texinfo: @setfilename

Texinfo File Header

@settitle

Start of Header

Back to Software Index

3.2.3 '@setfilename': Set the Output File Name
----------------------------------------------

The first Texinfo command (that is, after the '\input texinfo') in a
document is generally '@setfilename':

     @setfilename INFO-FILE-NAME

  This command is required for TeX, and very strongly recommended for
'makeinfo'.

  Write the '@setfilename' command at the beginning of a line and follow
it on the same line by the Info file name.  Do not write anything else
on the line.

  When an '@setfilename' line is present, the Texinfo processors ignore
everything written before the '@setfilename' line.  This is why the very
first line of the file (the '\input' line) does not show up in the
output.

  The '@setfilename' line specifies the name of the output file to be
generated.  This name must be different from the name of the Texinfo
file.  There are two conventions for choosing the name: you can either
remove the extension (such as '.texi') entirely from the input file
name, or (recommended) replace it with the '.info' extension.

  Although an explicit '.info' extension is preferable, some operating
systems cannot handle long file names.  You can run into a problem even
when the file name you specify is itself short enough.  This occurs
because the Info formatters split a long Info file into short indirect
subfiles, and name them by appending '-1', '-2', ..., '-10', '-11', and
so on, to the original file name.  (Note: Tag and Split Files.)  The
subfile name 'texinfo.info-10', for example, is too long for old systems
with a 14-character limit on filenames; so the Info file name for this
document is 'texinfo' rather than 'texinfo.info'.  When 'makeinfo' is
running on operating systems such as MS-DOS which impose severe limits
on file names, it may remove some characters from the original file name
to leave enough space for the subfile suffix, thus producing files named
'texin-10', 'gcc.i12', etc.

  When producing another output format, 'makeinfo' will replace any
final extension with the output format-specific extension ('html' when
generating HTML, for example), or add a dot followed by the extension
('.html' for HTML) if the given name has no extension.

  The '@setfilename' line produces no output when you typeset a manual
with TeX, but it is nevertheless essential: it opens the index and other
auxiliary files used by Texinfo, and also reads 'texinfo.cnf' if that
file is present on your system (Note: Preparing for TeX).

  If there is no '@setfilename' line, 'makeinfo' uses the input file
name to determine the output name: first, any of the extensions '.texi',
'.tex', '.txi' or '.texinfo' is removed from the input file name; then,
the output format specific extension is added--'.html' when generating
HTML, '.info' when generating Info, etc.  The '\input' line is still
ignored in this processing, as well as leading blank lines.

  See also the '--output' option in Note: Invoking texi2any.