The LAL-Spec mentions two distinct forms the documentation must take: stand-alone documentation for a single package and a comprehensive manual (with an exhaustive index and table of contents) for the entire LAL. In this section we describe how we implement these two competing documentation specifications using the same LATEX source to build both type of documents.
The requirement of both forms of the documentation in the LAL-Spec is not capricious: both forms of the documentation are useful. When you are working on a single package, having a short, single-package document is handy. This way you won't have to wait while LATEX runs on the complete manual for the entire LAL every time you want to see if your equations line up. On the other hand, as the LAL code becomes more mature and some of it starts to perform highly integrated tasks, it will be necessary for coders to have quick access to the entire body of documentation.
Documentation for a single package:
The guts of the documentation for a package (e.g. sample) should reside in the
file /lal/packages/samplepackage/doc/sample.tex.
This file may
itself have many \input{} commands in it to include files that
were auto extracted from the source-code files by laldoc.
When LAL is built, the file sample.tex will be automatically included in the file main.tex to build the stand alone documentation main.pdf for this (or any package). In other words, the file main.pdf in any lal/package/doc is the documentation for that package.
One problem you can have when you build the documentation of a single
package is that if their are references (\ref{}'s) to objects
outside the package, these will be left unresolved by LATEX. Try to
minimize these by referring to the objects by name rather than section
number. Remember, when the comprehensive document is built, it will
have a complete index and table of contents, so the reader should be
able to easily find the documentation for the objects by name.
Comprehensive manual for the entire LAL: In the comprehensive
documentation directory (/lal/doc) their is a file lsd.tex
(lsd = LAL Software Documentation). This plays essentially the
same role as main.tex described above; however this file has an
/include{} statement for every package in the LAL.