Though most applications and libraries have some documentation associated with them, some documentation is not associated with any particular software, and so lives in a component by itself. These components are principally the various cookbooks and system notes, though there are a few SUNs in this category as well. Though the correct way to handle such components should be fairly clear from the discussion above, it seems worth while to make a few remarks here to clear up some ambiguities.
Like any other component, a documentation-only component must have
a bootstrap file, and Makefile.am,
configure.ac and component.xml.in files, as
described in Section 4.1; however these will
typically be rather simple.
We can look at the SC/3 configuration files for an example.
The configure.ac file, shorn of most of its comments,
looks like this:
Note thednl Process this file with autoconf to produce a configure script AC_INIT(sc3, 2, ussc@star.rl.ac.uk) AC_PREREQ(2.50) AM_INIT_AUTOMAKE(1.8.2-starlink) AC_CONFIG_SRCDIR(sc3.tex) STAR_DEFAULTS(docs-only) STAR_LATEX_DOCUMENTATION(sc3) AC_CONFIG_FILES(Makefile component.xml) AC_OUTPUT
docs-only option to the
STAR_DEFAULTS macro (see Appendix A.17 for
discussion). This particular configure.ac file is to
handle document SC/3.2 -- this second edition of the document is
represented by the AC_INIT macro having a `version'
number of `2'.The Makefile.am file has some mild complications:
## Process this file with automake to produce Makefile.in
stardocs_DATA = @STAR_LATEX_DOCUMENTATION@
starexamples_DATA = $(distdir)-scripts.tar
sc3.htx_tar: sc3-scripts.tex
# sc3-scripts.tex is an appendix to the HTML version of the document,
# comprising the scripts contained in the scripts/ directory. These are
# also bundled in the htx tarball by virtue of being listed in the
# sc3.htx_tar.extras file.
sc3-scripts.tex: scripts
cd scripts; \
for f in *; do if test -f $$f; then \
echo $$f | sed 's/\([a-z0-9_]*\).*/\\subsection{\\label{se_\1_source}\\xlabel{\1}\1}/'; \
echo "\htmladdnormallink{Download $$f}{$$f}"; \
echo ''; \
echo '\begin{verbatim}'; \
cat $$f; \
echo '\end{verbatim}'; \
fi; done > ../$@
$(distdir)-scripts.tar: scripts
DN=$(distdir)-scripts; \
mkdir $$DN; \
for f in scripts/*; do if test -f $$f; then cp $$f $$DN; fi; done;\
tar cf $@ $$DN; \
rm -Rf $$DN
Makefile.am files is the
stardocs_DATA = @STAR_LATEX_DOCUMENTATION@ line, which
has exactly the same function described in Section 4.6 above. However cookbooks like SC/3 often have
both sets of examples (in this case, example scripts) and some
automatically generated documentation, and this example illustrates
how to describe both of these. The starexamples_DATA
line specifies a file which is to be installed in the examples
directory (typically /star/examples; see Appendix A.30), and the Makefile.am
therefore provides the rule for generating that tarball of
scripts.In addition, the sc3.tex file includes (in the TeX
sense) a generated file sc3-scripts.tex, which documents
these various scripts, and so we include in this
Makefile.am the rule for generating this file from the
contents of the scripts/ directory. We must also
indicate that the sc3.htx_tar file depends on this
generated file, and we do this by including that dependency (without
the build rule, which is generated automatically) in this
Makefile.am file.
Finally, note that this SC/3 directory uses the
.htx_tar.extra mechanism which is described rather in
passing in Appendix A.20.