28.9 Documentation

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.

28.9.1 Documentation Generation

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.

28.9.2 LATEX Files Generation

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

• ∖xProject (long form of the PROJECTNAME)
• ∖libraryname (LIBRARYNAME)
• ∖PROJECTNAME (PROJECTNAME)
• ∖projectname (projectname)
• ∖versionname (LIBPREFIX+LIBRARYNAME+version): Base name (without extension of an Aldor source file that contains version information for the library.
• ∖LIBRARYERSION
• ∖xMyAlps
• ∖allproselibraryname, and
• ∖ALLPROSELIBPROJECTNAME.
• ∖ALLPROSEVERSION.

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.

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.

However, if myalps.lsf does not yet exist or has a zero size, we simply use all source files.

Putting all together, we get the following. Note that

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

(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.

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.

28.9.3 Compilation of LATEX Files

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

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.

Generation of .bbl:

If there is not bibliography file, we have to generate it and to re-latex. If it is present and a new generation modifies it, then we also relatex. Otherwise, nothing is done.

383a⟨documentation: generate bibliography 383a⟩≡   (392b)  383b ⊳
$(projectname).bibliography:
        if [ -f $(projectname).bbl ]; then \
          $(CP) $(projectname).bbl tmp$$$$; \
          $(MAKE) bib; \
          if ! $(CMP) $(projectname).bbl tmp$$$$; then $(MAKE) $(TEXCMD); fi; \
          $(RM) tmp$$$$; \
        else \
          $(MAKE) bib $(TEXCMD); \
        fi

Uses CP 354a and projectname 127.

BibTEX should not be run on an empty file and it should also not be run if there is not yet any citation mentioned.

383b⟨documentation: generate bibliography 383a⟩+≡   (392b)  ⊲383a
bib: $(projectname).bib
        if $(GREP) ’^\\citation{’ $(projectname).aux > /dev/null; then\
            $(BIBTEX) $(projectname); fi

Uses BIBTEX 433b, GREP 354a, and projectname 127.

ToDo ⊲ 18 ⊳ We make bib dependent on the file myalps.bib.nw, in order to allow this file to be generated via some target in Makefile.def.nw.

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

Generation of .ind:

Similarly, we re-latex only if the .ind is not present or different from an old version. And we even do nothing at all if the file myalps.index exists. But note that we re-latex two times if the .ind file did not exist. This is necessary to get an Index entry into the table of contents in the XHTML generation.

384⟨documentation: generate index 384⟩≡   (392b)  385 ⊳
$(projectname).index:
        if [ -f $(projectname).ind ]; then \
          $(CP) $(projectname).ind tmp$$$$; \
          $(MAKE) $(TEXCMD).index; \
          if $(CMP) $(projectname).ind tmp$$$$; then \
            echo "EQUAL" > $@; \
          else \
            $(MAKE) $(TEXCMD); \
          fi; \
          $(RM) tmp$$$$; \
        else \
          $(MAKE) $(TEXCMD).index $(TEXCMD); \
          $(MAKE) $(TEXCMD).index $(TEXCMD); \
        fi

Uses CP 354a and projectname 127.

The actual generation of the .ind file is simple for LATEX and PDFLATEX.

385⟨documentation: generate index 384⟩+≡   (392b)  ⊲384  390 ⊳
LATEX.index PDFLATEX.index:
        if [ -f $(projectname).idx ]; then $(MAKEINDEX) $(projectname).idx; fi

Uses LATEX 433b, MAKEINDEX 433b, PDFLATEX 433b, and projectname 127.

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.¹⁹ 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.

390⟨documentation: generate index 384⟩+≡   (392b)  ⊲385  391a ⊳
$(projectname).rhx:
        echo ’\def\yeshasBar#1|#2!*?: #3{%’ > $@
        echo ’  \immediate\write\idx{\indexentry\the\split{%’ >> $@
        echo ’    #1|rhxLNK{#2}{\file}{\anchor}{\pointer}}{\the\entryNum’ >> $@
        echo ’}}%’ >> $@
        echo ’  \immediate\write\indexes{\string \indexmark\the\split{%’ >> $@
        echo ’    #2}{\the\entryNum’ >> $@
        echo ’}}}’ >> $@
        echo ’\def\INPUTSOURCE#1#2#3#4{\input #1.idx}’ >> $@
        echo ’\expandafter\INPUTSOURCE\filename\relax’ >> $@

Uses projectname 127.

With this twist the generation of myalps.ind looks relatively easy.

391a⟨documentation: generate index 384⟩+≡   (392b)  ⊲390
HTLATEX.index:
        if [ -f $(projectname).idx ]; then \
          $(MAKE) $(projectname).rhx; \
          $(TEX) ’\def\filename{{$(projectname)}{rhx}{4dx}{ind}}\input idxmake.4ht’;\
          $(MAKEINDEX) $(projectname).4dx;\
        fi

Uses HTLATEX 434a, MAKEINDEX 433b, projectname 127, and TEX 434a.

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.