Back: Installing Header Files
Forward: Adding a Test Suite
FastBack: Adding a Test Suite
Up: A Large GNU Autotools Project
FastForward: Rolling Distribution Tarballs
Top: Autoconf, Automake, and Libtool
Contents: Table of Contents
Index: Index
About: About this document

12.4 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 `' for Texinfo documentation is extremely straightforward:

## Process this file with automake to produce

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 `'. 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 `':

SUFFIXES                = .html

html_docs               = sic.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 `' 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

        @echo Making [email protected] in $(docdir)
        @cd $(docdir) && make [email protected]

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
@settitle Dynamic Modular Interpreter Prototyping
@setchapternewpage odd
@c %**end of header
@headings             double

@include version.texi

@dircategory Programming
* sic: (sic).    The dynamic, modular, interpreter prototyping tool.
@end direntry

This file documents sic.

@end ifinfo

@sp 10
@title Sic
@subtitle Edition @value{EDITION}, @value{UPDATED}
@subtitle $Id: autobook_97.html,v 1.7 2006/02/08 14:07:09 gvv Exp $
@author Gary V. Vaughan
@author @email{[email protected]}

@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/ 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 `' and to `SUBDIRS' in the top-level `'.

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html