Including Texinfo Documentation

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:

## Process this file with automake to produce Makefile.in MAINTAINERCLEANFILES = Makefile.in info_TEXINFOS = sic.texi

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:

SUFFIXES = .html html_docs = sic.html .texi.html: $(MAKEINFO) --html $< .PHONY: html html: version.texi $(html_docs)

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:

\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename sic.info @settitle Dynamic Modular Interpreter Prototyping @setchapternewpage odd @c %**end of header @headings double @include version.texi @dircategory Programming @direntry * sic: (sic). The dynamic, modular, interpreter prototyping tool. @end direntry @ifinfo This file documents sic. @end ifinfo @titlepage @sp 10 @title Sic @subtitle Edition @value{EDITION}, @value{UPDATED} @subtitle $Id: sic.texi,v 1.4 2000/05/23 09:07:00 bje Exp $ @author Gary V. Vaughan @author @email{gvv@@techie.com} @page @vskip 0pt plus 1filll @end titlepage

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.