28.9 Documentation

  28.9.1 Documentation Generation
  28.9.2 LATEX Files Generation
  28.9.3 Compilation of LATEX Files

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.

360documentation 360  (346)
documentation: doc file generation 361
documentation: latex compilation 387b

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.

361documentation: doc file generation 361  (360)  362
VERBATIMINPUT=showexports project.def.tex allprosefiles.list

Uses allprosefiles.list 403 and showexports 370.

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.

362documentation: doc file generation 361+   (360)  361  365a
AN=$(ALLPROSELIBPROJECTNAME)
LIBRARYVERSION=$(MAJORVERSION).$(MINORVERSION).$(PATCHVERSION)
ALLPROSEVERSION=$(ALLPROSEMAJORVERSION).$(ALLPROSEMINORVERSION).$(ALLPROSEPATCHVERSION)
project.def.tex: Makefile.def.nw Makefile.nw code ChangeLog
        @echo "% project.def.tex generated by Makefile.nw"     >$@
        @echo "\\def\\xProject{\\csname x$(PROJECTNAME)\\endcsname}">>$@
        @echo "\\def\\libraryname{$(LIBRARYNAME)}"            >>$@
        @echo "\\def\\PROJECTNAME{$(PROJECTNAME)}"            >>$@
        @echo "\\def\\projectname{$(projectname)}"            >>$@
        @echo "\\def\\SOURCEROOT{$(PROJECTROOT)}"             >>$@
        @echo ""                                              >>$@
        @echo "\\def\\versionname{$(LIBPREFIX)$(LIBRARYNAME)version}">>$@
        @echo "\\def\\LIBRARYVERSION{$(LIBRARYVERSION)}"             >>$@
        @echo "\\def\\ALLPROSEVERSION{$(ALLPROSEVERSION)}"           >>$@
        @echo ""                                                     >>$@
        @echo "\\xnamedef{$(AN)}{http://www.hemmecke.de/aldor}"      >>$@
        @echo "\\def\\allproselibraryname{$(ALLPROSELIBRARYNAME)}"      >>$@
        @echo "\\def\\ALLPROSELIBPROJECTNAME{$(ALLPROSELIBPROJECTNAME)}">>$@
        documentation: date 363             >>$@
        @echo "\\makeatletter"              >>$@
        @echo "\\input{$(projectname).sty}" >>$@
        @echo "\\makeatother"               >>$@
        $(CREATEIFNOTTHERE) $(projectname).sty

Defines:
ALLPROSEVERSION, used in chunk 410.
LIBRARYVERSION, used in chunks 21, 217a, 415a, and 419.

Uses ALLPROSELIBPROJECTNAME 346, ALLPROSELIBRARYNAME 346, ALLPROSEMAJORVERSION 346, ALLPROSEMINORVERSION 346, ALLPROSEPATCHVERSION 346, code 432, CREATEIFNOTTHERE 429a, LIBPREFIX 124, LIBRARYNAME 124, MAJORVERSION 124, MINORVERSION 124, PATCHVERSION 124, PROJECTNAME 124, projectname 124, PROJECTROOT 346, and xnamedef 233.

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.

363documentation: date 363  (362)
$(PERL) \
  -e ’open(CL, "ChangeLog") || die "Cannot open ChangeLog";’ \
  -e ’$$firstline=<CL>;’ \
  PERL set NAMEVERSION 415a \
  -e ’if(0==index $$firstline, $$NAMEVERSION){’ \
  -e ’  $$D=substr $$firstline, length $$NAMEVERSION;’ \
  -e ’  if($$D=~/^ (\d\d-[A-Z][a-z][a-z]-\d\d\d\d) --$$/){’ \
  -e ’    print "\\date{$$1}\n";’ \
  -e ’  }’ \
  -e ’}’ \
  -e ’close CL;’

Uses PERL 427b.

The file project.def.tex defines the commands

and is shown below.

% project.def.tex generated by Makefile.nw  
\def\xProject{\csname xMyAlps\endcsname}  
\def\libraryname{myalps}  
\def\PROJECTNAME{MyAlps}  
\def\projectname{myalps}  
\def\SOURCEROOT{/home/hemmecke/SVK/HOME/trunk/projects/Software/allprose}  
 
\def\versionname{mymyalpsversion}  
\def\LIBRARYVERSION{0.2.6}  
\def\ALLPROSEVERSION{0.2.6}  
 
