automake-1.16: Texinfo
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 should have the ‘.texi’ extension. Automake
also accepts ‘.txi’ or ‘.texinfo’ extensions, but their use is
discouraged now, and will elicit runtime warnings.
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.
It is worth noting that, contrary to what happens with the other
formats, the generated ‘.info’ files are by default placed in ‘srcdir’
rather than in the ‘builddir’. This can be changed with the
‘info-in-builddir’ option.
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 of these targets can be extended using ‘-local’ rules (⇒
Extending).
If the ‘.texi’ file ‘@include’s ‘version.texi’, then that file will
be automatically generated. The file ‘version.texi’ defines four
Texinfo flags 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.
Often an Info file depends on more than one ‘.texi’ file. For
instance, in GNU Hello, ‘hello.texi’ includes the file ‘fdl.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 = fdl.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’ (⇒Finding
‘configure’ Input (autoconf)Input.), 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’.
By default, ‘make install-info’ and ‘make uninstall-info’ will try to
run the ‘install-info’ program (if available) to update (or
create/remove) the ‘${infodir}/dir’ index. If this is undesired, it can
be prevented by exporting the ‘AM_UPDATE_INFO_DIR’ variable to "‘no’".
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 (⇒User Variables) 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
Info Catalog
automake-1.16: Documentation
automake-1.16: Man Pages