There is fairly complete support for documentation within
the build system. Most Starlink documentation is in the
form of LaTeX files respecting certain conventions (see
SGP/28: Writing Starlink
documents and SUN/199:
Star2HTML for some further details), but a small
amount is in a custom XML DTD, converted using the kit contained in
the sgmlkit component, documented in SSN/70.
The simplest case is where you have one or more
.tex files in the component directory (that is,
the directory which contains the component.xml
file). In this case, you simply declare the document
numbers, and the files named after them, in a
STAR_LATEX_DOCUMENTATION macro, as in:
This will put these document codes into the substitution variableSTAR_LATEX_DOCUMENTATION([sun123 sc99])
@STAR_DOCUMENTATION@, which you can
use to substitute in component.xml.in, and it
will arrange to compile the LaTeX files
sun123.tex and sc99.tex. This
macro is documented fully in Appendix A.20.The final step in this case is to declare that the
documentation is to be built and installed in the Starlink
documentation directory. You do that by including the
following line in the component's Makefile.am:
(see Appendix A.30). This substitution variable expands to the default list of documentation targets (at present comprisingstardocs_DATA = @STAR_LATEX_DOCUMENTATION@
.tex,
.ps and .htx_tar, but subject to
change in principle).The next simplest case is where the source files are in a different
directory from the component.xml. Indicate this by
appending a slash to the end of each of the document codes located
elsewhere. For example:
This will behave as above for theSTAR_LATEX_DOCUMENTATION([sun123/ sc99])
sc99.tex file, but
differently for the sun123 document. That code,
sun123 is still included in
@STAR_DOCUMENTATION@, but it is the variable
@STAR_LATEX_DOCUMENTATION_SUN123@ which is set to the
default target list, and not @STAR_LATEX_DOCUMENTATION@.
Documentation specified in this way does not -- contrary to
appearances -- have to live in a similarly named subdirectory of the
component directory; instead you will have to separately make sure that the
documentation is built at build time.Suppose, for example, you are managing the documentation for
the package which contains SUN/123, and suppose the source for this is
in a subdirectory docs/sun-cxxiii (whimsy is a terrible
thing), then you would still refer to the documentation via
STAR_LATEX_DOCUMENTATION(sun123/) as above, but in the
file docs/sun-cxxiii/Makefile.am you would include at
least the line
and make sure that directorystardocs_DATA = @STAR_LATEX_DOCUMENTATION_SUN123@
docs/sun-cxxiii is built,
and its contents installed when appropriate, by the usual method of
mentioning the directory in a SUBDIRS declaration in the
component Makefile.am:
TheSUBDIRS = docs/sun-cxxiii
datacube component uses this mechanism to build its
documentation.If you need to add extra files to the .htx tarball,
you can do so via the .extras file described in Appendix A.20.
Sometimes you need to do more elaborate things to build
your documentation -- the ast component is a
good example, here. In this case, you can give a non-null
second argument to the STAR_LATEX_DOCUMENTATION
macro, giving a list of makefile targets which should be
built. The document codes in the first argument are still
included in @STAR_DOCUMENTATION@, but the
second argument is included verbatim in
@STAR_LATEX_DOCUMENTATION@ without any
defaulting. You are responsible for adding the given
targets to the Makefile and, as before, you should add
@STAR_LATEX_DOCUMENTATION@ to the
stardocs_DATA Makefile variable.
If you have produced XML documentation, use the STAR_XML_DOCUMENTATION macro, which is closely analogous to the LaTeX one.