Several LATEX packages that are used for the documentation of this project. We list here the packages together with some commands that are defined in terms of the commands from the package.
Since the project uses Noweb to generate its documentation, we must load the noweb package.
We want the Noweb code to appear in ∖footnotesize, so we add an appropriate option in ∖noweboptions.
The command ∖nwindexdefn is generated by NOWEAVEX for identifiers that appear in a chunk. One can define the identifiers of a chunk in the .nw file by writing
%def id1 id2 id3
|
at the end of a chunk after the closing @ sign and a blank.
We introduce ∖rhxindexdefn here only to hold the original ∖nwindexdefn. The ∖defineterm command below does not print anything, see rhxterm.
If the current filename ends in .as.nw (∖ifAldorSource is true) then the definition is different than for other files.
Although completely optional, we want to allow colored backgrounds for certain environments. The LATEX package framed provides support for colored backgrounds and is used if it can be found. If it cannot be found, the background color settings will be ignored.
Note that we require at least a version from 0.8a on. Version 0.5 does not work.
Note also that we wrap everything into a ∖trivlist in order to get the spacing correct after the environment. We did not want an indentation of the line following immediately after the environment.
We provide here a command ∖backgroundColor to set the background color. It is flexible enough after a redefinition in allprose.4ht.nw to set the background color for the html output, too.
The command takes as the first argument the name of an environment and as the second argument a color description. The color description can be given in a format that is accepted by the ∖colorbox command from the LATEX color package.
For example, both of the following commands set the color red for the environment ToDo.
\backgroundColor{ToDo}{red}
\backgroundColor{ToDo}[rgb]{1.0,0,0} |
We do not use the package aldoc (by Niklaus Mannhart) at the moment, because we see no real advantage. Instead we use another package aldordoc which is described in Section 25.1.
Note that for the rest of this section we assume that the page style allprose is active when the command ∖rhead is used, see Section 24.4.
We like to put the name of the currently defined object into the right header of the compiled documentation. Therefore, we redefine the appropriate commands ∖addefinetype and ∖adinternaldefinename accordingly.
For ∖addefinetype this is easy.
All API (application programming interface) documentation comments that are meant to correspond to Aldor +++ descriptions should be written into the +++ environment
\begin{+++}
... \end{+++} |
At the moment this environment does nothing spectacular, but is necessary for the script tools/aldordoc2codechunk.pl.nw that takes this environment and embeds it as +++ descriptions to the <<exports: ...>> code chunk immediately following the +++ environment.
The background color of the +++ environment can be configured via the command ∖backgroundColor{aldordoc}{...} at a local customization (see Section 24.12).
The documentation should become a hyperlinked document. The hyperref package supports links inside the whole document.
The package rhxterm takes advantage of hyperref and provides the commands ∖defineterm and ∖useterm. In fact, it is an extra package by Ralf Hemmecke (ralf@hemmecke.de).
We decided to take this package instead of the noweb way with double brackets in order to have more flexibility. In fact, the index indicates where ∖defineterm is used.
For the special purpose of defining and using LATEX commands, we define ∖definetexcommand and ∖usetexcommand as special versions of ∖defineterm and ∖useterm. They should be used in the documentation like
\definetexcommand{SOMECOMMAND}
\usetexcommand{SOMECOMMAND} |
to refer to the LATEX command \SOMECOMMAND.
In order to refer to Makefile targets in the text, we provide the command ∖usemaketarget. Targets should be defined via the %def mechanism of Noweb.
The hyperref package usually loads the standard packages keyval and url.
The command ∖email is used to put a hyperlink to an email address.
The url package provides some simple commands to enter verbatim like text. We use
url.sty ver 1.4 02-Mar-1999 Donald Arseneau asnd@triumf.ca
|
but version 1.5 should also work.
It defines (among others) the command ∖path. The command ∖directory builds on this package.
Code in the documentation that is not part of a chunk should be typeset by using the verbatim environment. One could change the fontsize by redefining the \verbatim@font command from the verbatim package, but we decided to redefine the whole verbatim environment in order to enable background colors.
The command ∖verbatiminput is used to include the generated file src/Makefile.dep.
We highlight verbatim environments via the ColoredBackground environment, see Section 24.3.2.
The background color of the verbatim environment and the ∖verbatiminput command can be configured via the commands ∖backgroundColor{verbatim}{...} and ∖backgroundColor{verbatiminput}{...} at a local customization (see Section 24.12).
Some remark to the seemingly strange definition of ∖verbatiminput. Our original definition was
\renewcommand{\verbatiminput}[1]{{%
\def\FrameCommand{\backgroundverbatiminput}\MakeFramed{}% \footnotesize\allproseverbatiminput{#1}\endMakeFramed}} |
but TEX4ht stopped with the following error message.
(/usr/share/texmf/tex/generic/tex4ht/verbatim.4ht
! Argument of \verbatiminput has an extra }. <inserted text> \par l.32 \:gobble} |
After careful analysis, it became obvious that verbatim.4ht very much relied on the original definition of ∖verbatiminput as defined in verbatim.sty which begins with ∖begingroup. So we have to mimic that definition.
The makeidx package is mainly used in connection with the rhxterm package. The command ∖makeindex is defined in the makeidx package.
For mathematical environments and other nice features we load the amsmath and amssymb packages.
The program kdvi as well as newer versions of xdvi (see DVIVIEWER) are able to inverse search14 a dvi file, i. e., by clicking on some place in the .dvi file, the corresponding .tex file is opened in an editor of your choice. It is middle mouse click for kdvi and holding the control key and pressing the left mouse button for xdvi15 .
Inverse search is not possible by default. Certain versions of TEX support the generation of ∖special commands that have to be put into the .dvi file. For example, teTeX 2.0 offers a -src switch.
Since, however, our source files do not have the extension .tex but rather .nw, we use the package srcltx. After having contacted Stefan Ulrich, the current maintainer of that package, it is now released as
\ProvidesPackage{srcltx}[2006/11/12 v1.6]
|
and contains a hook ∖srcInputHook, which allows to control the name of the source file that is written into the .dvi file.
Since version 1.6 is probably not yet widely distributed, we still provide our old ad-hoc patch for versions 1.4 and 1.5.
Through the command ∖SOURCEROOT, we even offer to specify a relative or absolute path to the source tree. This path is written into the .dvi file. See also Section 28.9.2.
Note that the command ∖SOURCEROOT is defined only later in project.def.tex and so we must delay the test whether it is defined or not until we actually need it.
That the modification is so simple comes from our design of how to generate the .tex files and the fact that LATEX automatically appends the extension .tex for the argument to ∖input. (Note that we never use ∖include in ALLPROSE.)
The package srcltx is not really necessary (although strongly suggested), so we include it only, if it exists.
Note also that we cannot simply put the reference to the patch inside the ∖IfFileExists command, since this leads to some strange LATEX error.