STAR_LATEX_DOCUMENTATION(documentcode, [targets=''])
Generate the standard makefile targets to handle LaTeX
documentation source. The
parameter documentcode should be a
space-separated list of codes like `sun123' -- they must
not include any .tex extension. Each of the
documentcodes may optionally be followed by a slash, to
indicate that the source file is not in the current
directory; see below.
The second, optional, argument gives an explicit list
of the targets which are build. If this is not
specified, then a standard list is used
(.tex, .ps and
.tar_htx at present, though this is in
principle subject to change) and corresponding rules added to
the generated makefile. If it is specified, it must be
non-null, and its value is a list of files which are to be
added to the distribution, and no extra Makefile rules are
added. Thus if users need anything complicated done, they
should use this second argument and provide rules for
satisfying the given targets.
In the latter case, the .tex -> htx_tar rule
is still emitted, so you can use it, but it requires the
substitution variable @STAR2HTML@, and so if
you do use it, you will have to make that
available, either through
STAR_CHECK_PROGS(star2html) or otherwise (see
Appendix A.14). If you need to tune the
parameters used when running the star2html command,
then assign these to the STAR2HTML_FLAGS
macro in Makefile.am.
The default rule for compiling LaTeX files simply runs LaTeX
twice. If you need to do more than this -- for example to
run BibTeX or make an index -- then you can override this
by setting the variable LATEX2DVI in the
configure.ac file; it is already substituted
with a default value, so you don't have to call
AC_SUBST on it. This variable should refer
to LaTeX as $$LATEX, and use
$$1 to refer to the root of the
LaTeX file to be compiled (that is, the filename with
any .tex extension removed). The doubled dollar
signs are because this is evaluated within the context of
a `make' rule. Thus if you needed to run
BibTeX between the LaTeX runs, you would define:
LATEX2DVI='$$LATEX $$1; bibtex $$1; $$LATEX $$1'
This macro defines the substitution variable
@STAR_LATEX_DOCUMENTATION@ to be the second
macro argument if that is present, or the default target
list if not. This variable must therefore be used as a value
for the stardocs_DATA Makefile variable (see
Appendix A.30).
If any documentcode is followed by a slash,
then the default target list is assigned to
@STAR_LATEX_DOCUMENTATION_<DOCUMENTCODE>@
instead; you may not use this latter feature if the second
argument is non-null.
See Section 4.6 for more discussion of this feature, plus an example.
The configure option
--without-stardocs
suppresses building documenation.
It is occasionally necessary to add extra files to the
.htx tarball -- for example .gif images, or
other files referenced by the HTML version of the documentation. To
request that extra files should be added to the
starnnn.htx_tar archive, you should create a file
starnnn.htx_tar.extras listing the filenames which should be included,
separated by whitespace (spaces, tabs or newlines).