\xnamedef{MyAlps}{http://www.hemmecke.de/aldor}  
\def\allproselibraryname{myalps}  
\def\ALLPROSELIBPROJECTNAME{MyAlps}  
\date{16-Dec-2007}  
\makeatletter  
\input{myalps.sty}  
\makeatother

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.

365adocumentation: doc file generation 361+   (360)  362  365b
texfiles: fileslist
        $(MAKE) $(shell $(PERL) -pe ’s/$$/.nw.filtered/’ files.list)
        call NOWEAVEX on the concatenation of filtered files 368a | \
        split the resulting output into the corresponding .tex files 368b

Defines:
texfiles, used in chunks 376 and 377.

Uses fileslist 435 and PERL 427b.
365bdocumentation: doc file generation 361+   (360)  365a  366b
%.as.nw.filtered: %.as.nw $(TOOLS)/nwescape.pl
        @echo "Pre-Filtering $*.as.nw [as]..."
        $(NWESCAPE) $*.as.nw | \
        $(PERL) $(TOOLS)/addaldortypedef.pl | \
        $(PERL) $(TOOLS)/aldordoc2tex.pl |\
        Add space+% after each lonely code ending @ sign 366c\
            > $@

Uses NWESCAPE 433a, nwescape.pl 433a, PERL 427b, and TOOLS 423b.
ToDo 16 The following code chunk is a quick hack to remove the documentation part from .as files.
366aUNUSED: documentation: doc file generation 366a
%.as.nw.filtered: %.as.nw $(TOOLS)/nwescape.pl
        @echo "Pre-Filtering $*.as.nw [as]..."
        $(NWESCAPE) $*.as.nw | \
        $(PERL) $(TOOLS)/api.pl | \
        $(PERL) $(TOOLS)/addaldortypedef.pl | \
        $(PERL) $(TOOLS)/aldordoc2tex.pl \
            > $*.as.nw.filtered

Uses NWESCAPE 433a, nwescape.pl 433a, PERL 427b, and TOOLS 423b.
366bdocumentation: doc file generation 361+   (360)  365b  370
%.nw.filtered: %.nw $(TOOLS)/nwescape.pl
        @echo "Pre-Filtering $*.nw ..."
        $(NWESCAPE) $*.nw | \
        $(PERL) $(TOOLS)/aldordoc2tex.pl |\
        Add space+% after each lonely code ending @ sign 366c\
            > $@

Uses NWESCAPE 433a, nwescape.pl 433a, PERL 427b, and TOOLS 423b.

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.

366cAdd space+% after each lonely code ending @ sign 366c  (365b 366b)
$(PERL) -ne ’if(/^@\s*$$/){print "@ %\n"}else{print}’

Uses PERL 427b.

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.

367adocumentation files 367a  (368a)
$(PERL) \
        -e ’while(<>){’ \
        -e ’    /^\\SourceFile \{(.*)\}$$/;’ \
        -e ’    $$filename=$$1;’ \
        -e ’    if ($$filename=~/\.bib$$/) {next}’ \
        -e ’    print "$$filename.nw.filtered\n";’ \
        -e ’}’ $(projectname).lsf

Uses PERL 427b and projectname 124.
However, if myalps.lsf does not yet exist or has a zero size, we simply use all source files.
367ball filtered files 367b  (368a)
$(PERL) -pe ’s/$$/.nw.filtered/’ files.list

Uses PERL 427b.
Putting all together, we get the following. Note that
-s file  
     True if file exists and has a size greater than zero.

368acall NOWEAVEX on the concatenation of filtered files 368a  (365a)
$(NOWEAVEX) $(shell \
  if [ -s $(projectname).lsf ]; then \
    documentation files 367a;\
  else\
    all filtered files 367b;\
  fi)

Uses NOWEAVEX 349a and projectname 124.
368bsplit the resulting output into the corresponding .tex files 368b  (365a)
$(PERL) -e ’$$openfile=0;’\
        -e ’while (<>) {’\
        -e ’    chomp;’\
        -e ’    $$line=$$_;’\
        -e ’    if ($$line =~ /^(.*)(\\nwfilename{([^}]+))\.filtered(}.*)/) {’\
        -e ’        $$rest=$$1;’\
        -e ’        $$filename=$$3;’\
        -e ’        $$line="$$2$$4";’\
        -e ’        if ($$openfile) {print DF "$$rest\n"; close DF;}’\
        -e ’        open(DF, ">$$filename.tex");’\
        -e ’    }’\
        -e ’    print DF "$$line\n";’\
        -e ’}’\
        -e ’if ($$openfile) {print DF "$$rest\n"; close DF;}’

Uses PERL 427b.

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.

Convention 21 For the generation of the files with extension .exports.tex, we rely on the fact that types (categories, domains, packages) that provide explicit exports in the the form of
<<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.

370documentation: doc file generation 361+   (360)  366b  371
showexports: fileslist
        -$(RM) Makefile.showexports
        $(PERL) \
            -e ’while(<>) {’\
            -e ’    chomp;’\
            -e ’    if (! (/\.as$$/)) {next}’\
            -e ’    $$filename="$$_.nw";’\
            -e ’    open(SF, "$$filename.filtered");’\
            -e ’    while (<SF>) {’\
            -e ’        if (/^\\showexports{((\.|\w)+)}/) {’\
            -e ’            print "TYPEEXPORTS+=$$1\n";’\
            -e ’            print "$$1.exports.tex: $$filename\n";’\
            -e ’        }’\
            -e ’    }’\
            -e ’    close(SF);’\
            -e ’}’ \
          files.list >> Makefile.showexports
        $(MAKE) generateexports

