automake: Texinfo

1 
1 11.1 Texinfo
1 ============
1 
1 If the current directory contains Texinfo source, you must declare it
1 with the ‘TEXINFOS’ primary.  Generally Texinfo files are converted into
1 info, and thus the ‘info_TEXINFOS’ variable is most commonly used here.
1 Any Texinfo source file should have the ‘.texi’ extension.  Automake
1 also accepts ‘.txi’ or ‘.texinfo’ extensions, but their use is
1 discouraged now, and will elicit runtime warnings.
1 
1    Automake generates rules to build ‘.info’, ‘.dvi’, ‘.ps’, ‘.pdf’ and
1 ‘.html’ files from your Texinfo sources.  Following the GNU Coding
1 Standards, only the ‘.info’ files are built by ‘make all’ and installed
1 by ‘make install’ (unless you use ‘no-installinfo’, see below).
1 Furthermore, ‘.info’ files are automatically distributed so that Texinfo
1 is not a prerequisite for installing your package.
1 
1    It is worth noting that, contrary to what happens with the other
1 formats, the generated ‘.info’ files are by default placed in ‘srcdir’
1 rather than in the ‘builddir’.  This can be changed with the
1 ‘info-in-builddir’ option.
1 
1    Other documentation formats can be built on request by ‘make dvi’,
1 ‘make ps’, ‘make pdf’ and ‘make html’, and they can be installed with
1 ‘make install-dvi’, ‘make install-ps’, ‘make install-pdf’ and ‘make
1 install-html’ explicitly.  ‘make uninstall’ will remove everything: the
1 Texinfo documentation installed by default as well as all the above
1 optional formats.
1 
11    All of these targets can be extended using ‘-local’ rules (⇒
 Extending).
1 
1    If the ‘.texi’ file ‘@include’s ‘version.texi’, then that file will
1 be automatically generated.  The file ‘version.texi’ defines four
1 Texinfo flags you can reference using ‘@value{EDITION}’,
1 ‘@value{VERSION}’, ‘@value{UPDATED}’, and ‘@value{UPDATED-MONTH}’.
1 
1 ‘EDITION’
1 ‘VERSION’
1      Both of these flags hold the version number of your program.  They
1      are kept separate for clarity.
1 
1 ‘UPDATED’
1      This holds the date the primary ‘.texi’ file was last modified.
1 
1 ‘UPDATED-MONTH’
1      This holds the name of the month in which the primary ‘.texi’ file
1      was last modified.
1 
1    The ‘version.texi’ support requires the ‘mdate-sh’ script; this
1 script is supplied with Automake and automatically included when
1 ‘automake’ is invoked with the ‘--add-missing’ option.
1 
1    If you have multiple Texinfo files, and you want to use the
1 ‘version.texi’ feature, then you have to have a separate version file
1 for each Texinfo file.  Automake will treat any include in a Texinfo
1 file that matches ‘vers*.texi’ just as an automatically generated
1 version file.
1 
1    Sometimes an info file actually depends on more than one ‘.texi’
1 file.  For instance, in GNU Hello, ‘hello.texi’ includes the file
1 ‘fdl.texi’.  You can tell Automake about these dependencies using the
1 ‘TEXI_TEXINFOS’ variable.  Here is how GNU Hello does it:
1 
1      info_TEXINFOS = hello.texi
1      hello_TEXINFOS = fdl.texi
1 
1    By default, Automake requires the file ‘texinfo.tex’ to appear in the
1 same directory as the ‘Makefile.am’ file that lists the ‘.texi’ files.
11 If you used ‘AC_CONFIG_AUX_DIR’ in ‘configure.ac’ (⇒Finding
 ‘configure’ Input (autoconf)Input.), then ‘texinfo.tex’ is looked for
