Autoconf, Automake, and Libtool: Including Texinfo Documentation

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

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