#This is only a dummy definition if no exports are available.
Makefile.showexports:
        echo "" > $@

include Makefile.showexports

generateexports: $(TYPEEXPORTS:%=%.exports.tex)

Defines:
generateexports, never used.
showexports, used in chunks 230, 361, 390, 479, and 482.

Uses fileslist 435 and PERL 427b.

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.

371documentation: doc file generation 361+   (360)  370
%.exports.tex:
        $(MAKE) $(TOOLS)/nwescape.pl
        $(PERL) $(TOOLS)/aldordoc2codechunk.pl $< | \
        $(NWESCAPE) | $(NOTANGLE) -R"exports: $(*:extend.%=%)" | \
        $(PERL) $(TOOLS)/showexports2aldordoc.pl $(*:extend.%=%) | \
        $(PERL) $(TOOLS)/aldordoc2tex.pl > $@

Uses NOTANGLE 348, NWESCAPE 433a, nwescape.pl 433a, PERL 427b, and TOOLS 423b.
ToDo 17 Note that for extensions of domains the generated .exports.tex file starts with extend. including the dot.

The file Makefile.showexports is the following.

TYPEEXPORTS+=MyAdditiveType  
MyAdditiveType.exports.tex: src/myalps/arith.as.nw  
TYPEEXPORTS+=MyArithmeticType  
MyArithmeticType.exports.tex: src/myalps/arith.as.nw  
TYPEEXPORTS+=MyBinaryPowering  
MyBinaryPowering.exports.tex: src/myalps/binpow.as.nw  
TYPEEXPORTS+=MyCopyableType  
MyCopyableType.exports.tex: src/myalps/copy.as.nw  
TYPEEXPORTS+=MyPrimitiveType  
MyPrimitiveType.exports.tex: src/myalps/prtype.as.nw  
TYPEEXPORTS+=MyVersionInformationType  
MyVersionInformationType.exports.tex: src/myalps/version.as.nw

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.

372documentation: toplevel targets dvi ps pdf html 372  (387b)  373a
documentation: toplevel target: dvi 374a
documentation: toplevel target: ps 373b
documentation: toplevel target: pdf 374b
documentation: toplevel target: html 375

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

373adocumentation: toplevel targets dvi ps pdf html 372+   (387b)  372
DOCDIR=$(PROJECTROOT)/doc
docdir:
        $(MDparent) $(DOCDIR)

Defines:
DOCDIR, used in chunks 373–75.

Uses MDparent 428 and PROJECTROOT 346.

The generation of a postscript file is done in the usual way.

373bdocumentation: toplevel target: ps 373b  (372)
dvips: dvi
        $(DVIPS) $(projectname).dvi

ps: dvips docdir
        $(CP) $(projectname).ps $(DOCDIR)
        @echo
        @echo "$(PSVIEWER) $(DOCDIR)/$(projectname).ps &"
        @echo

Defines:
ps, used in chunks 408 and 418.

Uses CP 350a, DOCDIR 373a, dvi 374a, DVIPS 430b, projectname 124, and PSVIEWER 430b.

The generation of .dvi and .pdf nearly agree, only that for the first we call LATEX and for the latter we call PDFLATEX.

374adocumentation: toplevel target: dvi 374a  (372)
dvi:
        $(MAKE) TEXCMD=LATEX latex.all docdir
        $(CP) $(projectname).dvi $(DOCDIR)
        @echo
        @echo "$(DVIVIEWER) $(DOCDIR)/$(projectname).dvi &"
        @echo

Defines:
dvi, used in chunk 373b.

Uses all 346, CP 350a, DOCDIR 373a, DVIVIEWER 430b, LATEX 429b, latex.all 377, and projectname 124.
374bdocumentation: toplevel target: pdf 374b  (372)
pdf:
        $(MAKE) TEXCMD=PDFLATEX latex.all docdir
        $(CP) $(projectname).pdf $(DOCDIR)
        @echo
        @echo "$(PDFVIEWER) $(DOCDIR)/$(projectname).pdf &"
        @echo

Defines:
pdf, used in chunks 408 and 418.

Uses all 346, CP 350a, DOCDIR 373a, latex.all 377, PDFLATEX 429b, PDFVIEWER 430b, and projectname 124.

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.

