The documentation is generated from the .nw files.
The following junk basically contains the targets connected to the generation of a pdf, dvi, ps, or html form of the documentation.
It basically assumes via the target texfiles that all documentation files have been extracted from the Noweb format to a LATEX format. It then compiles the file myalps.tex.nw (projectname.tex) as many times as necessary. If a file myalps.idx is available, then it will be processed by MAKEINDEX. The file myalps.idx will be generated by LATEX if the command \makeindex appears in the preamble of myalps.tex.nw. ALLPROSE switches it on right after loading the package makeidx in allprose.sty.nw.
A file project.def.tex will be generated that transforms some variables from Makefile.def.nw and Makefile.nw into a LATEX form. It also includes the ∖date command if an appropriate date can be extracted from the first line of the ChangeLog file. This file together with the style file of the project, myalps.sty.nw (projectname.sty) is included in allprose.sty.nw, see Section 24.11.
In order to check whether all source files are mentioned in myalps.tex.nw, we use the target undocumented) to generate the file undocumented.tex.
See docfiles. The variable VERBATIMINPUT list all the files in this directory that appear inside a ∖verbatiminput command. In fact, the target showexports will (re-)generate the file Makefile.showexports which is included here.
We generated also a file project.def.tex that contains definitions of certain LATEX commands.
Note that the definition of \x$(PN) (∖xMyAlps) must be given in the file myalps.sty.nw (projectname.sty). Additional styles can be given in that file.
The dependency code is there to ensure that myalps.sty.nw has already been built (if there is a corresponding .nw file).
We use ∖LIBRARYVERSION in order to put it into the title of the documentation and ∖ALLPROSEVERSION for the description of ALLPROSE.
We patch the srcltx package in Section 24.3.9 in order to enable the inverse search. Since the .dvi file could be moved to some other place in the directory structure, we have to write an absolute path of the source .nw files into the .dvi file so that inverse search still refers to the original place of the source files. The command ∖SOURCEROOT is used for this purpose.
Depending on whether or not the first line of the ChangeLog file is in a format as set by the release-date MAKE target, a ∖date is written to standard output.
The file project.def.tex defines the commands
and is shown below.
Let us start with the generation of the LATEX files. In contrast to a code that was demonstrated up to version 1.47 of this Makefile.nw, we mention now all .nw files on the command line of NOWEAVEX and split the resulting .tex file by the following Perl script into the corresponding .tex files. Thus we take advantage of the cross-referencing feature of NOWEAVE.
Since in Aldor the << function appears quite often, it would be troublesome to escape it each time by an @ sign to <<. Not escaping it results in NOWEAVEX returning with error code 1. That would, however, stop the building process of the documentation. Thus instead of ignoring such an error (and possibly others), we call a filter program to escape the << and >> if they appear unpaired and un-escaped by prepending them with an @ sign.
The same problem occurs for NOTANGLE.
A single @ on one line or @␣ with at most spaces following switches to document mode. However, in contrast to the 3 character sequence, a ∖nwdocspar will be added right after ∖nwbegindocs.
at the beginning of a line to switch to document mode. We rather like to swallow also the newline.
Only those source files should appear as arguments to NOWEAVEX that are actually used in the documentation. Unfortunately, since the documentation of ALLPROSE might not be included, we do not know the files until the file myalps.lsf exists, i. e., after the first successful run of LATEX.
Note that according to Convention 13 files with certain extensions are not automatically included even if they appear inside a ∖SourceFile command. In particular, files with extension .bib.nw are skipped.
The correct list of files we get from the following code chunk.
-s file
True if file exists and has a size greater than zero. |
The .as.nw files follow the convention given in Section 8. In particular for each ∖showexports command that starts at the beginning of a line, a corresponding file is included in the text that contains the exports of a corresponding domain, package, or category.
The idea to generate these files is as follows. Each ∖showexports line in a .as.nw file will be translated into a line of the form
TYPENAME.exports.tex: dir/filename.as.nw
|
(where TYPENAME is the argument of the ∖showexports command) written to Makefile.showexports.
Note in the code below that instead of the original .as.nw file, the generated file with extension .as.nw.filtered is taken as input. Note also that in the generation of the .filtered file the script tools/addaldortypedef.pl.nw might have added some ∖showexports commands.
<<exports: TYPENAME>>
|
chunks are unique, i. e., there should not be two types with different parameter lists and different exports since we only generate one corresponding .exports.tex file.
Note that $< in the following target corresponds to a file given through Makefile.showexports. In particular, as can be seen from Makefile.showexports, $< corresponds to a .as.nw file.
The file Makefile.showexports is the following.
The remaining part is connected to producing the documentation from the .tex files. There are various formats that can be produced.
The documentation is first generated into the directory given by PROJECTROOT and finally copied to the directory specified by the variable DOCDR. One could even produce a documentation that is copied outside the PROJECTROOT by saying something like
make DOCDIR=/some/interesting/directory dvi
|
The generation of a postscript file is done in the usual way.
The generation of .dvi and .pdf nearly agree, only that for the first we call LATEX and for the latter we call PDFLATEX.
For the generation of HTML TEX4ht, i. e., HTLATEX. A postprocess is required after calling LATEX in order to extract the HTML code from a .dvi file.
In order to get the references correct, LATEX has to be run several times to stabilize the output.
If we start from a clean situation (distclean), then the first LATEX run just compiles the core documentation and generates the file myalps.lsf.
Since only after this file exists, it will be clear which files and in which order are included in the documentation, we have to run the target texfiles for the generation of .tex files (including cross references) again.
Similarly, for checking whether there are some undocumented files, the file myalps.lsf is necessary.
If myalps.lsf is present, we call the appropriate latex command. Then compile the bibliography and latex again, if necessary. Similarly, we then compile the index, and latex again if the index file has changed. Usually after checking the index a second time and re-latex the output will be stable.
Note that latex is at least called once and at most five times. If files from previous runs are sufficiently close, it might happen that the following process completes, by calling latex only once.
Also note that we generate the bibliography, then latex, and only after that generate the index and latex. For some strange reason, there appeared an overflow of TEX’s memory during HTLATEX if the index was generated too early. The reason was not further investigated since simply moving the index generation one stage back solved the size problem.
Before we come to the actual latex call, let us deal with the conditional generation of the .bbl file and the .ind file.
Note that ALLPROSE requires the existence of a file myalps.bib.nw.
The file Makefile.def.nw could, for example define something like the following.
$(projectname).bib: sometarget
sometarget: somedependency generatebib > $(projectname).bib |
The actual generation of the .ind file is simple for LATEX and PDFLATEX.
Note that in the case of html production via TEX4ht the rules for the index are slightly different. These commands are suggested in a warning message of TEX4ht.
l.23 --- TeX4ht warning --- If not done so, the index is to be processed by
tex ’\def\filename{{myalps}{idx}{4dx}{ind}} \input idxmake.4ht’ makeindex -o myalps.ind myalps.4dx instead of makeindex -o myalps.ind myalps.idx |
Unfortunately, TEX4ht has some problems with the correct generation of index entries.19 In the .idx file we see something like
\indexentry{=@\adcodefont {=}!\adcodefont {MyPrimitiveType}|defineTermPage}{153}
\indexentry{=@\adcodefont {=}!\adcodefont {MyPrimitiveType}}{153} |
which are translated by TEX call from above into something like
\indexentry{=@\adcodefont {=}!\adcodefont
{MyPrimitiveType}\let\LNKidx\defineTermPage|LNK{myalpsse18.html}% {dx51-41009}{}}{936} \indexentry{=@\adcodefont {=}!\adcodefont {MyPrimitiveType}|LNK{myalpsse18.html}{dx51-41012}{}}{939} |
However, with that definition, there will be two entries.
Since both indexentries should become just two page number links in the printed form, we have to modify idxmake.4ht. Instead of
\def\yeshasBar#1|#2!*?: #3{%
\immediate\write\idx{\indexentry\the\split{% #1\string\let\string\LNKidx\expandafter\string\csname #2\endcsname|LNK{\file}{\anchor}{\pointer}}{\the\entryNum }}% \immediate\write\indexes{\string \indexmark\the\split{% #2}{\the\entryNum }}% } |
we use
\def\yeshasBar#1|#2!*?: #3{%
\immediate\write\idx{\indexentry\the\split{% #1|rhxLNK{#2}{\file}{\anchor}{\pointer}}{\the\entryNum }}% \immediate\write\indexes{\string \indexmark\the\split{% #2}{\the\entryNum }}% } |
i. e., we use the command ∖rhxLNK to take care of the the case where the index link is beautified by a command. See also Section 27.7.
Unfortunately, we cannot easily patch idxmake.4ht, so we simply load a generated file myalps.rhx instead of myalps.idx which redefines an appropriate command from idxmake.4ht before it loads myalps.idx.
With this twist the generation of myalps.ind looks relatively easy.
All what is left is an appropriate LATEX call.
The whole LATEX compilation is logged by LATEX itself into myalps.log. Additionally the standard output of LATEX is redirected into myalps.trace.
We want to split the HTML output at section and subsection level and want to provide frames. See Section 27.3 for the configuration.
Now we put together all the code parts.