1 there.  In both cases, ‘automake’ then supplies ‘texinfo.tex’ if
1 ‘--add-missing’ is given, and takes care of its distribution.  However,
1 if you set the ‘TEXINFO_TEX’ variable (see below), it overrides the
1 location of the file and turns off its installation into the source as
1 well as its distribution.
1 
1    The option ‘no-texinfo.tex’ can be used to eliminate the requirement
1 for the file ‘texinfo.tex’.  Use of the variable ‘TEXINFO_TEX’ is
1 preferable, however, because that allows the ‘dvi’, ‘ps’, and ‘pdf’
1 targets to still work.
1 
1    Automake generates an ‘install-info’ rule; some people apparently use
1 this.  By default, info pages are installed by ‘make install’, so
1 running ‘make install-info’ is pointless.  This can be prevented via the
1 ‘no-installinfo’ option.  In this case, ‘.info’ files are not installed
1 by default, and user must request this explicitly using ‘make
1 install-info’.
1 
1    By default, ‘make install-info’ and ‘make uninstall-info’ will try to
1 run the ‘install-info’ program (if available) to update (or
1 create/remove) the ‘${infodir}/dir’ index.  If this is undesired, it can
1 be prevented by exporting the ‘AM_UPDATE_INFO_DIR’ variable to "‘no’".
1 
1    The following variables are used by the Texinfo build rules.
1 
1 ‘MAKEINFO’
1      The name of the program invoked to build ‘.info’ files.  This
1      variable is defined by Automake.  If the ‘makeinfo’ program is
1      found on the system then it will be used by default; otherwise
1      ‘missing’ will be used instead.
1 
1 ‘MAKEINFOHTML’
1      The command invoked to build ‘.html’ files.  Automake defines this
1      to ‘$(MAKEINFO) --html’.
1 
1 ‘MAKEINFOFLAGS’
1      User flags passed to each invocation of ‘$(MAKEINFO)’ and
1      ‘$(MAKEINFOHTML)’.  This user variable (⇒User Variables) is
1      not expected to be defined in any ‘Makefile’; it can be used by
1      users to pass extra flags to suit their needs.
1 
1 ‘AM_MAKEINFOFLAGS’
1 ‘AM_MAKEINFOHTMLFLAGS’
1      Maintainer flags passed to each ‘makeinfo’ invocation.  Unlike
1      ‘MAKEINFOFLAGS’, these variables are meant to be defined by
1      maintainers in ‘Makefile.am’.  ‘$(AM_MAKEINFOFLAGS)’ is passed to
1      ‘makeinfo’ when building ‘.info’ files; and
1      ‘$(AM_MAKEINFOHTMLFLAGS)’ is used when building ‘.html’ files.
1 
1      For instance, the following setting can be used to obtain one
1      single ‘.html’ file per manual, without node separators.
1           AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
1 
1      ‘AM_MAKEINFOHTMLFLAGS’ defaults to ‘$(AM_MAKEINFOFLAGS)’.  This
1      means that defining ‘AM_MAKEINFOFLAGS’ without defining
1      ‘AM_MAKEINFOHTMLFLAGS’ will impact builds of both ‘.info’ and
1      ‘.html’ files.
1 
1 ‘TEXI2DVI’
1      The name of the command that converts a ‘.texi’ file into a ‘.dvi’
1      file.  This defaults to ‘texi2dvi’, a script that ships with the
1      Texinfo package.
1 
1 ‘TEXI2PDF’
1      The name of the command that translates a ‘.texi’ file into a
1      ‘.pdf’ file.  This defaults to ‘$(TEXI2DVI) --pdf --batch’.
1 
1 ‘DVIPS’
1      The name of the command that builds a ‘.ps’ file out of a ‘.dvi’
1      file.  This defaults to ‘dvips’.
1 
1 ‘TEXINFO_TEX’
1 
1      If your package has Texinfo files in many directories, you can use
1      the variable ‘TEXINFO_TEX’ to tell Automake where to find the
1      canonical ‘texinfo.tex’ for your package.  The value of this
1      variable should be the relative path from the current ‘Makefile.am’
1      to ‘texinfo.tex’:
1 
1           TEXINFO_TEX = ../doc/texinfo.tex
1