375documentation: toplevel target: html 375  (372)
html:
        $(MAKE) TEXCMD=HTLATEX latex.all docdir tex4htpostprocess
        $(CP) $(projectname)*.html $(DOCDIR)
        $(CP) $(projectname)*.css  $(DOCDIR)
        -$(CP) $(projectname)*.png  $(DOCDIR)
        @echo
        @echo "$(HTMLVIEWER) $(DOCDIR)/$(projectname).html &"
        @echo

tex4htpostprocess:
        $(TEX4HT) -f/$(projectname) -cmozhtf
        $(T4HT) -f/$(projectname) -cvalidate
        -$(RM) $(projectname).err
        -xmllint --noout --valid --html *.html 2> $(projectname).err
        -(if [ -s $(projectname).err ]; then \
          echo "================================";\
          echo "ERROR in checking generated HTML";\
          echo "See $(projectname).err.         ";\
          echo "================================";\
        else\
          echo "=================";\
          echo "Generated HTML OK";\
          echo "=================";\
        fi)


Defines:
html, used in chunks 234, 332, 408, and 418.

Uses all 346, CP 350a, DOCDIR 373a, HTLATEX 430a, HTMLVIEWER 430b, latex.all 377, projectname 124, T4HT 430a, and TEX4HT 430a.

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.

376documentation: prepare texfiles 376  (387b)
$(projectname).lsf:
        $(MAKE) $(TEXCMD) texfiles undocumented

Uses projectname 124, texfiles 365a, and undocumented 436.

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.

377documentation: run LaTeX process as often as necessary 377  (387b)
latex.all: code allprose.sty $(projectname).sty texfiles docfiles
        -$(RM) $(projectname).trace
        -$(RM) $(projectname).index
        $(MAKE) $(projectname).lsf
        $(MAKE) $(TEXCMD)
        $(MAKE) $(projectname).bibliography
        $(MAKE) $(projectname).index
        $(MAKE) $(projectname).index
        @echo ===========================================================
#       -@$(GREP) -i warning $(projectname).log | sort | uniq
        -$(PERL) -e ’while(<>){if(/warning/i){$$A{$$_}=1}}’\
                 -e ’for $$l (sort keys %A){print $$l}’ $(projectname).log
        @echo ===========================================================

Defines:
latex.all, used in chunks 374 and 375.

Uses all 346, code 432, docfiles 434, GREP 350a, PERL 427b, projectname 124, and texfiles 365a.

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.
378adocumentation: generate bibliography 378a  (387b)  378b
$(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 350a and projectname 124.
BibTEX should not be run on an empty file and it should also not be run if there is not yet any citation mentioned.
378bdocumentation: generate bibliography 378a+   (387b)  378a
bib: $(projectname).bib
        if $(GREP) ’^\\citation{’ $(projectname).aux > /dev/null; then\
            $(BIBTEX) $(projectname); fi

Uses BIBTEX 429b, GREP 350a, and projectname 124.
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.
379documentation: generate index 379  (387b)  380
$(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 350a and projectname 124.

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

380documentation: generate index 379+   (387b)  379  385
LATEX.index PDFLATEX.index:
        if [ -f $(projectname).idx ]; then $(MAKEINDEX) $(projectname).idx; fi

Uses LATEX 429b, MAKEINDEX 429b, PDFLATEX 429b, and projectname 124.

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.

385documentation: generate index 379+   (387b)  380  386a
$(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 124.

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

386adocumentation: generate index 379+   (387b)  385
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 430a, MAKEINDEX 429b, projectname 124, and TEX 430a.

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.

386bdocumentation: run LaTeX once 386b  (387b)
# Generate files using latex, pdflatex, or latex in tex4ht variant.
LATEXARGS   =
PDFLATEXARGS=
HTLATEXARGS =’\makeatletterTEX4HT hook 387a\makeatother\input ’
LATEX PDFLATEX HTLATEX:
        echo $@ $(projectname).tex;\
        if ! $($@) --interaction nonstopmode $($(@)ARGS) $(projectname).tex \
            >> $(projectname).trace; then \
          echo ============================================;\
          echo $@ did not succeed.;\
          echo A trace was written to $(projectname).trace.;\
          echo Consult also $(projectname).log.;\
          exit 1;\
        fi

Defines:
HTLATEXARGS, never used.

Uses HTLATEX 430a, LATEX 429b, PDFLATEX 429b, and projectname 124.

We want to split the HTML output at section and subsection level and want to provide frames. See Section 27.3 for the configuration.

387aTEX4HT hook 387a  (386b)
\g@addto@macro\@documentclasshook{\RequirePackage[xhtml,3,frames,next]{tex4ht}}

Now we put together all the code parts.

387bdocumentation: latex compilation 387b  (360)
documentation: toplevel targets dvi ps pdf html 372
documentation: prepare texfiles 376
documentation: run LaTeX process as often as necessary 377
documentation: generate bibliography 378a
documentation: generate index 379
documentation: run LaTeX once 386b