11. Building documentation

Currently Automake provides support for Texinfo and man pages.

11.1 Texinfo

If the current directory contains Texinfo source, you must declare it with the TEXINFOS primary. Generally Texinfo files are converted into info, and thus the info_TEXINFOS variable is most commonly used here. Any Texinfo source file must end in the `.texi', `.txi', or `.texinfo' extension. We recommend `.texi' for new manuals.

Automake generates rules to build `.info', `.dvi', `.ps', `.pdf' and `.html' files from your Texinfo sources. Following the GNU Coding Standards, only the `.info' files are built by `make all' and installed by `make install' (unless you use `no-installinfo', see below). Furthermore, `.info' files are automatically distributed so that Texinfo is not a prerequisite for installing your package.

Other documentation formats can be built on request by `make dvi', `make ps', `make pdf' and `make html', and they can be installed with `make install-dvi', `make install-ps', `make install-pdf' and `make install-html' explicitly. `make uninstall' will remove everything: the Texinfo documentation installed by default as well as all the above optional formats.

All these targets can be extended using `-local' rules (see section Extending Automake Rules).

If the `.texi' file @includes `version.texi', then that file will be automatically generated. The file `version.texi' defines four Texinfo flag you can reference using @value{EDITION}, @value{VERSION}, @value{UPDATED}, and @value{UPDATED-MONTH}.

EDITION

VERSION

Both of these flags hold the version number of your program. They are kept separate for clarity.

UPDATED

This holds the date the primary `.texi' file was last modified.

UPDATED-MONTH

This holds the name of the month in which the primary `.texi' file was last modified.

The `version.texi' support requires the mdate-sh script; this script is supplied with Automake and automatically included when automake is invoked with the `--add-missing' option.

If you have multiple Texinfo files, and you want to use the `version.texi' feature, then you have to have a separate version file for each Texinfo file. Automake will treat any include in a Texinfo file that matches `vers*.texi' just as an automatically generated version file.

Sometimes an info file actually depends on more than one `.texi' file. For instance, in GNU Hello, `hello.texi' includes the file `gpl.texi'. You can tell Automake about these dependencies using the texi_TEXINFOS variable. Here is how GNU Hello does it:

info_TEXINFOS = hello.texi
hello_TEXINFOS = gpl.texi

By default, Automake requires the file `texinfo.tex' to appear in the same directory as the `Makefile.am' file that lists the `.texi' files. If you used AC_CONFIG_AUX_DIR in `configure.ac' (see (autoconf)Input section `Finding `configure' Input' in The Autoconf Manual), then `texinfo.tex' is looked for there. In both cases, automake then supplies `texinfo.tex' if `--add-missing' is given, and takes care of its distribution. However, if you set the TEXINFO_TEX variable (see below), it overrides the location of the file and turns off its installation into the source as well as its distribution.

The option `no-texinfo.tex' can be used to eliminate the requirement for the file `texinfo.tex'. Use of the variable TEXINFO_TEX is preferable, however, because that allows the dvi, ps, and pdf targets to still work.

Automake generates an install-info rule; some people apparently use this. By default, info pages are installed by `make install', so running make install-info is pointless. This can be prevented via the no-installinfo option. In this case, `.info' files are not installed by default, and user must request this explicitly using `make install-info'.

The following variables are used by the Texinfo build rules.

MAKEINFO

The name of the program invoked to build `.info' files. This variable is defined by Automake. If the makeinfo program is found on the system then it will be used by default; otherwise missing will be used instead.

MAKEINFOHTML

The command invoked to build `.html' files. Automake defines this to `$(MAKEINFO) --html'.

MAKEINFOFLAGS

User flags passed to each invocation of `$(MAKEINFO)' and `$(MAKEINFOHTML)'. This user variable (see section Variables reserved for the user) is not expected to be defined in any `Makefile'; it can be used by users to pass extra flags to suit their needs.

AM_MAKEINFOFLAGS

AM_MAKEINFOHTMLFLAGS

Maintainer flags passed to each makeinfo invocation. Unlike MAKEINFOFLAGS, these variables are meant to be defined by maintainers in `Makefile.am'. `$(AM_MAKEINFOFLAGS)' is passed to makeinfo when building `.info' files; and `$(AM_MAKEINFOHTMLFLAGS)' is used when building `.html' files.

For instance, the following setting can be used to obtain one single `.html' file per manual, without node separators.

AM_MAKEINFOHTMLFLAGS = --no-headers --no-split

AM_MAKEINFOHTMLFLAGS defaults to `$(AM_MAKEINFOFLAGS)'. This means that defining AM_MAKEINFOFLAGS without defining AM_MAKEINFOHTMLFLAGS will impact builds of both `.info' and `.html' files.

TEXI2DVI

The name of the command that converts a `.texi' file into a `.dvi' file. This defaults to `texi2dvi', a script that ships with the Texinfo package.

TEXI2PDF

The name of the command that translates a `.texi' file into a `.pdf' file. This defaults to `$(TEXI2DVI) --pdf --batch'.

DVIPS

The name of the command that builds a `.ps' file out of a `.dvi' file. This defaults to `dvips'.

TEXINFO_TEX

If your package has Texinfo files in many directories, you can use the variable TEXINFO_TEX to tell Automake where to find the canonical `texinfo.tex' for your package. The value of this variable should be the relative path from the current `Makefile.am' to `texinfo.tex':

TEXINFO_TEX = ../doc/texinfo.tex

11.2 Man Pages

A package can also include man pages (but see the GNU standards on this matter, (standards)Man Pages section `Man Pages' in The GNU Coding Standards.) Man pages are declared using the MANS primary. Generally the man_MANS variable is used. Man pages are automatically installed in the correct subdirectory of mandir, based on the file extension.

File extensions such as `.1c' are handled by looking for the valid part of the extension and using that to determine the correct subdirectory of mandir. Valid section names are the digits `0' through `9', and the letters `l' and `n'.

Sometimes developers prefer to name a man page something like `foo.man' in the source, and then rename it to have the correct suffix, for example `foo.1', when installing the file. Automake also supports this mode. For a valid section named SECTION, there is a corresponding directory named `manSECTIONdir', and a corresponding _MANS variable. Files listed in such a variable are installed in the indicated section. If the file already has a valid suffix, then it is installed as-is; otherwise the file suffix is changed to match the section.

For instance, consider this example:

man1_MANS = rename.man thesame.1 alsothesame.1c

In this case, `rename.man' will be renamed to `rename.1' when installed, but the other files will keep their names.

By default, man pages are installed by `make install'. However, since the GNU project does not require man pages, many maintainers do not expend effort to keep the man pages up to date. In these cases, the `no-installman' option will prevent the man pages from being installed by default. The user can still explicitly install them via `make install-man'.

For fast installation, with many files it is preferable to use `manSECTION_MANS' over `man_MANS' as well as files that do not need to be renamed.

Man pages are not currently considered to be source, because it is not uncommon for man pages to be automatically generated. Therefore they are not automatically included in the distribution. However, this can be changed by use of the dist_ prefix. For instance here is how to distribute and install the two man pages of GNU cpio (which includes both Texinfo documentation and man pages):

dist_man_MANS = cpio.1 mt.1

The nobase_ prefix is meaningless for man pages and is disallowed.

Executables and manpages may be renamed upon installation (see section Renaming Programs at Install Time). For manpages this can be avoided by use of the notrans_ prefix. For instance, suppose an executable `foo' allowing to access a library function `foo' from the command line. The way to avoid renaming of the `foo.3' manpage is:

man_MANS = foo.1
notrans_man_MANS = foo.3

`notrans_' must be specified first when used in conjunction with either `dist_' or `nodist_' (see section Fine-grained Distribution Control). For instance:

notrans_dist_man3_MANS = bar.3

This document was generated on July, 20 2009 using texi2html 1.76.