[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Automake provides a few facilities to make the maintenance of Texinfo documentation within projects much simpler than it used to be. Writing a ‘Makefile.am’ for Texinfo documentation is extremely straightforward:
The ‘TEXINFOS’ primary will not only create rules for generating ‘.info’ files suitable for browsing with the GNU info reader, but also for generating ‘.dvi’ and ‘.ps’ documentation for printing.
You can also create other formats of documentation by adding the
appropriate make
rules to ‘Makefile.am’. For example,
because the more recent Texinfo distributions have begun to support
generation of HTML documentation from the ‘.texi’ format master
document, I have added the appropriate rules to the ‘Makefile.am’:
For ease of maintenance, these make
rules employ a suffix rule
which describes how to generate HTML from equivalent ‘.texi’ source
– this involves telling make about the ‘.html’ suffix using the
automake SUFFIXES
macro. I haven’t defined ‘MAKEINFO’
explicitly (though I could have done) because I know that Automake has
already defined it for use in the ‘.info’ generation rules.
The ‘html’ target is for convenience; typing ‘make html’ is a
little easier than typng ‘make sic.html’. I have also added a
.PHONY
target so that featureful make
programs will
know that the ‘html’ target doesn’t actually generate a file called
literally, ‘html’. As it stands, this code is not quite complete,
since the toplevel ‘Makefile.am’ doesn’t know how to call the
‘html’ rule in the ‘doc’ subdirectory.
There is no need to provide a general solution here in the way Automake does for its ‘dvi’ target, for example. A simple recursive call to ‘doc/Makefile’ is much simpler:
docdir = $(top_builddir)/doc html: @echo Making $@ in $(docdir) @cd $(docdir) && make $@ |
Another useful management function that Automake can perform for you
with respect to Texinfo documentation is to automatically generate the
version numbers for your Texinfo documents. It will add make
rules to generate a suitable ‘version.texi’, so long as
automake
sees ‘@include version.texi’ in the body of the
Texinfo source:
‘version.texi’ sets Texinfo variables, ‘VERSION’,
‘EDITION’ and ‘UPDATE’, which can be expanded elsewhere in the
main Texinfo documentation by using @value{EDITION}
for
example. This makes use of another auxiliary file, mdate-sh
which will be added to the scripts in the $ac_aux_dir
subdirectory by Automake after adding the ‘version.texi’ reference
to ‘sic.texi’:
$ ./bootstrap + aclocal -I config + libtoolize --force --copy Putting files in AC_CONFIG_AUX_DIR, config. + autoheader + automake --add-missing --copy doc/Makefile.am:22: installing config/mdate-sh + autoconf $ make html /bin/sh ./config.status --recheck ... Making html in ./doc make[1]: Entering directory /tmp/sic/doc Updating version.texi makeinfo --html sic.texi make[1]: Leaving directory /tmp/sic/doc |
Hopefully, it now goes without saying that I also need to add the ‘doc’ subdirectory to ‘AC_OUTPUT’ in ‘configure.in’ and to ‘SUBDIRS’ in the top-level ‘Makefile.am’.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated by Ben Elliston on July 10, 2015 using texi2html 1.82.