This manual is for GNU Texinfo (version 7.3, 1 March 2026), a
documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

   Copyright © 1988-2026 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".

11 Special Insertions
*********************

Texinfo provides several commands for inserting characters that have
special meaning in Texinfo, such as braces, and for other graphic
elements that do not correspond to simple characters you can type.

11.1 Special Characters: Inserting @ {} , \ # &
===============================================

‘@’ and curly braces are the basic special characters in Texinfo.  To
insert these characters so they appear in text, you must put an ‘@’ in
front of these characters to prevent Texinfo from misinterpreting them.
Alphabetic commands are also provided.

   The other characters (comma, backslash, hash, ampersand) are special
only in restricted contexts, as explained in the respective sections.

11.1.1 Inserting '@' with ‘@@’ and ‘@atchar{}’
----------------------------------------------

‘@@’ produces a single ‘@’ character in the output.  Do not put braces
after an ‘@@’ command.

   ‘@atchar{}’ also produces a single ‘@’ character in the output.  It
does need following braces, as usual for alphabetic commands.  In inline
conditionals (see Inline Conditionals), it can be necessary to avoid
using the literal ‘@’ character in the source (and may be clearer in
other contexts).

11.1.2 Inserting '{ '}' with ‘@{ @}’ and ‘@l rbracechar{}’
----------------------------------------------------------

‘@{’ produces a single ‘{’ in the output, and ‘@}’ produces a single
‘}’.  Do not put braces after either an ‘@{’ or an ‘@}’ command.

   ‘@lbracechar{}’ and ‘@rbracechar{}’ also produce single ‘{’ and ‘}’
characters in the output.  They do need following braces, as usual for
alphabetic commands.  In inline conditionals (see Inline Conditionals),
it can be necessary to avoid using literal brace
characters in the source (and may be clearer in other contexts).

11.1.3 Inserting ',' with ‘@comma{}’
------------------------------------

Ordinarily, a comma ',' is a normal character that can be simply typed
in your input where you need it.

   However, Texinfo uses the comma as a special character only in one
context: to separate arguments to those Texinfo commands, such as
‘@node’ (see Node Line Requirements), ‘@acronym’ (see @acronym)
and ‘@xref’ (see Cross References), as well as user-defined macros
(see Defining Macros), which take more than one argument.

   Since a comma character would confuse Texinfo's parsing for these
commands, you must use the command ‘@comma{}’ instead if you want to
pass an actual comma.  Here are some examples:

     @acronym{ABC, A Bizarre @comma{}}
     @xref{Comma,, The @comma{} symbol}
     @mymac{One argument@comma{} containing a comma}

   Although ‘@comma{}’ can be used nearly anywhere, there is no need for
it anywhere except in this unusual case.

   (Incidentally, the name ‘@comma’ lacks the ‘char’ suffix used in its
companion commands only for historical reasons.  It didn't seem
important enough to define a synonym.)

11.1.4 Inserting '\' with ‘@backslashchar{}’
--------------------------------------------

Ordinarily, a backslash '\' is a normal character in Texinfo that can be
simply typed in your input where you need it.  The result is to typeset
the backslash from the typewriter font.

   However, Texinfo uses the backslash as a special character in one
restricted context: to delimit formal arguments in the bodies of
user-defined macros (see Defining Macros).

   Due to the vagaries of macro argument parsing, it is more reliable to
pass an alphabetic command that produces a backslash instead of using a
literal \.  Hence ‘@backslashchar{}’.  Here is an example macro call:

     @mymac{One argument@backslashchar{} with a backslash}

   Texinfo documents may also use \ as a command character inside
‘@math’ (see Inserting Math).  In this case, ‘@\’ or ‘\backslash’
produce a "math" backslash (from the math symbol font), while
‘@backslashchar{}’ produces a typewriter backslash as usual.

   Although ‘@backslashchar{}’ can be used nearly anywhere, there is no
need for it except in these unusual cases.

11.1.5 Inserting '#' with ‘@hashchar{}’
---------------------------------------

Ordinarily, a hash '#' is a normal character in Texinfo that can be
simply typed in your input where you need it.  The result is to typeset
the hash character from the current font.

   This character has many other names, varying by locale, such as
"number sign", "pound", and "octothorp".  It is also sometimes called
"sharp" or "sharp sign" since it vaguely resembles the musical symbol by
that name.  In situations where Texinfo is used, "hash" is the most
common in our experience.

   However, Texinfo uses the hash character as a special character in
one restricted context: to introduce the so-called ‘#line’ directive and
variants (see External Macro Processors).

   So, in order to typeset an actual hash character in such a place (for
example, in a program that needs documentation about ‘#line’), it's
necessary to use ‘@hashchar{}’ or some other construct.  Here's an
example:

     @hashchar{} 10 "example.c"

   Although ‘@hashchar{}’ can be used nearly anywhere, there is no need
for it anywhere except this unusual case.

11.1.6 Inserting '&' with ‘@&’ and ‘@ampchar{}’
-----------------------------------------------

Ordinarily, an ampersand '&' is a normal character in Texinfo that can
be simply typed in your input where you need it.  The result is to
typeset the ampersand character.

   However, the ampersand character is treated specially in just one
restricted context.  In the argument to a definition command (see
Definition Commands), an ampersand followed by a series of letters may
be typeset specially when processing with TeX(1) (see Def Cmd Conventions).
For example:

     @defun foo integer1 &optional integer2 &rest integers
     @code{foo} described here.
     @end defun

may have ‘&optional’ and ‘&rest’ formatted in bold, even without any
@-command involved.

   So, in order to typeset an ampersand in such a context, it's
necessary to use ‘@&’ or some other construct.  Here's an example of a
C++ function taking a reference as a parameter:

     @deftypefn Function int foo (const std::vector<int>@& @var{bar})
     Documentation of @code{foo}.
     @end deftypefn

This gives the output

 -- Function: int foo (const std::vector<int>& BAR)
     Documentation of ‘foo’.

   Although ‘@&’ and ‘@ampchar{}’ can be used nearly anywhere, there is
no need for them anywhere except this unusual case.

   ---------- Footnotes ----------

   (1) This syntax is used for Emacs Lisp keywords.  See A Sample Function Description (elisp).

11.2 Inserting Quote Characters
===============================

As explained in the early section on general Texinfo input conventions
(see Conventions), Texinfo source files use the ASCII character ‘`’
(96 decimal) to produce a left quote ('), and ASCII ‘'’ (39 decimal) to
produce a right quote (').  Doubling these input characters (‘``’ and
‘''’) produces double quotes (" and ").  These are the conventions used
by TeX.

   In examples of computer code, however, ‘`’ and ‘'’ produce typical
renderings for these ASCII characters: the backtick character
(standalone grave accent) and undirected single quote respectively.  In
the past, directed glyphs were used by default in TeX output.  Texinfo
provides these commands to choose between these alternate renderings:

‘@codequoteundirected ON-OFF’
     Set to ‘off’ to output the ‘'’ character in code environments as
     the right curly single quote.

‘@codequotebacktick ON-OFF’
     Set to ‘off’ to output the ‘`’ character in code environments as
     the left curly single quote.

   If you want these settings for only part of the document,
‘@codequote... on’ will restore the normal behavior, as in
‘@codequoteundirected on’.

   These settings affect ‘@code’, ‘@example’, ‘@kbd’, ‘@samp’, ‘@verb’,
and ‘@verbatim’.  See Useful Highlighting.

   Unfortunately, some document viewers will mangle the directed quote
characters when copying and pasting.  (The free PDF reader ‘xpdf’ works
fine, but other PDF readers, both free and nonfree, have problems.)

   This feature can also be controlled by using ‘@set’ and ‘@clear’ on
the corresponding variables ‘txicodequoteundirected’ and
‘txicodequotebacktick’.

11.3 Inserting Space
====================

The following sections describe commands that control spacing of various
kinds within and after sentences.

11.3.1 Multiple Spaces
----------------------

Ordinarily, multiple whitespace characters (space, tab, and newline) are
collapsed into a single space.

   Occasionally, you may want to produce several consecutive spaces,
either for purposes of example (e.g., what your program does with
multiple spaces as input), or merely for purposes of appearance in
headings or lists.  Texinfo supports three commands: ‘@SPACE’, ‘@TAB’,
and ‘@NL’, all of which insert a single space into the output.  (Here,
‘@SPACE’ represents an ‘@’ character followed by a space, i.e., ‘@ ’,
‘TAB’ represents an actual tab character, and ‘@NL’ represents an ‘@’
character and end-of-line, i.e., when ‘@’ is the last character on a
line.)

   For example,
     Spacey@ @ @ @
     example.

produces

     Spacey    example.

   Do not follow any of these commands with braces.

   To produce a non-breakable space, see @tie.

11.3.2 Not Ending a Sentence
----------------------------

When a period, exclamation point or question mark is at the end of a
sentence, slightly more space is inserted after it in a typeset manual.

   Usually, Texinfo can determine automatically when a period ends a
sentence.  However, special commands are needed in some circumstances.
Use the ‘@:’ command after a period, question mark, exclamation mark or
colon that should not be followed by extra space.  This is necessary in
the following situations:

  1. After a period that ends a lowercase abbreviation which is not at
     the end of a sentence.

  2. When a parenthetical remark in the middle of a sentence (like this
     one!) ends with a period, exclamation point or question mark, ‘@:’
     should be used after the right parenthesis.  Similarly for right
     brackets and right quotes (both single and double).

   For example:

     ‘foo vs.@: bar (or?)@: baz’,

The first line below shows the output, and for comparison, the second
line shows the spacing when the ‘@:’ commands were not used.

     foo vs. bar (or?) baz
     foo vs.  bar (or?)  baz

   It may help you to remember what ‘@:’ does by imagining that it
stands for an invisible lower-case character that stops a word ending in
a period.

   A few Texinfo commands force normal interword spacing, so that you
don't have to insert ‘@:’ where you otherwise would.  These are the
code-like highlighting commands, ‘@var’, ‘@abbr’, and ‘@acronym’ (see
Useful Highlighting).  For example, in ‘@code{foo. bar}’ the period is
not considered to be the end of a sentence, and no extra space is
inserted.

   ‘@:’ has no effect on the HTML or DocBook output.

11.3.3 Ending a Sentence
------------------------

As mentioned above, Texinfo normally inserts additional space after the
end of a sentence.  It uses the same heuristic for this as TeX: a
sentence ends with a period, exclamation point, or question mark, either
preceded or followed by optional closing punctuation, and then
whitespace, and _not_ preceded by a capital letter.

   Use ‘@.’ instead of a period, ‘@!’ instead of an exclamation point,
and ‘@?’ instead of a question mark at the end of a sentence that does
end with a capital letter.  Do not put braces after any of these
commands.  For example:

     Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.
     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.

The output follows.  In printed output and Info, you can see the desired
extra whitespace after the ‘W’ in the first line.

     Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
     Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.

   In other output formats, ‘@.’ is equivalent to a simple ‘.’; likewise
for ‘@!’ and ‘@?’.

   The "closing punctuation" mentioned above is defined as a right
parenthesis (‘)’, right bracket (‘]’), or right quote, either single or
double (‘'’ and ‘''’; the many possible additional Unicode right quotes
are not included).  These characters can be thought of as invisible with
respect to whether a given period ends a sentence.  (This is the same
rule as TeX.)  For instance, the periods in ‘foo.) Bar’ and ‘foo.'' Bar’
do end sentences.

   The meanings of ‘@:’ and ‘@.’, etc. in Texinfo are designed to work
well with the Emacs sentence motion commands (see Sentences (emacs)).
It may help to imagine that the ‘@’ in ‘@.’, etc., is an invisible
lower-case letter 'a' which makes an upper-case letter before it
immaterial for the purposes of deciding whether the period ends the
sentence.

   A few Texinfo commands are not considered as being an abbreviation,
even though they may end with a capital letter when expanded, so that
you don't have to insert ‘@.’ and companions.  Notably, this is the case
for code-like highlighting commands, ‘@var’ arguments ending with a
capital letter, ‘@LaTeX’, and ‘@TeX’.  For example, that sentence ended
with ‘... @code{@@TeX}.’; ‘@.’ was not needed.  Similarly, in ‘...
@var{VARNAME}. Text’ the period after VARNAME ends the sentence; there
is no need to use ‘@.’.

11.3.4 ‘@frenchspacing’ VAL: Control Sentence Spacing
-----------------------------------------------------

In American typography, it is traditional and correct to put extra space
at the end of a sentence.  This is the default in Texinfo (implemented
in Info and printed output, not in other output formats).  In French
typography (and others), this extra space is wrong; all spaces are
uniform.

   Therefore Texinfo provides the ‘@frenchspacing’ command to control
the spacing after punctuation.  It reads the rest of the line as its
argument, which must be the single word ‘on’ or ‘off’ (always these
words, regardless of the language of the document).  Here is an example:

     @frenchspacing on
     This is text. Two sentences. Three sentences. French spacing.

     @frenchspacing off
     This is text. Two sentences. Three sentences. Non-French spacing.

produces:

   This is text. Two sentences. Three sentences. French spacing.

   This is text.  Two sentences.  Three sentences.  Non-French spacing.

   ‘@frenchspacing’ also affects the output after ‘@.’, ‘@!’, and ‘@?’
(see Ending a Sentence).

   ‘@frenchspacing’ has no effect on the HTML or DocBook output.

11.3.5 ‘@dmn’{DIMENSION}: Format a Dimension
--------------------------------------------

You can use the ‘@dmn’ command to format a dimension with just enough
space for proper typesetting inserted in printed output.  In other
output formats, the formatting commands insert no space at all.

   To use the ‘@dmn’ command, write the number and then follow it
immediately, with no intervening space, by ‘@dmn’, and then by the
dimension within braces.  For example,

     A4 paper is 8.27@dmn{in} wide.

produces

     A4 paper is 8.27in wide.

   Not everyone uses this style.  Some people prefer '8.27 in.' or
'8.27 inches'.  In these cases, however, you need to use ‘@tie’ (see
@tie) or ‘@w’ (see @w) so that no line break can occur between the
number and the dimension.  Also, if you write a period after an
abbreviation within a sentence (as with the 'in.' above), you should
write ‘@:’ after the period to avoid inserting extra whitespace in
printed output, as shown here.  See Not Ending a Sentence.

11.4 Inserting Accents
======================

Here is a table with the commands Texinfo provides for inserting
floating accents.  They all need an argument, the character to accent,
which can either be given in braces as usual (‘@'{e}’), or, as a special
case, the braces can be omitted, in which case the argument is the next
character (‘@'e’).  This is to make the source as convenient as possible
to type and read, since accented characters are very common in some
languages.

   If the command is alphabetic, such as ‘@dotaccent’, then there must
be a space between the command name and argument if braces are not used.
If the command is non-alphabetic, such as ‘@'’, then there must _not_ be
a space; the argument is the very next character.

   Exception: the argument to ‘@tieaccent’ must be enclosed in braces
(since it is two characters instead of one).

   In Info and plain text output, accent constructs are output as the
true accented characters if the document encoding supports the required
characters, unless the option ‘--disable-encoding’ is given to
‘texi2any’ (see @documentencoding).  ASCII transliterations are used
if the encoded characters are not output.

Command           Output   What
------------------------------------------------------
@"o               ö        umlaut accent
@'o               ó        acute accent
@,{c}             ç        cedilla accent
@=o               ō        macron/overbar accent
@^o               ô        circumflex accent
@`o               ò        grave accent
@~o               õ        tilde accent
@dotaccent{o}     ȯ        overdot accent
@H{o}             ő        long Hungarian umlaut
@ogonek{a}        ą        ogonek
@ringaccent{o}    o̊        ring accent
@tieaccent{oo}    o͡o       tie-after accent
@u{o}             ŏ        breve accent
@ubaraccent{o}    o̲        underbar accent
@udotaccent{o}    ọ        underdot accent
@v{o}             ǒ        caron/hacek/check accent

   This table lists the Texinfo commands for inserting other characters
commonly used in languages other than English.

@exclamdown{}     ¡       upside-down !
@questiondown{}   ¿       upside-down ?
@aa{} @AA{}       å Å     a,A with circle
@ae{} @AE{}       æ Æ     ae,AE ligatures
@dh{} @DH{}       ð Ð     Icelandic eth
@dotless{i}       ı       dotless i
@dotless{j}       ȷ       dotless j
@l{} @L{}         ł Ł     suppressed-L,l
@o{} @O{}         ø Ø     O,o with slash
@oe{} @OE{}       œ Œ     oe,OE ligatures
@ordf{} @ordm{}   ª º     Spanish ordinals
@ss{}             ß       es-zet or sharp S
@th{} @TH{}       þ Þ     Icelandic thorn

11.5 Inserting Quotation Marks
==============================

Use doubled single-quote characters to begin and end quotations:
``...''.  Two single quotes are converted to left- and right-hand
doubled quotation marks, "like this".

   You may occasionally need to produce two consecutive single quotes;
for example, in documenting a computer language such as Maxima where ''
is a valid command.  You can do this with the input '@w{}'; the empty
‘@w’ command stops the combination into the double-quote characters.

   The left quote character (`, ASCII code 96) used in Texinfo is a
grave accent in ANSI and ISO character set standards.  We use it as a
quote character because that is how TeX is set up, by default.

   Texinfo supports several other quotation marks used in languages
other than English.  Below is a table with the commands Texinfo provides
for inserting quotation marks.

Command               Glyph   Unicode name (point)
----------------------------------------------------------------------
@quotedblleft{} ``    “       Left double quotation mark (U+201C)
@quotedblright{} ''   ”       Right double quotation mark (U+201D)
@quoteleft{} `        ‘       Left single quotation mark (U+2018)
@quoteright{} '       ’       Right single quotation mark (U+2019)
@quotedblbase{}       „       Double low-9 quotation mark (U+201E)
@quotesinglbase{}     ‚       Single low-9 quotation mark (U+201A)
@guillemetleft{}      «       Left-pointing double angle quotation
                              mark (U+00AB)
@guillemetright{}     »       Right-pointing double angle quotation
                              mark (U+00BB)
@guilsinglleft{}      ‹       Single left-pointing angle quotation
                              mark (U+2039)
@guilsinglright{}     ›       Single right-pointing angle quotation
                              mark (U+203A)

   For the double angle quotation marks, Adobe and LaTeX glyph names are
also supported: ‘@guillemotleft’ and ‘@guillemotright’.  These names are
incorrect; a "guillemot" is a bird species (a type of auk).

   The standard TeX fonts support the usual quotation marks used in
English (the ones produced with single and doubled ASCII single quotes).
For the other quotation marks, TeX uses European Computer Modern (EC)
fonts (‘ecrm1000’ and other variants).  These fonts are freely
available, of course; you can download them from
<http://ctan.org/pkg/ec>, among other places.

   The free EC fonts are bitmap fonts created with Metafont.  Especially
for on-line viewing, Type 1 (vector) versions of the fonts are
preferable; these are available in the CM-Super font package
(<http://ctan.org/pkg/cm-super>).

   Both distributions include installation instructions.

   Traditions for quotation mark usage vary to a great extent between
languages (<https://en.wikipedia.org/wiki/Quotation_mark>).  Texinfo
does not provide commands or configurations for typesetting quotation
marks according to the numerous traditions.  Therefore, you have to
choose the commands appropriate for the language of your manual.
Sometimes aliases (see @alias) can simplify the usage and make the
source code more readable.  For example, in German, ‘@quotedblbase’ is
used for the left double quote, and the right double quote is the glyph
produced by ‘@quotedblleft’, which is counterintuitive.  Thus, in this
case the following aliases would be convenient:

     @alias lgqq = quotedblbase
     @alias rgqq = quotedblleft

11.6 ‘@sub’ and ‘@sup’: Inserting Subscripts and Superscripts
=============================================================

You can insert subscripts and superscripts with the ‘@sub’ and ‘@sup’
commands.  For example:

     here@sub{below}@sup{above}

produces:

     here_{below}^{above}

   In Info and plain text, ‘@sub{TEXT}’ is currently output as ‘_{TEXT}’
and ‘@sup{TEXT}’ as ‘^{TEXT}’, including the literal braces (to mark the
beginning and end of the "script" text to the reader).

   When the output format (and display program) permit (printed output,
HTML), the superscript is set above the subscript when both commands are
given consecutively.

   For subscripts and superscripts in mathematical expressions, it is
better to use TeX's ‘_’ and ‘^’ characters.  See the next section.

11.7 Glyphs for Text
====================

Texinfo has support for a few additional glyphs that are commonly used
in printed text but not available in ASCII.  Of course, there are many
thousands more.  It is possible to use Unicode characters as-is as far
as ‘texi2any’ is concerned, but TeX is not so lucky.

11.7.1 ‘@TeX’{} (TeX) and ‘@LaTeX’{} (LaTeX)
--------------------------------------------

Use the ‘@TeX{}’ command to generate 'TeX'.  In a printed manual, this
is a special logo that is different from three ordinary letters.  In
other output formats, it just looks like ‘TeX’.

   Similarly, use the ‘@LaTeX{}’ command to generate 'LaTeX', which is
even more special in printed manuals (and different from the incorrect
‘La@TeX{}’.  In other output formats, the result is just ‘LaTeX’.

   The spelling of these commands is unusual for Texinfo, in that they
use both uppercase and lowercase letters.

11.7.2 ‘@copyright{}’ (©)
-------------------------

Use the ‘@copyright{}’ command to generate the copyright symbol, '©'.
Where possible, this is a ‘c’ inside a circle; otherwise this is ‘(C)’.

   Legally, it's not necessary to use the copyright symbol; the English
word 'Copyright' suffices, according to international treaty.

11.7.3 ‘@registeredsymbol{}’ (®)
--------------------------------

Use the ‘@registeredsymbol{}’ command to generate the registered symbol,
'®'.  Where possible, this is an ‘R’ inside a circle; otherwise this is
‘(R)’.

11.7.4 ‘@dots’ (...) and ‘@enddots’ (...)
-----------------------------------------

An “ellipsis” (a sequence of dots) would be spaced wrong when typeset as
a string of periods, so a special command is used in Texinfo: use the
‘@dots{}’ command to generate a normal ellipsis, which is three dots in
a row, appropriately spaced ... like so.  To emphasize: do not simply
write three periods in the input file; that could work in some output
formats, but would produce the wrong amount of space between the periods
in printed manuals.

   The ‘@enddots{}’ command generates an end-of-sentence ellipsis, which
also has three dots, but with different spacing afterwards, ...  Look
closely to see the difference.

   Here is an ellipsis: ... Here are three periods in a row: ...

   In printed (and usually HTML) output, the three periods in a row are
much closer together than the dots in the ellipsis.

11.7.5 ‘@bullet’ (•)
--------------------

Use the ‘@bullet{}’ command to generate a large round dot, or the
closest possible thing to one.  An asterisk can also be used.  Here is a
bullet: •

11.7.6 ‘@euro’ (€): Euro Currency Symbol
----------------------------------------

Use the ‘@euro{}’ command to generate '€'.  Where possible, this is the
symbol for the Euro currency.  Otherwise, the word ‘Euro’ is used.

   The Euro symbol does not exist in the standard TeX fonts (which were
designed before the Euro was legislated into existence).  Therefore, TeX
uses an additional font, named ‘feymr10’ (along with other variables).
It is freely available, of course; you can download it from
<http://ctan.org/pkg/eurosym>, among other places.  The distribution
includes installation instructions.

11.7.7 ‘@pounds’ (£): Pounds Sterling
-------------------------------------

Use the ‘@pounds{}’ command to generate '£'.  Where possible, this is
the symbol for the pounds sterling British currency.

11.7.8 ‘@textdegree’ (°): Degrees Symbol
----------------------------------------

Use the ‘@textdegree{}’ command to generate '°'.  Where possible, this
is the normal symbol for degrees.

11.7.9 ‘@minus’ (−): Inserting a Minus Sign
-------------------------------------------

Use the ‘@minus{}’ command to generate a minus sign.  Where the
character encoding and font used in the output allow it, the symbol is
the customary length for a minus sign--a little longer than a hyphen,
shorter than an em-dash:

     ‘−’ is a minus sign generated with ‘@minus{}’,

     '-' is a hyphen generated with the character ‘-’,

     '--' is an em-dash for text.

   If you actually want to typeset some math that does a subtraction, it
is better to use ‘@math’, as in ‘@math{a-b}’ (see Inserting Math).

11.7.10 ‘@geq’ (≥) and ‘@leq’ (≤): Inserting Relations
------------------------------------------------------

Use the ‘@geq{}’ and ‘@leq{}’ commands to generate greater-than-or-equal
and less-than-equal-signs, '≥' and '≤'.  When those symbols are not
available, the ASCII sequences ‘>=’ and ‘<=’ are output.

11.8 Glyphs for Programming
===========================

In Texinfo, code is often illustrated in examples that are delimited by
‘@example’ and ‘@end example’.  In such examples, you can indicate the
results of evaluation or an expansion using ‘⇒’ or ‘↦’.  Likewise, there
are commands to insert glyphs to indicate printed output, error
messages, equivalence of expressions, the location of point in an
editor, and GUI operation sequences.

   The glyph-insertion commands do not need to be used within an
example, but most often they are.  All glyph-insertion commands are
followed by empty braces.

11.8.1 Glyphs Summary
---------------------

Here is a summary of the glyph commands:

⇒
     ‘@result{}’ indicates the result of an expression.

↦
     ‘@expansion{}’ indicates the results of a macro expansion.

⊣
     ‘@print{}’ indicates printed output.

error→
     ‘@error{}’ indicates the following text is an error message.

≡
     ‘@equiv{}’ indicates the exact equivalence of two forms.

⋆
     ‘@point{}’ shows the location of point.

A → B
     ‘@clicksequence{A @click{} B}’ indicates a GUI operation sequence:
     first A, then clicking B, or choosing B from a menu, or otherwise
     selecting it.

11.8.2 ‘@result{}’ (⇒): Result of an Expression
-----------------------------------------------

Use the ‘@result{}’ command to indicate the result of evaluating an
expression.

   The ‘@result{}’ command is displayed as ‘⇒’, either a double stemmed
arrow or (when that is not available) the ASCII sequence ‘=>’.

   Thus, the following,

     (cdr '(1 2 3))
         ⇒ (2 3)

may be read as "‘(cdr '(1 2 3))’ evaluates to ‘(2 3)’".

11.8.3 ‘@expansion{}’ (↦): Indicating an Expansion
--------------------------------------------------

When an expression is a macro call, it expands into a new expression.
You can indicate the result of the expansion with the ‘@expansion{}’
command.

   The ‘@expansion{}’ command is displayed as ‘↦’, either a long arrow
with a flat base or (when that is not available) the ASCII sequence
‘==>’.

   For example, the following

     @example lisp
     (third '(a b c))
         @expansion{} (car (cdr (cdr '(a b c))))
         @result{} c
     @end example

produces

     (third '(a b c))
         ↦ (car (cdr (cdr '(a b c))))
         ⇒ c

which may be read as:

     ‘(third '(a b c))’ expands to ‘(car (cdr (cdr '(a b c))))’; the
     result of evaluating the expression is ‘c’.

Often, as in this case, an example looks better if the ‘@expansion{}’
and ‘@result{}’ commands are indented.

11.8.4 ‘@print{}’ (⊣): Indicating Generated Output
--------------------------------------------------

Sometimes an expression will generate output during its execution.  You
can indicate such displayed output with the ‘@print{}’ command.

   The ‘@print{}’ command is displayed as ‘⊣’, either a horizontal dash
butting against a vertical bar or (when that is not available) the ASCII
sequence ‘-|’.

   In the following example, the printed text is indicated with ‘⊣’, and
the value of the expression follows on the last line.

     (progn (print 'foo) (print 'bar))
         ⊣ foo
         ⊣ bar
         ⇒ bar

In a Texinfo source file, this example is written as follows:

     @example lisp
     (progn (print 'foo) (print 'bar))
         @print{} foo
         @print{} bar
         @result{} bar
     @end example

11.8.5 ‘@error{}’ (error→): Indicating an Error Message
-------------------------------------------------------

A piece of code may cause an error when you evaluate it.  You can
designate the error message with the ‘@error{}’ command.

   The ‘@error{}’ command is displayed as ‘error→’, either the word
'error' in a box in the printed output, the word error followed by an
arrow in other formats or (when no arrow is available) ‘error-->’.

   Thus,

     @example lisp
     (+ 23 'x)
     @error{} Wrong type argument: integer-or-marker-p, x
     @end example

produces

     (+ 23 'x)
     error→ Wrong type argument: integer-or-marker-p, x

This indicates that the following error message is printed when you
evaluate the expression:

     Wrong type argument: integer-or-marker-p, x

   The word ‘error→’ itself is not part of the error message.

11.8.6 ‘@equiv{}’ (≡): Indicating Equivalence
---------------------------------------------

Sometimes two expressions produce identical results.  You can indicate
the exact equivalence of two forms with the ‘@equiv{}’ command.  The
‘@equiv{}’ command is displayed as ‘≡’, either a standard mathematical
equivalence sign (three parallel horizontal lines) or (when that is not
available) as the ASCII sequence ‘==’.

   Thus,

     @example lisp
     (make-sparse-keymap) @equiv{} (list 'keymap)
     @end example

produces

     (make-sparse-keymap) ≡ (list 'keymap)

This indicates that evaluating ‘(make-sparse-keymap)’ produces identical
results to evaluating ‘(list 'keymap)’.

11.8.7 ‘@point{}’ (⋆): Indicating Point in a Buffer
---------------------------------------------------

Sometimes you need to show an example of text in an Emacs buffer.  In
such examples, the convention is to include the entire contents of the
buffer in question between two lines of dashes containing the buffer
name.

   You can use the ‘@point{}’ command to show the location of point in
the text in the buffer.  (The symbol for point, of course, is not part
of the text in the buffer; it indicates the place _between_ two
characters where point is located.)

   The ‘@point{}’ command is displayed as ‘⋆’, either a pointed star or
(when that is not available) the ASCII sequence ‘-!-’.

   The following example shows the contents of buffer ‘foo’ before and
after evaluating a Lisp command to insert the word ‘changed’.

     ---------- Buffer: foo ----------
     This is the ⋆contents of foo.
     ---------- Buffer: foo ----------

     (insert "changed ")
         ⇒ nil
     ---------- Buffer: foo ----------
     This is the changed ⋆contents of foo.
     ---------- Buffer: foo ----------

   In a Texinfo source file, the example is written like this:

     @example
     ---------- Buffer: foo ----------
     This is the @point{}contents of foo.
     ---------- Buffer: foo ----------

     (insert "changed ")
         @result{} nil
     ---------- Buffer: foo ----------
     This is the changed @point{}contents of foo.
     ---------- Buffer: foo ----------
     @end example

11.8.8 Click Sequences
----------------------

When documenting graphical interfaces, it is necessary to describe
sequences such as 'Click on ‘File’, then choose ‘Open’, then ...'.
Texinfo offers commands ‘@clicksequence’ and ‘click’ to represent this,
typically used like this:

     ... @clicksequence{File @click{} Open} ...

which produces:

     ... File → Open ...

   The ‘@click’ command produces a right arrow; this glyph is also
available independently via the command ‘@arrow{}’.

   The ‘@clickstyle’ command that could be used to change the glyph
produced by ‘@click’ is deprecated, you should not use it anymore.  You
can use ‘@alias’ (see @alias) instead to change the glyph produced
by ‘@click’.

   You can replace:
     @clickstyle @result
   by
     @alias click=result

   The ‘@clickstyle’ command will be removed in a future release.

11.9 Inserting Unicode: ‘@U’
============================

The command ‘@U{HEX}’ inserts a representation of the Unicode character
U+HEX.  For example, ‘@U{0132}’ inserts the Dutch 'IJ' ligature ('Ĳ').

   The HEX value should be at least four hex digits; leading zeros are
_not_ added.  In general, HEX must specify a valid normal Unicode
character; e.g., U+10FFFF (the very last code point) is invalid by
definition, and thus cannot be inserted this way.

   ‘@U’ is useful for inserting occasional glyphs for which Texinfo has
no dedicated command, while allowing the Texinfo source to remain purely
7-bit ASCII for maximum portability.

   This command has many limitations--the same limitations as inserting
Unicode characters in UTF-8 or another binary form.  First and most
importantly, TeX knows nothing about most of Unicode.  Supporting
specific additional glyphs upon request is possible, but it's not viable
for ‘texinfo.tex’ to support whole additional scripts (Japanese, Urdu,
...).  The ‘@U’ command does nothing to change this.  If the specified
character is not supported in TeX, an error is given.  LaTeX output has
more possibilities regarding UTF-8, but could require extra code to load
fonts and declare how UTF-8 characters are output.  (see
@documentencoding.)

   In HTML and DocBook, the output from ‘@U’ is always an entity
reference of the form ‘&#xHEX;’, as in ‘&#x0132;’ for the example above.
This should work even when an HTML document uses some other encoding
(say, Latin 1) and the given character is not supported in that
encoding.

   In Info and plain text, if the output encoding is not UTF-8, the
output is the ASCII sequence ‘U+HEX’, as in the six ASCII characters
‘U+0132’ for the example above.

12 Formatting Mathematics
*************************

You can write a mathematical expression, equation or formula using the
‘@math’ command.  Write the TeX math notation between braces, like this:

     @math{\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta}

   ‘@math’ is formatted inline when used inside a paragraph, like
\partial_\alpha \partial^\alpha A^\beta = \mu_0 J^\beta in this example.

   By default, the ‘@math’ command has no special effect on the Info
output, merely outputting the contents verbatim.  You can use the
experimental ‘INFO_MATH_IMAGES’ variable to produce images; see
Info and Plaintext Customization Variables.

   For printed output, ‘@math’ switches into TeX "math mode".  In that
context, ‘\’ must be used instead of ‘@’ for plain TeX math control
sequences for symbols, functions, and so on.

   By default, the HTML output is only emphasized.  ‘texi2any’ provides
three options for displaying properly formatted mathematics for HTML.
You can select these with the ‘HTML_MATH’ variable (see HTML Customization for Math).
With ‘HTML_MATH’ set to ‘l2h’, ‘texi2any’
attempts to use the ‘latex2html’ program to produce image files for
mathematical material.  With the ‘t4h’ setting, ‘texi2any’ attempts to
use the ‘tex4ht’ program.  With the ‘mathjax’ setting, ‘texi2any’
inserts references in the output files to MathJax scripts to format the
material.  The MathJax option requires JavaScript to be enabled in the
browser to work.  See also MathJax Customization Variables,
latex2html Customization Variables and tex4ht Customization Variables.

   For displayed equations, you can use the ‘@displaymath’ command.
Example:

     @displaymath
     f(x) = {1\over\sigma\sqrt{2\pi}}
     e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}
     @end displaymath

which produces:

f(x) = {1\over\sigma\sqrt{2\pi}}
e^{-{1\over2}\left({x-\mu\over\sigma}\right)^2}

   In general, the contents of ‘@math’ or ‘@displaymath’ should be plain
TeX only, with no interspersed Texinfo commands.  If you do use any
Texinfo commands, then you should mark these with ‘@’ as usual, rather
than ‘\’ (e.g. ‘@var’ rather than ‘\var’), but we do not guarantee which
Texinfo commands will work.

   Although ‘@sub’ and ‘@sup’ may work inside math mode in some
contexts, it is better to use TeX's ‘_’ and ‘^’ characters to denote
subscripts and superscripts within mathematical expressions.

   LaTeX-specific code will only work when the output format is LaTeX,
and with the ‘HTML_MATH’ options (although ‘tex4ht’ needs
‘T4H_MATH_CONVERSION’ to be set to ‘latex’; see tex4ht Customization Variables).

   Due to the conflict with Texinfo's ‘@sup’ command, you can access the
plain TeX command ‘\sup’ as ‘\mathopsup’ instead, in the unlikely
occurrence that you want to do this (but only when processing with TeX,
not when outputting LaTeX nor with any of the ‘HTML_MATH’ options).

13 Forcing and Preventing Breaks
********************************

Line and page breaks can sometimes occur in the 'wrong' place in one or
another form of output.  It's up to you to ensure that text looks right
in all the output formats.

   For example, in a printed manual, page breaks may occur awkwardly in
the middle of an example; to prevent this, you can hold text together
using a grouping command that keeps the text from being split across two
pages.  Conversely, you may want to force a page break where none would
normally occur.

   You can use the break, break prevention, or pagination commands to
fix problematic line and page breaks.

13.1 Break Commands
===================

The break commands create or allow line and paragraph breaks:

‘@*’
     Force a line break.

‘@sp N’
     Skip N blank lines.

‘@-’
     Insert a discretionary hyphen.

‘@hyphenation{HY-PHEN-A-TED WORDS}’
     Define hyphen points in HY-PHEN-A-TED WORDS.

   These commands hold text together on a single line:

‘@w{TEXT}’
     Prevent TEXT from being split and hyphenated across two lines.

‘@tie{}’
     Insert a normal interword space at which a line break may not
     occur.

   The pagination commands apply only to printed output, since other
output formats do not have pages.

‘@page’
     Start a new page.

‘@group’
     Hold text together that must appear on one page.

‘@need MILS’
     Start a new page if not enough space on this one.

13.2 ‘@*’ and ‘@/’: Generate and Allow Line Breaks
==================================================

The ‘@*’ command forces a line break in all output formats.  The ‘@/’
command allows a line break (printed manual only).

   Here is an example with ‘@*’:

     This sentence is broken @*into two lines.

produces

     This sentence is broken
     into two lines.

   The ‘@/’ command can be useful within long URLs or other identifiers
where TeX can't find a good place to break.  TeX will automatically
break URLs at the natural places (see URL Line Breaking), so only
use ‘@/’ if you need it.  ‘@/’ has no effect on the other output
formats.

13.3 ‘@-’ and ‘@hyphenation’: Hyphenation in Printed Output
===========================================================

Although TeX's hyphenation algorithm is generally pretty good, it does
miss useful hyphenation points from time to time.  (Or, far more rarely,
insert an incorrect hyphenation.)  So, for documents with an unusual
vocabulary or when fine-tuning for a printed edition, you may wish to
specify hyphenation points explicitly.  Texinfo supports two commands
for this:

‘@-’

     Insert a discretionary hyphen, i.e., a place where a word can be
     broken across lines with a hyphen.  This is especially useful when
     you notice that an overfull hbox is due to TeX missing a
     hyphenation (see Overfull hboxes).  TeX will not insert any
     hyphenation points itself into a word containing ‘@-’.

‘@hyphenation{HY-PHEN-A-TED WORDS}’
     Give hyphenation points for certain words.  For example:
          @hyphenation{man-u-script man-u-scripts}

     As shown, you put a ‘-’ at each hyphenation point.  TeX only uses
     the specified hyphenation points when the words match exactly, so
     give all necessary variants, such as plurals.

   Non-printed output is not hyphenated, so none of these commands have
any effect in other output formats.

13.4 ‘@allowcodebreaks’: Control Line Breaks in ‘@code’
=======================================================

Ordinarily, TeX considers breaking lines at ‘-’ and ‘_’ characters
within ‘@code’ and related commands (see @code), more or less as if
they were "empty" hyphenation points.

   This is necessary since many manuals, especially for Lisp-family
languages, must document very long identifiers.  On the other hand, some
manuals don't have this problem, and you may not wish to allow a line
break at the underscore in, for example, ‘SIZE_MAX’, or even worse,
after any of the four underscores in ‘__typeof__’.

   So Texinfo provides this command:

     @allowcodebreaks false

to prevent from breaking at ‘-’ or ‘_’ within ‘@code’.  You can go back
to allowing such breaks with ‘@allowcodebreaks true’.  Write these
commands on lines by themselves.

   These commands can be given anywhere in the document.  For example,
you may have just one problematic paragraph where you need to turn off
the breaks, but want them in general, or vice versa.

   This command has no effect except in TeX output.

13.5 ‘@w’{TEXT}: Prevent Line Breaks
====================================

‘@w{TEXT}’ outputs TEXT, while prohibiting line breaks within TEXT.

   Thus, you can use ‘@w’ to produce a non-breakable space, fixed at the
width of a normal interword space:

     @w{ } @w{ } @w{ } indentation.

produces:

           indentation.

   The space from ‘@w{ }’, as well as being non-breakable, also will not
stretch or shrink.  Sometimes that is what you want, for instance if
you're doing manual indenting.  However, usually you want a normal
interword space that does stretch and shrink (in the printed output);
for that, see the ‘@tie’ command in the next section.

   In printed output, you can also use the ‘@w’ command to prevent a
long name or phrase being automatically hyphenated, for example if it
happens to fall near the end of a line.

   You can also use ‘@w’ to avoid unwanted keyword expansion in source
control systems.  For example, to literally write $Id$ in your document,
use ‘@w{$}Id$’.  This trick isn't effective for output files in some
output formats, though.

13.6 ‘@tie{}’: Inserting an Unbreakable Space
=============================================

The ‘@tie{}’ command produces a normal interword space at which a line
break may not occur.  Always write it with following (empty) braces, as
usual for commands used within a paragraph.  Here's an example:

     @TeX{} was written by Donald E.@tie{}Knuth.

produces:

     TeX was written by Donald E. Knuth.

   There are two important differences between ‘@tie{}’ and ‘@w{ }’:

   • The space produced by ‘@tie{}’ will stretch and shrink slightly
     along with the normal interword spaces in the paragraph; the space
     produced by ‘@w{ }’ will not vary.

   • ‘@tie{}’ allows hyphenation of the surrounding words, while ‘@w{ }’
     inhibits hyphenation of those words (for TeXnical reasons, namely
     that it produces an ‘\hbox’).

13.7 ‘@sp N’: Insert Blank Lines
================================

A line beginning with and containing only ‘@sp N’ generates N blank
lines of space.  ‘@sp’ also forces a paragraph break.  For example,

     @sp 2

generates two blank lines.

   The ‘@sp’ command is most often used inside a ‘@titlepage’ block.

13.8 ‘@page’: Start a New Page
==============================

A line containing only ‘@page’ starts a new page in a printed manual.
In other formats, without the concept of pages, it starts a new
paragraph.  A ‘@page’ command is often used in a ‘@titlepage’ section of
a Texinfo file to start the copyright page.

13.9 ‘@group’: Prevent Page Breaks
==================================

The ‘@group’ command is used to hold an example together on one page.
Use it inside an ‘@example’ or similar construct to begin an
unsplittable vertical group, which will appear entirely on one page in
the printed output.  Terminate the group by a line containing only ‘@end
group’.  This command has an effect in TeX output only.

   The ‘@group’ and ‘@end group’ commands need to be inside the
‘@example’ and ‘@end example’ commands, thus:

     @example
     @group
     ...
     @end group
     @end example

   Although ‘@group’ would make sense conceptually in a wide variety of
contexts, its current implementation works only within ‘@example’ and
variants, and within ‘@display’, ‘@format’, ‘@flushleft’ and
‘@flushright’.  See Quotations and Examples.  (What all these
commands have in common is that each line of input produces a line of
output.)

13.10 ‘@need MILS’: Prevent Page Breaks
=======================================

A line containing only ‘@need N’ starts a new page in a printed manual
if fewer than N mils (thousandths of an inch) remain on the current
page.  Do not use braces around the argument N.  The ‘@need’ command has
no effect on other output formats since they are not paginated.

   This paragraph is preceded by a ‘@need’ command that starts a new
page in printed output if fewer than 800 mils (eight-tenths inch) remain
on the page.  It looks like this:

     @need 800
     This paragraph is preceded by ...

   The ‘@need’ command is useful for preventing orphans: single lines at
the bottoms of printed pages.

14 Definition Commands
**********************

The ‘@deffn’ command and the other “definition commands” enable you to
describe functions, variables, macros, commands, user options, special
forms and other entities in a uniform format.

   In the output, the name of the entity is shown with any arguments,
along with the entity category --'Function', 'Variable', or whatever.
Underneath, the body of the definition is indented.  The name of the
entity is also entered into the appropriate index.

   All the definition commands follow a similar format.  This chapter
starts by describing ‘@deffn’ before detailing all the other definition
commands.

14.1 The Template for a Definition
==================================

     @deffn CATEGORY NAME ARGUMENTS...
     BODY-OF-DEFINITION
     @end deffn

The ‘@deffn’ command is used for definitions of entities that resemble
functions--entities that may take arguments.  Write the ‘@deffn’ command
at the beginning of a line and follow it on the same line by the
category of the entity, the name of the entity itself, and its arguments
(if any).  Then write the body of the definition on succeeding lines.
Finally, end the definition with an ‘@end deffn’ command written on a
line of its own.

For example,

     @deffn Command forward-word count
     This command moves point forward @var{count} words
     (or backward if @var{count} is negative). ...
     @end deffn

produces

      -- Command: forward-word count
          This command moves point forward COUNT words (or backward if
          COUNT is negative).  ...

   Capitalize the category name like a title.  If the name of the
category contains spaces, as in the phrase 'Interactive Command',
enclose it in braces.  For example:

     @deffn {Interactive Command} isearch-forward
     ...
     @end deffn

Otherwise, the second word will be mistaken for the name of the entity.
As a general rule, when any of the arguments in the heading line
_except_ the last one are more than one word, you need to enclose them
in braces.  This may also be necessary if the text contains commands,
for example, ‘{declaraci@'on}’ if you are writing in Spanish.

   The category is output in a different location for different output
formats.  For example, in the Info file, the category appears at the
beginning of the first line of the definition.  With TeX output, the
category is printed next to the right margin.

   ‘@deffn’ enters names into the index of functions.

   Three predefined, specialized variations of ‘@deffn’ (‘@defun’,
‘@defmac’, and ‘@defspec’) specify the category for you: "Function",
"Macro", and "Special Form" respectively.  (In Lisp, a special form is
an entity much like a function.)  Similarly, the general ‘@defvr’
command is accompanied by several specialized variations for describing
particular kinds of variables.

14.2 Definition Command Continuation Lines
==========================================

The heading line of a definition command can get very long.  Therefore,
Texinfo has a special syntax allowing them to be continued over multiple
lines of the source file: a lone ‘@’ at the end of each line to be
continued.  Here's an example:

     @defun fn-name @
       arg1 arg2 arg3
     This is the basic continued defun.
     @end defun

produces:

 -- Function: fn-name arg1 arg2 arg3
     This is the basic continued defun.

As you can see, the continued lines are combined, as if they had been
typed on one source line.

   Although this example only shows a one-line continuation,
continuations may extend over any number of lines, in the same way; put
an ‘@’ at the end of each line to be continued.

   In general, any number of spaces or tabs before the ‘@’ continuation
character are collapsed into a single space.  There is one exception:
the Texinfo processors will not fully collapse whitespace around a
continuation inside braces.  For example:

     @deffn {Category @
       Name} ...

The output (not shown) has excess space between 'Category' and 'Name'.
To avoid this, elide the unwanted whitespace in your input, or put the
continuation ‘@’ outside braces.

   ‘@’ does not function as a continuation character in _any_ other
context.  Ordinarily, ‘@’ followed by a whitespace character (space,
tab, newline) produces a normal interword space (see Multiple Spaces).

14.3 Optional and Repeated Arguments
====================================

Some entities take optional or repeated arguments.  One convention for
indicating these uses square brackets and ellipses: an argument enclosed
within square brackets is optional, and an argument followed by an
ellipsis is optional and may be repeated more than once.

   Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional and
REPEATED-ARGS‘...’ stands for zero or more arguments.  Parentheses are
used when several arguments are grouped into additional levels of list
structure in Lisp.

   Here is the definition line of an example of an imaginary
(complicated) special form:

      -- Special Form: foobar (var [from to [inc]]) body...

In this example, the arguments FROM and TO are optional, but must both
be present or both absent.  If they are present, INC may optionally be
specified as well.  These arguments are grouped with the argument VAR
into a list, to distinguish them from BODY, which includes all remaining
elements of the form.

   In a Texinfo source file, this ‘@defspec’ line is written like this:

     @defspec foobar (var [from to [inc]]) body@dots{}

14.4 Omitting the Space After a Definition Name
===============================================

As a matter of style or as demanded by the syntax of a programming
language, you may wish to omit any space after a name in a definition,
occurring before an opening bracket.  To do this, set the
‘txidefnamenospace’ flag (see @set @value).  For example, this input

     @set txidefnamenospace
     @deffn Builtin m4_index (string, substring)
     @dots{}
     @end deffn

produces the following:

 -- Builtin: m4_index(string, substring)
     ...

14.5 ‘@deffnx’, et al.: Two or More 'First' Lines
=================================================

To create two or more 'first' or header lines for a definition, follow
the first ‘@deffn’ line by a line beginning with ‘@deffnx’.

   For example,

     @deffn {Interactive Command} isearch-forward
     @deffnx {Interactive Command} isearch-backward
     These two search commands are similar except ...
     @end deffn

produces

 -- Interactive Command: isearch-forward
 -- Interactive Command: isearch-backward
     These two search commands are similar except ...

   Each definition command has an 'x' form: ‘@defunx’, ‘@defvrx’,
‘@deftypefunx’, etc.

   The 'x' forms work similarly to ‘@itemx’ (see @itemx).

14.6 The Definition Commands
============================

This section describes all the definition commands of Texinfo.

14.6.1 Functions and Similar Entities
-------------------------------------

This section describes the commands for describing functions and similar
entities with simple arguments:

‘@deffn CATEGORY NAME ARGUMENTS...’
     The ‘@deffn’ command is the general definition command for
     functions, interactive commands, and similar entities that may take
     simple arguments.  You must choose a term to describe the category
     of entity being defined; for example, "Function" could be used if
     the entity is a function.  The ‘@deffn’ command is written at the
     beginning of a line and is followed on the same line by the
     category of entity being described, the name of this particular
     entity, and its arguments, if any.  Terminate the definition with
     ‘@end deffn’ on a line of its own.

     For example, here is a definition:

          @deffn Command forward-char nchars
          Move point forward @var{nchars} characters.
          @end deffn

     This shows a rather terse definition for a "command" named
     ‘forward-char’ with one argument, NCHARS.

     Within the text of the description, write an argument name
     explicitly with ‘@var’ to refer to the value of the argument.  In
     the example above, we used ‘@var{nchars}’ in this way.

     In the extremely unusual case when an argument name contains ‘--’,
     or another character sequence which is treated specially (see
     Conventions), use ‘@code’ around the special characters.  This
     avoids the conversion to typographic en-dashes and em-dashes.

‘@defun NAME ARGUMENTS...’
     The ‘@defun’ command is the definition command for functions with
     simple arguments.  ‘@defun’ is equivalent to ‘@deffn Function ...’.
     Terminate the definition with ‘@end defun’ on a line of its own.

‘@defmac NAME ARGUMENTS...’
     The ‘@defmac’ command is the definition command for macros.
     ‘@defmac’ is equivalent to ‘@deffn Macro ...’ and works like
     ‘@defun’.

‘@defspec NAME ARGUMENTS...’
     The ‘@defspec’ command is the definition command for special forms.
     (In Lisp, a special form is an entity much like a function; see
     Special Forms (elisp).)  ‘@defspec’ is equivalent to ‘@deffn
     {Special Form} ...’ and works like ‘@defun’.

   All these commands create entries in the index of functions.

14.6.2 Functions in Typed Languages
-----------------------------------

The ‘@deftypefn’ command and its variants are generic commands for
describing functions.  They are particularly suitable for languages in
which you must declare types of variables and functions, such as C and
C++.

‘@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...’
     The ‘@deftypefn’ command is the general definition command for
     functions and similar entities that may take arguments and that
     could be typed.  The ‘@deftypefn’ command is written at the
     beginning of a line and is followed on the same line by the
     category of entity being described, information on the returned
     value, the name of this particular entity, and its arguments, if
     any.

     For example,

          @deftypefn {Library Function} int foobar @
            (int @var{foo}, float @var{bar})
          ...
          @end deftypefn

     produces:

           -- Library Function: int foobar (int FOO, float BAR)
               ...

     This means that ‘foobar’ is a "library function" that returns an
     ‘int’, and its arguments are FOO (an ‘int’) and BAR (a ‘float’).
     ‘Library Function’ has to be enclosed in braces to make it a single
     argument.

     When using ‘@deftypefn’ command and variations, you should mark
     parameter names with ‘@var’ to distinguish these from data type
     names, keywords, and other parts of the literal syntax of the
     programming language.

     If you are describing a procedure in a language that has packages,
     such as Ada, you might consider using ‘@deftypefn’ in the following
     manner:

          @deftypefn stacks private push @
                 (@var{s}:in out stack; @
                 @var{n}:in integer)
          ...
          @end deftypefn

     (In these examples the ‘@deftypefn’ arguments are shown using
     continuations (see Def Cmd Continuation Lines), but could be on
     a single line.)

     In this instance, the procedure is classified as belonging to the
     package ‘stacks’ rather than classified as a 'procedure' and its
     data type is described as ‘private’.  (The name of the procedure is
     ‘push’, and its arguments are S and N.)  Output:

      -- stacks: private push (S:in out stack; N:in integer)
          ...

     ‘@deftypefn’ and variants could be used when it is convenient to
     interpret the arguments list as literal computer code, marking
     argument names with ‘@var’.  It is not necessary for any type names
     to appear, and you can give an empty return type as ‘{}’.

     The information on return values may be used to name the return
     variables.  For example, in Perl, returned scalars may be given the
     $RESULT and $STATUS name in the following manner:

          @deftypefn {Sub} {(@var{$result}, @var{$status}) =} @
                               process (@var{$input})
          ... Set @var{$status} to 0 in case of failure ...
          @end deftypefn

     to get output like

      -- Sub: ($RESULT, $STATUS) = process ($INPUT)
          ... Set $STATUS to 0 in case of failure ...

     ‘@deftypefn’ creates an entry in the index of functions for NAME.

‘@deftypefun DATA-TYPE NAME ARGUMENTS...’
     The ‘@deftypefun’ command is the specialized definition command for
     functions.  The command is equivalent to ‘@deftypefn Function ...’.

     ‘@deftypefun’ creates an entry in the index of functions for NAME.

   Ordinarily, the return type is printed on the same line as the
function name and arguments, as shown above.  In source code, GNU style
for typed functions is to put the return type on a line by itself.  So
Texinfo provides an option to do that: ‘@deftypefnnewline on’.

   This affects the generic functions only--not untyped functions with
simple arguments such as ‘@deffn’, not typed variables, etc.
Specifically, it affects the commands in this section, and the analogous
commands for object-oriented languages, namely ‘@deftypeop’ and
‘@deftypemethod’ (see Object-Oriented Methods).

   Specifying ‘@deftypefnnewline off’ reverts to the default.

14.6.3 Variables and Similar Entities
-------------------------------------

Here are the commands for defining variables and similar entities:

‘@defvr CATEGORY NAME’
     The ‘@defvr’ command is a general definition command for something
     like a variable--an entity that records a value.  You must choose a
     term to describe the category of entity being defined; for example,
     "Variable" could be used if the entity is a variable.  Write the
     ‘@defvr’ command at the beginning of a line and follow it on the
     same line by the category of the entity and the name of the entity.

     We recommend capitalizing the category name like a title.  If the
     name of the category contains spaces, as in the name "User Option",
     enclose it in braces.  Otherwise, the second word will be mistaken
     for the name of the entity.  For example,

          @defvr {User Option} fill-column
          This buffer-local variable specifies
          the maximum width of filled lines.
          ...
          @end defvr

     Terminate the definition with ‘@end defvr’ on a line of its own.

     ‘@defvr’ creates an entry in the index of variables for NAME.

‘@defvar NAME’
     The ‘@defvar’ command is the definition command for variables.
     ‘@defvar’ is equivalent to ‘@defvr Variable ...’.

     For example:

          @defvar kill-ring
          ...
          @end defvar

     ‘@defvar’ creates an entry in the index of variables for NAME.

‘@defopt NAME’
     The ‘@defopt’ command is the definition command for “user options”,
     i.e., variables intended for users to change according to taste;
     Emacs has many such (see Variables (emacs)).  ‘@defopt’ is
     equivalent to ‘@defvr {User Option} ...’.

14.6.4 Variables in Typed Languages
-----------------------------------

Variables in typed languages are handled in a manner similar to
functions in typed languages.  See Typed Functions.  The general
definition command ‘@deftypevr’ corresponds to ‘@deftypefn’ and the
specialized definition command ‘@deftypevar’ corresponds to
‘@deftypefun’.

‘@deftypevr CATEGORY DATA-TYPE NAME’
     The ‘@deftypevr’ command is the general definition command for
     something like a variable in a typed language--an entity that
     records a value.  You must choose a term to describe the category
     of the entity being defined; for example, "Variable" could be used
     if the entity is a variable.

     The ‘@deftypevr’ command is written at the beginning of a line and
     is followed on the same line by the category of the entity being
     described, the data type, and the name of this particular entity.

     For example:

          @deftypevr {Global Flag} int enable
          ...
          @end deftypevr

     produces the following:

           -- Global Flag: int enable
               ...

‘@deftypevar DATA-TYPE NAME’
     The ‘@deftypevar’ command is the specialized definition command for
     variables in typed languages.  ‘@deftypevar’ is equivalent to
     ‘@deftypevr Variable ...’.

   These commands create entries in the index of variables.

14.6.5 Data Types
-----------------

Here is the command for data types:

‘@deftp CATEGORY NAME ATTRIBUTES...’
     The ‘@deftp’ command is the generic definition command for data
     types.  The command is written at the beginning of a line and is
     followed on the same line by the category, by the name of the type
     (which is a word like ‘int’ or ‘float’), and then by names of
     attributes of objects of that type.  Thus, you could use this
     command for describing ‘int’ or ‘float’, in which case you could
     use ‘data type’ as the category.  (A data type is a category of
     certain objects for purposes of deciding which operations can be
     performed on them.)

     In Lisp, for example, “pair” names a particular data type, and an
     object of that type has two slots called the CAR and the CDR.  Here
     is how you would write the first line of a definition of ‘pair’.

          @deftp {Data type} pair car cdr
          ...
          @end deftp

     ‘@deftp’ creates an entry in the index of data types.

14.6.6 Object-Oriented Programming
----------------------------------

Here are the commands for formatting descriptions about abstract
objects, such as are used in object-oriented programming.  A class is a
defined type of abstract object.  An instance of a class is a particular
object that has the type of the class.  An instance variable is a
variable that belongs to the class but for which each instance has its
own value.

14.6.6.1 Object-Oriented Variables
..................................

These commands allow you to define different sorts of variables in
object-oriented programming languages.

‘@defcv CATEGORY CLASS NAME’
     The ‘@defcv’ command is the general definition command for
     variables associated with classes in object-oriented programming.
     The ‘@defcv’ command is followed by three arguments: the category
     of thing being defined, the class to which it belongs, and its
     name.  For instance:

          @defcv {Class Option} Window border-pattern
          ...
          @end defcv

     produces:
      -- Class Option of Window: border-pattern
          ...

     ‘@defcv’ creates an entry in the index of variables.

‘@deftypecv CATEGORY CLASS DATA-TYPE NAME’
     The ‘@deftypecv’ command is the definition command for typed class
     variables in object-oriented programming.  It is analogous to
     ‘@defcv’ with the addition of the DATA-TYPE parameter to specify
     the type of the instance variable.

          @deftypecv {Class Option} Window int border-pattern
          ...
          @end deftypecv

     produces:

      -- Class Option of Window: int border-pattern
          ...

     ‘@deftypecv’ creates an entry in the index of variables.

‘@defivar CLASS NAME’
     The ‘@defivar’ command is the definition command for instance
     variables in object-oriented programming.  ‘@defivar’ is equivalent
     to ‘@defcv {Instance Variable} ...’.  For instance:

          @defivar Window border-pattern
          ...
          @end defivar

     produces:

      -- Instance Variable of Window: border-pattern
          ...

     ‘@defivar’ creates an entry in the index of variables.

‘@deftypeivar CLASS DATA-TYPE NAME’
     The ‘@deftypeivar’ command is the definition command for typed
     instance variables in object-oriented programming.  It is analogous
     to ‘@defivar’ with the addition of the DATA-TYPE parameter to
     specify the type of the instance variable.

          @deftypeivar Window int border-pattern
          ...
          @end deftypeivar

     produces:

      -- Instance Variable of Window: int border-pattern
          ...

     ‘@deftypeivar’ creates an entry in the index of variables.

14.6.6.2 Object-Oriented Methods
................................

These commands allow you to define different sorts of function-like
entities resembling methods in object-oriented programming languages.
These entities take arguments, as functions do, but are associated with
particular classes of objects.

‘@defop CATEGORY CLASS NAME ARGUMENTS...’
     The ‘@defop’ command is the definition command for these
     method-like entities with simple arguments.

     For example, some systems have constructs called “wrappers” that
     are associated with classes as methods are, but that act more like
     macros than like functions.  You could use ‘@defop Wrapper’ to
     describe one of these.

     Sometimes it is useful to distinguish methods and “operations”.
     You can think of an operation as the specification for a method.
     Thus, a window system might specify that all window classes have a
     method named ‘expose’; we would say that this window system defines
     an ‘expose’ operation on windows in general.  Typically, the
     operation has a name and also specifies the pattern of arguments;
     all methods that implement the operation must accept the same
     arguments, since applications that use the operation do so without
     knowing which method will implement it.

     Often it makes more sense to document operations than methods.  For
     example, window application developers need to know about the
     ‘expose’ operation, but need not be concerned with whether a given
     class of windows has its own method to implement this operation.
     To describe this operation, you would write:

          @defop Operation windows expose

     The ‘@defop’ command is written at the beginning of a line and is
     followed on the same line by the overall name of the category of
     operation, the name of the class of the operation, the name of the
     operation, and its arguments, if any.

     ‘@defop’ creates an entry, such as '‘expose’ on ‘windows’', in the
     index of functions.

‘@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...’
     The ‘@deftypeop’ command is the generic definition command for
     operations in object-oriented programming.  It is particularly
     suitable for typed object-oriented languages.  It is similar to
     ‘@defop’ with the addition of the DATA-TYPE parameter to specify
     information on the return value of the method, for example the
     return type.

‘@defmethod CLASS NAME ARGUMENTS...’
     The ‘@defmethod’ command is the definition command for methods in
     object-oriented programming.  A method is a kind of function that
     implements an operation for a particular class of objects and its
     subclasses.

     ‘@defmethod’ is equivalent to ‘@defop Method ...’.  The command is
     written at the beginning of a line and is followed by the name of
     the class of the method, the name of the method, and its arguments,
     if any.

     For example:
          @defmethod bar-class bar-method argument
          ...
          @end defmethod

     illustrates the definition for a method called ‘bar-method’ of the
     class ‘bar-class’.  The method takes an argument.

     ‘@defmethod’ creates an entry in the index of functions.

‘@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...’
     The ‘@deftypemethod’ command is the definition command for methods
     in object-oriented languages, in particular for typed languages
     such as C++ and Java.  It is similar to the ‘@defmethod’ command
     with the addition of the DATA-TYPE parameter to specify information
     on the return value of the method, for example the return type.

   The commands with information on return values are affected by the
‘@deftypefnnewline’ option (see Functions in Typed Languages).

14.7 Generic Definition Commands
================================

Texinfo provides commands for definitions that do not produce automatic
index entries.

   You create a generic definition environment with ‘@defblock’ paired
with ‘@end defblock’.  Within this environment, use a ‘@defline’ or
‘@deftypeline’ line for each symbol you document.  For example:

     @defblock
     @defline Macro mac (arg1, arg2)
     Description of mac.
     @deftypeline Builtin int foo (int @var{bar})
     Description of foo.
     @end defblock

This produces the output:

 -- Macro: mac (arg1, arg2)
     Description of mac.
 -- Builtin: int foo (int BAR)
     Description of foo.

   The syntax of ‘@defline’ is similar to that of ‘@deffn’.  The first
argument gives a category for the definition.  Follow this with the
symbol name, followed by any parameters.  You should surround any
arguments containing spaces with braces.

   You use ‘@deftypeline’ in a similar way to ‘@deftypefn’, following
the category with a data type, and marking any parameters with ‘@var’.
(see Typed Functions).)

   To share the same description for multiple symbols, you can put
several ‘@defline’ lines together.  For example:

     @defblock
     @defline Function set-var (value)
     @defline {Settable Variable} var
     Description of set-var and var.
     @end defblock

This produces the output:

 -- Function: set-var (value)
 -- Settable Variable: var
     Description of set-var and var.

   It may be useful to define line macros (see Line Macros) in
combination with these commands.

14.8 Conventions for Writing Definitions
========================================

A manual need not and should not contain more than one definition for a
given name.  An appendix containing a summary should use ‘@table’ rather
than the definition commands.

   When you write a definition using ‘@deffn’, ‘@defun’, or one of the
other definition commands, please take care to use arguments that
indicate the meaning, as with the COUNT argument to the ‘forward-word’
function.  Also, if the name of an argument contains the name of a type,
such as INTEGER, take care that the argument actually is of that type.

   _Fonts._  As Texinfo is a semantic language, you should nearly never
need to specify font styles with explicit font commands in definitions
(see Fonts).  However, you may be need to work around problems for
particular output formats and/or constructs.  Here are some
possibilities:

   • Explicitly marking a Lisp keyword like ‘&KEYWORD’ with
     ‘@r{&keyword}’, producing &keyword.

     Note such keywords in definition arguments are (at present)
     rendered in roman in TeX, but this formatting is not done in any
     other output format.

   • ‘@r{@slanted{argument}}’, producing argument, similar to ‘@var’ but
     avoiding upper-casing its argument in Info output.

     In this and the previous point, ‘@r’ resets the font from that
     being used in the definition line context (slanted or typewriter)
     to a roman, upright style.

   • You could use ‘@t’ (or even ‘@r{@t{...’, using ‘@r’ to reset font
     styles) to mark literal syntax on a definition line where text
     would otherwise be output in the slanted roman style.  ‘@code’
     would be inappropriate here as it adds quotation marks in Info
     output.

   Some degree of trial and error may be needed to get the result you
want.  As ever, how nested font commands combine depends on the output
format, so should be avoided where possible.

   Hopefully, such usages are kept to a minimum.  One possibility is to
wrap these in ‘@macro’ (see Defining New Texinfo Commands), allowing
these usages to be easily changed in the future.

14.9 A Sample Function Definition
=================================

Here is a definition from Calling Functions (elisp), using the
‘@defun’ command.  The name of the function, ‘apply’, follows
immediately after the ‘@defun’ command and it is followed, on the same
line, by the parameter list.

      -- Function: apply function &rest arguments
          ‘apply’ calls FUNCTION with ARGUMENTS, just like ‘funcall’ but
          with one difference: the last of ARGUMENTS is a list of
          arguments to give to FUNCTION, rather than a single argument.
          We also say that this list is “appended” to the other
          arguments.

          ‘apply’ returns the result of calling FUNCTION.  As with
          ‘funcall’, FUNCTION must either be a Lisp function or a
          primitive function; special forms and macros do not make sense
          in ‘apply’.

               (setq f 'list)
                   ⇒ list
               (apply f 'x 'y 'z)
               error→ Wrong type argument: listp, z
               (apply '+ 1 2 '(3 4))
                   ⇒ 10
               (apply '+ '(1 2 3 4))
                   ⇒ 10

               (apply 'append '((a b c) nil (x y z) nil))
                   ⇒ (a b c x y z)

          An interesting example of using ‘apply’ is found in the
          description of ‘mapcar’.

   In the Texinfo source file, this example should look like this:

     @defun apply function @r{&rest} arguments
     @code{apply} calls @var{function} with
     @var{arguments}, just like @code{funcall} but with one
     difference: the last of @var{arguments} is a list of
     arguments to give to @var{function}, rather than a single
     argument.  We also say that this list is @dfn{appended}
     to the other arguments.

     @code{apply} returns the result of calling
     @var{function}.  As with @code{funcall},
     @var{function} must either be a Lisp function or a
     primitive function; special forms and macros do not make
     sense in @code{apply}.

     @example
     (setq f 'list)
         @result{} list
     (apply f 'x 'y 'z)
     @error{} Wrong type argument: listp, z
     (apply '+ 1 2 '(3 4))
         @result{} 10
     (apply '+ '(1 2 3 4))
         @result{} 10

     (apply 'append '((a b c) nil (x y z) nil))
         @result{} (a b c x y z)
     @end example

     An interesting example of using @code{apply} is found
     in the description of @code{mapcar}.
     @end defun

In this manual, this function is listed in the Command Index under
‘apply’.

15 Internationalization
***********************

Texinfo has some support for writing in languages other than English,
although this area still needs considerable work.  (If you are the one
helping to translate the fixed strings written to documents, see
Internationalization of Document Strings.)

   For a list of the various accented and special characters Texinfo
supports, see Inserting Accents.

15.1 ‘@documentlanguage LL[_CC]’: Set the Document Language
===========================================================

The ‘@documentlanguage’ command declares the current document locale.
Write it on a line by itself, near the beginning of the file.

     @documentlanguage LL[_CC]

   Include a two-letter (or three-letter) ISO 639-2 language code (LL)
following the command name, optionally followed by an underscore and
two-letter ISO 3166 two-letter country code (CC).  If you have a
multilingual document, the intent is to be able to use this command
multiple times, to declare each language change.

   As with GNU Gettext (see gettext), if the country code is
omitted, the main dialect is assumed where possible.  For example, ‘de’
is equivalent to ‘de_DE’ (German as spoken in Germany).

   This command changes the translation of various “document strings”
such as "see" in cross-references (see Cross References), "Function"
in defuns (see Definition Commands), and so on.  Optionally, this
command may also affect how ‘texi2any’ sorts indices (see Global Customization Variables,
under ‘DOCUMENTLANGUAGE_COLLATION’).  If the
document language is not specified, the default English document strings
are output as they are.

   Note that in Info output, some strings, such as "Node:", "Next:",
"Menu:", etc., are keywords and so are not translated.

   In DocBook output ‘@documentlanguage’ sets the language for following
sections.

   For LaTeX, this command causes code to load the ‘babel’ package to be
output in the preamble, and ‘\selectlanguage’ to be output.

   For TeX, this command causes a file ‘txi-LOCALE.tex’ to be read (if
it exists).  If ‘@documentlanguage’ argument contains the optional ‘_CC’
suffix, this is tried first.  For example, with ‘@documentlanguage
de_DE’, TeX first looks for ‘txi-de_DE.tex’, then ‘txi-de.tex’.

   Such a ‘txi-*’ file is intended to redefine the various English words
used in TeX output, such as 'Chapter', 'See', and so on.  We are aware
that individual words like these cannot always be translated in
isolation, and that a very different strategy would be required for
ideographic (among other) scripts.  Help in improving Texinfo's language
support is welcome.

   ‘@documentlanguage’ also changes TeX's current hyphenation patterns,
if the TeX program being run has the necessary support included.  This
will generally not be the case for ‘tex’ itself, but will usually be the
case for up-to-date distributions of the extended TeX programs ‘etex’
(DVI output) and ‘pdftex’ (PDF output).  ‘texi2dvi’ will use the
extended TeXs if they are available (see Format with texi2dvi).

   Since the lists of language codes and country codes are updated
relatively frequently, we don't attempt to list them here.  The valid
language codes are on the official home page for ISO 639,
<http://www.loc.gov/standards/iso639-2/>.  The country codes and the
official web site for ISO 3166 can be found via
<https://en.wikipedia.org/wiki/ISO_3166>.

15.2 ‘@documentencoding ENC’: Set Input Encoding
================================================

By default, the input and output document encoding are assumed to be
UTF-8, the vast global character encoding, expressed in 8-bit bytes.
UTF-8 is compatible with 7-bit ASCII. It is recommended to use UTF-8
encoding for Texinfo manuals.

   The ‘@documentencoding’ command declares the input document encoding,
and also affects the encoding of the output.  Write it on a line by
itself, with a valid encoding specification following, near the
beginning of the file if your document encoding is not the default
encoding.

     @documentencoding ENC

   UTF-8 should always be the best choice for the encoding.  Texinfo
still supports additional encodings, mainly for compatibility with older
manuals(1):

‘US-ASCII’
     Character encoding based on the English alphabet.

‘ISO-8859-1’
‘ISO-8859-15’
‘ISO-8859-2’
     These specify the pre-UTF-8 standard encodings for Western European
     (the first two) and Eastern European languages (the third),
     respectively.  ISO 8859-15 replaces some little-used characters
     from 8859-1 (e.g., precomposed fractions) with more commonly needed
     ones, such as the Euro symbol (€).

     A full description of the encodings is beyond our scope here; one
     useful reference is <http://czyborra.com/charsets/iso8859.html>.

‘koi8-r’
     This was a commonly used encoding for the Russian language before
     UTF-8.

‘koi8-u’
     This was a commonly used encoding for the Ukrainian language before
     UTF-8.

   In Info output, a so-called 'Local Variables' section (see
File Variables (emacs)) is output including the output encoding.  This
allows Info readers to set the encoding appropriately.  It looks like
this:

     Local Variables:
     coding: UTF-8
     End:

   By default, for Info and plain text output, ‘texi2any’ outputs accent
constructs and special characters (such as ‘@'e’) as the actual UTF-8
sequence or 8-bit character in the output encoding where possible.  If
this is not possible, or if the option ‘--disable-encoding’ is given, an
ASCII transliteration is used instead.

   In HTML output, a ‘<meta>’ tag is output, in the ‘<head>’ section of
the HTML, that specifies the output encoding.  Web servers and browsers
cooperate to use this information so the correct encoding is used to
display the page, if supported by the system.  That looks like this:

     <meta http-equiv="Content-Type" content="text/html;
          charset=utf-8">

   In HTML and LaTeX output, if ‘OUTPUT_CHARACTERS’ is set (see
Customization Variables for Multiple Formats), accent constructs and
special characters, such as ‘@'e’ or ‘``’, are output as the actual
UTF-8 sequence or 8-bit character in the output encoding where possible.
Otherwise, HTML entities are used for those characters in HTML, and
LaTeX macros are used in LaTeX.

   In DocBook output, if the encoding is different from UTF-8, an
‘encoding’ attribute is added to the XML declaration.  If
‘OUTPUT_CHARACTERS’ is set (see Customization Variables for Multiple Formats),
accent constructs such as ‘@'e’ are output as the actual
8-bit or UTF-8 character in the output encoding where possible.
Otherwise XML entities are used for those constructs.

   In TeX output, the characters which are supported in the standard
Computer Modern fonts are output accordingly.  For example, this means
using constructed accents rather than precomposed glyphs.  Using a
missing character generates a warning message, as does specifying an
unimplemented encoding.

   Although modern TeX systems support nearly every script in use in the
world, this wide-ranging support is not available in ‘texinfo.tex’, and
it's not feasible to duplicate or incorporate all that effort.

   In LaTeX output, code loading the ‘inputenc’ package is output based
on the encoding.  This, by itself, does not ensures that all the
characters from the input document can be subsequently output.  The
fonts used in the default case should cover the specific Texinfo glyphs,
but not all the possible encoded characters.  You may need to load
different fonts in the preamble and use ‘\DeclareUnicodeCharacter’ with
a UTF-8 encoding.  For example:
     @latex
     \DeclareUnicodeCharacter{017B}{\.Z}
     @end latex

   Cross-references between Info files in different character encodings
with non-ASCII characters in node names fail.  We strongly recommend
using UTF-8 only as the encoding for manuals with non-ASCII characters
in the destinations of cross-references.

   ---------- Footnotes ----------

   (1) ‘texi2any’ supports more encodings for Texinfo manuals,
potentially all the encodings supported by both Perl and iconv (see
Generic Charset Conversion (libc)).  The support in output formats may
be lacking, however, especially for LaTeX output.

16 Conditionally Visible Text
*****************************

The “conditional commands” allow you to use different text for different
output formats, or for general conditions that you define.  For example,
you can use them to specify different text for the printed manual and
the Info output.

   The conditional commands comprise the following categories.

   • Commands specific to an output format (Info, TeX, HTML, ...).

   • Commands specific to any output format _excluding_ a given one
     (e.g., not Info, not TeX, ...).

   • 'Raw' formatter text for any output format, passed straight through
     with minimal (but not zero) interpretation of @-commands.

   • Format-independent variable substitutions, and testing if a
     variable is set or clear.

16.1 Conditional Commands
=========================

Texinfo has an ‘@ifFORMAT’ environment for each output format, to allow
conditional inclusion of text for a particular output format.

   ‘@ifinfo’ begins segments of text that should be ignored when not
producing Info output, in particular in printed output.  The segment of
text appears only in the Info file and, for historical compatibility,
the plain text output.

   The environments for the other formats are analogous:

‘@ifdocbook ... @end ifdocbook’
     Text to appear only in the DocBook output.

‘@ifhtml ... @end ifhtml’
     Text to appear only in the HTML output.

‘@iflatex ... @end iflatex’
     Text to appear only in the LaTeX output.

‘@ifplaintext ... @end ifplaintext’
     Text to appear only in the plain text output.

‘@iftex ... @end iftex’
     Text to appear only in the printed manual.

‘@ifxml ... @end ifxml’
     Text to appear only in the XML output.

   The ‘@if...’ and ‘@end if...’ commands must appear on lines by
themselves in your source file.  The newlines following the commands are
(more or less) treated as whitespace, so that the conditional text is
flowed normally into a surrounding paragraph.

   The ‘@if...’ constructs are intended to conditionalize normal Texinfo
source; see Raw Formatter Commands, for using underlying format
commands directly.

   Here is an example showing all these conditionals:

     @iftex
     This text will appear only in the printed manual.
     @end iftex
     @ifinfo
     However, this text will appear only in Info and plain text.
     @end ifinfo
     @ifhtml
     And this text will only appear in HTML.
     @end ifhtml
     @iflatex
     Moreover, this text will only appear in @LaTeX{}.
     @end iflatex
     @ifplaintext
     Whereas this text will only appear in plain text.
     @end ifplaintext
     @ifxml
     Notwithstanding that this will only appear in XML.
     @end ifxml
     @ifdocbook
     Nevertheless, this will only appear in DocBook.
     @end ifdocbook

The preceding example produces the following line:

   However, this text will appear only in Info and plain text.

Notice that you only see one of the input lines, depending on which
version of the manual you are reading.

   In complex documents, you may want Texinfo to issue an error message
in some conditionals that should not ever be processed.  The
‘@errormsg{TEXT}’ command will do this; it takes one argument, the text
of the error message.

   We mention ‘@errormsg{}’ here even though it is not strictly related
to conditionals, since in practice it is most likely to be useful in
that context.  Technically, it can be used anywhere.  See External Macro Processors,
for a caveat regarding the line numbers which
‘@errormsg’ emits in TeX.

16.2 Conditional Not Commands
=============================

You can specify text to be included in any output format _other_ than a
given one with the ‘@ifnot...’ environments:

     @ifnotdocbook ... @end ifnotdocbook
     @ifnothtml ... @end ifnothtml
     @ifnotinfo ... @end ifnotinfo
     @ifnotlatex ... @end ifnotlatex
     @ifnotplaintext ... @end ifnotplaintext
     @ifnottex ... @end ifnottex
     @ifnotxml ... @end ifnotxml

The ‘@ifnot...’ command and the ‘@end’ command must appear on lines by
themselves in your actual source file.

   If the output file is being made in the given format, the region is
_ignored_.  Otherwise, it is included.

   There is one exception (for historical compatibility): ‘@ifnotinfo’
text is omitted for both Info and plain text output, not just Info.  To
specify text which appears only in Info and not in plain text, use
‘@ifnotplaintext’, like this:

     @ifinfo
     @ifnotplaintext
     This will be in Info, but not plain text.
     @end ifnotplaintext
     @end ifinfo

   The regions delimited by these commands are ordinary Texinfo source
as with ‘@iftex’, not raw formatter source as with ‘@tex’ (see Raw Formatter Commands).

16.3 Raw Formatter Commands
===========================

The ‘@if...’ conditionals just described must be used only with normal
Texinfo source.  For instance, most features of plain TeX will not work
within ‘@iftex’.  The purpose of ‘@if...’ is to provide conditional
processing for Texinfo source, not provide access to underlying
formatting features.  For that, Texinfo provides so-called “raw
formatter commands”.  They should only be used when truly required (most
documents do not need them).

   The first raw formatter command is ‘@tex’.  You can enter plain TeX
completely, and use ‘\’ in the TeX commands, by delineating a region
with the ‘@tex’ and ‘@end tex’ commands.  All plain TeX commands and
category codes are restored within a ‘@tex’ region.  The sole exception
is that the ‘@’ character still introduces a command, so that ‘@end tex’
can be recognized.  Texinfo processors will not output material in such
a region unless TeX output is being produced.

   In complex cases, you may wish to define new TeX macros within
‘@tex’.  You must use ‘\gdef’ to do this, not ‘\def’, because ‘@tex’
regions are processed in a TeX group.  If you need to make several
definitions, you may wish to set ‘\globaldefs=1’ (its value will be
restored to zero as usual when the group ends at ‘@end tex’, so it won't
cause problems with the rest of the document).

   As an example, here is a displayed equation written in plain TeX:

     @tex
     $$ \chi^2 = \sum_{i=1}^N
              \left (y_i - (a + b x_i)
              \over \sigma_i\right)^2 $$
     @end tex

The output of this example will appear only in a printed manual.  If you
are reading this in a format not generated by TeX, you will not see the
equation that appears in the printed manual.

   Analogously, you can use ‘@html ... @end html’ for a region of raw
HTML, ‘@docbook ... @end docbook’ for a region of raw DocBook, ‘@latex
... @end latex’ for a region of raw LaTeX, and ‘@xml ... @end xml’ for a
region of raw XML.

   The behavior of newlines in raw regions is unspecified.

   In all cases, in raw processing, ‘@’ retains the same meaning as in
the remainder of the document.  Thus, the Texinfo processors must
recognize and even execute, to some extent, the contents of the raw
regions, regardless of the final output format.  Therefore, specifying
changes that globally affect the document inside a raw region leads to
unpredictable and generally undesirable behavior.  For example, using
the ‘@kbdinputstyle’ command inside a raw region is undefined.  The
remedy is simple: don't do that.

16.4 Inline Conditionals: ‘@inline’, ‘@inlineifelse’, ‘@inlineraw’
==================================================================

Texinfo provides a set of conditional commands with arguments given
within braces:

‘@inlinefmt{FORMAT, TEXT}’
     Process the Texinfo TEXT if FORMAT output is being generated.

‘@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}’
     Process the Texinfo THEN-TEXT if FORMAT output is being generated;
     otherwise, process ELSE-TEXT.

‘@inlineraw{FORMAT, TEXT}’
     Similar, but for raw TEXT (see Raw Formatter Commands).

   The supported FORMAT names are:

     docbook  html  info  latex  plaintext  tex  xml

   For example,

     @inlinefmt{html, @emph{HTML-only text}}

is nearly equivalent to

     @ifhtml
     @emph{HTML-only text}
     @end ifhtml

except that no whitespace is added, as happens in the latter
(environment) case.

   In these commands, whitespace is ignored after the comma separating
the arguments, as usual, but is _not_ ignored at the end of TEXT.

   To insert a literal at sign, left brace, or right brace in one of the
arguments, you must use the alphabetic commands ‘@atchar{}’ (see
Inserting an Atsign), and ‘@lbracechar{}’ or ‘@rbracechar{}’ (see
Inserting Braces), or the parsing will become confused.

   With ‘@inlinefmtifelse’, it is also necessary to use ‘@comma{}’ to
avoid mistaking a ‘,’ in the text for the delimiter.  With ‘@inlinefmt’
and ‘@inlineraw’, ‘@comma{}’ is not required (though it's fine to use
it), since these commands always have exactly two arguments.

   For TeX, the processed TEXT cannot contain newline-delimited
commands.  Text to be ignored (i.e., for non-TeX) can, though.

   Two other ‘@inline...’ conditionals complement the ‘@ifset’ and
‘@ifclear’ commands; see the next section.

16.5 Flags: ‘@set’, ‘@clear’, conditionals, and ‘@value’
========================================================

You can direct the Texinfo formatting commands to format or ignore parts
of a Texinfo file with the ‘@set’, ‘@clear’, ‘@ifset’, and ‘@ifclear’
commands.  Here is a summary:

‘@set FLAG [VALUE]’
     Set the variable FLAG, to the optional VALUE if specified.

‘@clear FLAG’
     Undefine the variable FLAG, whether or not it was previously
     defined.

‘@ifset FLAG’
     If FLAG is set, text through the next ‘@end ifset’ command is
     formatted.  If FLAG is clear, text through the following ‘@end
     ifset’ command is ignored.

‘@inlineifset{FLAG, TEXT}’
     Brace-delimited version of ‘@ifset’.

‘@ifclear FLAG’
     If FLAG is set, text through the next ‘@end ifclear’ command is
     ignored.  If FLAG is clear, text through the following ‘@end
     ifclear’ command is formatted.

‘@inlineifclear{FLAG, TEXT}’
     Brace-delimited version of ‘@ifclear’.

16.5.1 ‘@set’ and ‘@value’
--------------------------

You use the ‘@set’ command to specify a value for a flag, which is later
expanded by the ‘@value’ command.

   A “flag” (aka “variable”) name is an identifier starting with an
alphanumeric, ‘-’, or ‘_’.  Subsequent characters, if any, may not be
whitespace, ‘@’, braces, angle brackets, or any of ‘~`^+|’; other
characters, such as ‘%’, may work.  However, it is best to use only
letters and numerals in a flag name, not ‘-’ or ‘_’ or others--they will
work in some contexts, but not all, due to limitations in TeX.

   The value is the remainder of the input line, and can contain
anything.

   Write the ‘@set’ command like this:

     @set foo This is a string.

This sets the value of the flag ‘foo’ to "This is a string.".

   The Texinfo processors then replace a ‘@value{FLAG}’ command with the
string to which FLAG is set.  Thus, when ‘foo’ is set as shown above,
the Texinfo processors convert this:

     @value{foo}
to this:
     This is a string.

   You can write a ‘@value’ command within a paragraph; but you must
write a ‘@set’ command on a line of its own.

   If you write the ‘@set’ command like this:

     @set foo

without specifying a string, the value of ‘foo’ is the empty string.

   If you clear a previously set flag with ‘@clear FLAG’, a subsequent
‘@value{flag}’ command will report an error.

   For example, if you set ‘foo’ as follows:

     @set howmuch very, very, very

then the processors transform

     It is a @value{howmuch} wet day.
into
     It is a very, very, very wet day.

   If you write

     @clear howmuch

then the processors transform

     It is a @value{howmuch} wet day.
into
     It is a {No value for "howmuch"} wet day.

   ‘@value’ cannot be reliably used as the argument to an accent command
(see Inserting Accents).  For example, this fails:

     @set myletter a
     @'@value{myletter}

16.5.2 ‘@ifset’ and ‘@ifclear’
------------------------------

When a FLAG is set, the Texinfo formatting commands format text between
subsequent pairs of ‘@ifset FLAG’ and ‘@end ifset’ commands.  When the
FLAG is cleared, the Texinfo formatting commands do _not_ format the
text.  ‘@ifclear’ operates analogously.

   Write the conditionally formatted text between ‘@ifset FLAG’ and
‘@end ifset’ commands, like this:

     @ifset FLAG
     CONDITIONAL-TEXT
     @end ifset

   For example, you can create one document that has two variants, such
as a manual for a 'large' and 'small' model:

     You can use this machine to dig up shrubs
     without hurting them.

     @set large

     @ifset large
     It can also dig up fully grown trees.
     @end ifset

     Remember to replant promptly ...

In the example, the formatting commands will format the text between
‘@ifset large’ and ‘@end ifset’ because the ‘large’ flag is set.

   When FLAG is cleared, the Texinfo formatting commands do _not_ format
the text between ‘@ifset FLAG’ and ‘@end ifset’; that text is ignored
and does not appear in the output.

   For example, if you clear the flag of the preceding example by
writing an ‘@clear large’ command after the ‘@set large’ command (but
before the conditional text), then the Texinfo formatting commands
ignore the text between the ‘@ifset large’ and ‘@end ifset’ commands.
In the formatted output, that text does not appear; you see only the
lines that say, "You can use this machine to dig up shrubs without
hurting them.  Remember to replant promptly ...".

   If a flag is cleared with a ‘@clear FLAG’ command, then the
formatting commands format text between subsequent pairs of ‘@ifclear’
and ‘@end ifclear’ commands.  But if the flag is set with ‘@set FLAG’,
then the formatting commands do _not_ format text between an ‘@ifclear’
and an ‘@end ifclear’ command; rather, they ignore that text.  An
‘@ifclear’ command looks like this:

     @ifclear FLAG

16.5.3 ‘@inlineifset’ and ‘@inlineifclear’
------------------------------------------

‘@inlineifset’ and ‘@inlineifclear’ provide brace-delimited alternatives
to the ‘@ifset’ and ‘@ifclear’ forms, similar to the other ‘@inline...’
Commands (see Inline Conditionals).  The same caveats about argument
parsing given there apply here too.

‘@inlineifset{VAR, TEXT}’
     Process the Texinfo TEXT if the flag VAR is defined.

‘@inlineifclear{VAR, TEXT}’
     Process the Texinfo TEXT if the flag VAR is not defined.

   Except for the syntax, their general behavior and purposes is the
same as with ‘@ifset’ and ‘@ifclear’, described in the previous section.

16.5.4 ‘@value’ Example
-----------------------

You can use the ‘@value’ command to minimize the number of places you
need to change when you record an update to a manual.  See GNU Sample Texts,
for the full text of an example of using this to work with
Automake distributions.

   This example is adapted from make.

  1. Set the flags:

          @set EDITION 0.35 Beta
          @set VERSION 3.63 Beta
          @set UPDATED 14 August 1992
          @set UPDATE-MONTH August 1992

  2. Write text for the ‘@copying’ section (see @copying):

          @copying
          This is Edition @value{EDITION},
          last updated @value{UPDATED},
          of @cite{The GNU Make Manual},
          for @code{make}, version @value{VERSION}.

          Copyright ...

          Permission is granted ...
          @end copying

  3. Write text for the title page, for people reading the printed
     manual:

          @documentinfo
          @title GNU Make
          @subtitle A Program for Directing Recompilation
          @subtitle Edition @value{EDITION}, ...
          @subtitle @value{UPDATE-MONTH}
          @end documentinfo

     (On a printed cover, a date listing the month and the year looks
     less fussy than a date listing the day as well as the month and
     year.)

  4. Write text for the Top node, for people reading the Info file:

          @ifnottex
          @node Top
          @top Make

          This is Edition @value{EDITION},
          last updated @value{UPDATED},
          of @cite{The GNU Make Manual},
          for @code{make}, version @value{VERSION}.
          @end ifnottex

     After you format the manual, the ‘@value’ constructs have been
     expanded, so the output contains text like this:

          This is Edition 0.35 Beta, last updated 14 August 1992,
          of `The GNU Make Manual', for `make', Version 3.63 Beta.

   When you update the manual, you change only the values of the flags;
you do not need to edit the three sections.

16.6 Testing for Texinfo Commands: ‘@ifcommanddefined’, ‘@ifcommandnotdefined’
==============================================================================

Occasionally, you may want to arrange for your manual to test if a given
Texinfo command is available and (presumably) do some sort of fallback
formatting if not.  There are conditionals ‘@ifcommanddefined’ and
‘@ifcommandnotdefined’ to do this.  For example:

     @ifcommanddefined node
     Good, @samp{@@node} is defined.
     @end ifcommanddefined

will output the expected 'Good, ‘@node’ is defined.'.

   This conditional will also consider any new commands defined by the
document via ‘@macro’, ‘@alias’, ‘@definfoenclose’, and
‘@def(code)index’ (see Defining New Texinfo Commands) to be true.
Caveat: the TeX implementation reports internal TeX commands, in
addition to all the Texinfo commands, as being "defined"; the ‘texi2any’
implementation is reliable in this regard, however.

   You can check the ‘NEWS’ file in the Texinfo source distribution and
linked from the Texinfo home page
(<https://www.gnu.org/software/texinfo>) to see when a particular
command was added.

   These command-checking conditionals themselves were added in
Texinfo 5.0, released in 2013--decades after Texinfo's inception.  In
order to test if they themselves are available, the predefined flag
‘txicommandconditionals’ can be tested, like this:

     @ifset txicommandconditionals
     @ifcommandnotdefined foobarnode
     (Good, @samp{@@foobarnode} is not defined.)
     @end ifcommandnotdefined
     @end ifset

   Since flags (see the previous section) were added early in the
existence of Texinfo, there is no problem with assuming they are
available.

   We recommend avoiding these tests whenever possible--which is usually
the case.  For many software packages, it is reasonable for all
developers to have a given version of Texinfo (or newer) installed, and
thus no reason to worry about older versions.  (It is straightforward
for anyone to download and install the Texinfo source; it does not have
any problematic dependencies.)

   The issue of Texinfo versions does not generally arise for end users.
With properly distributed packages, users need not process the Texinfo
manual simply to build and install the package; they can use
preformatted Info (or other) output files.  This is desirable in
general, to avoid unnecessary dependencies between packages (see
Releases (standards)).

16.7 Conditional Nesting
========================

Texinfo requires that for a failing conditional, the ignored text must
be properly nested with respect to that failing conditional.  Here's an
example:

     @ifset somevar
     @ifset anothervar
     Both somevar and anothervar are set.
     @end ifset
     @ifclear anothervar
     Somevar is set, anothervar is not.
     @end ifclear
     @end ifset

   If ‘somevar’ is not set, the whole block is skipped.

   To allow the processors to reliably determine which commands to
consider for nesting purposes, all conditional commands must be on lines
by themselves, with no text (even spaces) before or after.

17 Defining New Texinfo Commands
********************************

Texinfo provides several ways to define new commands (in all cases, it's
not recommended to try redefining existing commands):

   • A Texinfo “macro” allows you to define a new Texinfo command as any
     sequence of text and/or existing commands (including other macros).
     The macro can have any number of “parameters”--text you supply each
     time you use the macro.

     Incidentally, these macros have nothing to do with the ‘@defmac’
     command, which is for documenting macros in the subject area of the
     manual (see Def Cmd Template).

   • ‘@linemacro’ allows you to define a macro whose arguments extend to
     the end of the line and are separated by spaces.

   • ‘@alias’ defines a new name for an existing command.

   • ‘@definfoenclose’ allows you to define new commands with customized
     output for some non-printed output formats.  This command is
     deprecated.

   Most generally of all (not just for defining new commands), it is
possible to invoke any external macro processor and have Texinfo
recognize so-called ‘#line’ directives for error reporting.

   If you want to do simple text substitution, ‘@set’ and ‘@value’ is
the simplest approach (see @set @clear @value).

17.1 Defining Macros
====================

You use the Texinfo ‘@macro’ command to define a macro, like this:

     @macro MACRONAME{PARAM1, PARAM2, ...}
     TEXT ... \PARAM1\ ...
     @end macro

   The “parameters” PARAM1, PARAM2, ... correspond to arguments supplied
when the macro is subsequently used in the document (described in the
next section).

   In principle, MACRONAME should consist of alphanumerics, and (except
as the first character) ‘-’.  The ‘_’ character is excluded so that
macros can be called inside ‘@math’ without a following space (see
Inserting Math).  However, for a macro to work consistently with TeX,
MACRONAME must consist entirely of letters: no digits, hyphens, or other
special characters.  So, we recommend using only letters.  Texinfo
commands should not be redefined as macros.

   If a macro needs no parameters, you can define it either with an
empty list (‘@macro foo {}’) or with no braces at all (‘@macro foo’).

   The definition or “body” of the macro can contain most Texinfo
commands, including macro invocations.  However, a macro definition that
defines another macro does not work in TeX due to limitations in the
design of ‘@macro’.

   In the macro body, instances of a parameter name surrounded by
backslashes, as in ‘\PARAM1\’ in the example above, are replaced by the
corresponding argument from the macro invocation.  You can use parameter
names any number of times in the body, including zero.

   To get a single ‘\’ in the macro expansion, use ‘\\’.  Any other use
of ‘\’ in the body yields a warning.

   The newline characters after the ‘@macro’ line and before the ‘@end
macro’ line are ignored, that is, not included in the macro body.  All
other whitespace is treated according to the usual Texinfo rules.

   To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with ‘@rmacro’, like this:

     @rmacro rmac {arg}
     a\arg\b
     @end rmacro
     ...
     @rmac{1@rmac{text}2}

   This produces the output 'a1atextb2b'.  With ‘@macro’ instead of
‘@rmacro’, an error message is given.

   You can undefine a macro FOO with ‘@unmacro FOO’.  It is not an error
to undefine a macro that is already undefined.  For example:

     @unmacro foo

17.2 Invoking Macros
====================

After a macro is defined (see the previous section), you can “invoke”
(use) it in your document like this:

     @MACRONAME {ARG1, ARG2, ...}

and the result will be more or less as if you typed the body of
MACRONAME at that spot.  For example:

     @macro foo {p, q}
     Together: \p\ & \q\.
     @end macro
     @foo{a, b}

produces:

     Together: a & b.

   Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
ignored.  The braces are required in the invocation even when the macro
takes no arguments, consistent with other Texinfo commands.  For
example:

     @macro argless {}
     No arguments here.
     @end macro
     @argless{}

produces:

     No arguments here.

   Passing macro arguments containing commas requires care, since commas
also separate the arguments.  To include a comma character in an
argument, the most reliable method is to use the ‘@comma{}’ command.
Another method is to surround the argument with ‘@asis{...}’.  For
‘texi2any’, you can also prepend a backslash character, as in ‘\,’, but
this does not work with TeX.

   It's not always necessary to worry about commas.  To facilitate use
of macros, two rules for “automatic quoting” are implemented:

  1. If a macro takes only one argument, all commas in its invocation
     are quoted by default.  For example:

          @macro TRYME{text}
          @strong{TRYME: \text\}
          @end macro

          @TRYME{A nice feature, though it can be dangerous.}

     will produce the following output

          *TRYME: A nice feature, though it can be dangerous.*

     And indeed, it can.  Namely, there is no control on the number of
     arguments passed to one-argument macros, so be careful when you
     invoke them.

  2. If a macro invocation includes another command (including a
     recursive invocation of itself), any commas in the nested command
     invocation(s) are quoted by default.  For example, in

          @say{@strong{Yes, I do}, person one}

     the comma after ‘Yes’ is implicitly quoted.  Here's another
     example, with a recursive macro:

          @rmacro cat{a,b}
          \a\\b\
          @end rmacro

          @cat{@cat{foo, bar}, baz}

     will produce the string ‘foobarbaz’.

  3. Otherwise, a comma should be explicitly quoted, as above, for it to
     be treated as a part of an argument.

   The backslash itself can be quoted in macro arguments with another
backslash.  For example:

     @MACNAME {\\bleh}

will pass the argument ‘\bleh’ to MACNAME.

   ‘texi2any’ also recognizes ‘\{’ and ‘\}’ sequences for curly braces,
but these are not recognized by the implementation in TeX.  There
should, however, rarely be a need for these, as they are only needed
when a macro argument contains unbalanced braces.

   If a macro is defined to take exactly one argument, it can be invoked
without any braces, taking all of the line after the macro name as the
argument.  For example:

     @macro bar {p}
     Twice: \p\ & \p\.
     @end macro
     @bar aah

produces:

     Twice: aah & aah.

In these arguments, there is no escaping of special characters, so each
‘\’ stands for itself.

   If a macro is defined to take more than one argument, but is called
with only one (in braces), the remaining arguments are set to the empty
string, and no error is given.  For example:

     @macro addtwo {p, q}
     Both: \p\\q\.
     @end macro
     @addtwo{a}

produces simply:

     Both: a.

17.3 Macro Details and Caveats
==============================

By design, macro expansion should not happen in the following contexts:

   • ‘@macro’ and ‘@unmacro’ lines;

   • ‘@if...’ lines, including ‘@ifset’ and similar;

   • ‘@set’, ‘@clear’, ‘@value’;

   • ‘@clickstyle’ lines;

   • ‘@end’ lines when there is no macro expansion in the block command.

Unfortunately, TeX may do some expansion in these situations, possibly
yielding errors.

   Also, quite a few macro-related constructs cause problems with TeX;
some of the caveats are listed below.  Thus, if you get macro-related
errors when producing the printed version of a manual, you might try
expanding the macros with ‘texi2any’ by invoking ‘texi2dvi’ with the
‘-E’ option (see Format with texi2dvi).  Or, more reliably, eschew
Texinfo macros altogether and use a language designed for macro
processing, such as M4 (see External Macro Processors).

   • As mentioned earlier, macro names must consist entirely of letters.

   • It is not advisable to redefine any TeX primitive, plain, or
     Texinfo command name as a macro.  Unfortunately, this is a large
     and open-ended set of names, and the possible resulting errors are
     unpredictable.

   • Arguments to macros taking more than one argument cannot cross
     lines.

   • Macros containing a command which must be on a line by itself, such
     as a conditional, cannot be invoked in the middle of a line.
     Similarly, macros containing line-oriented commands or text, such
     as ‘@example’ environments, may behave unpredictably in TeX.

   • Texinfo commands in the expansion of a macro in the text of an
     index entry may end up being typeset as literal text (including an
     "@" sign), instead of being interpreted with their intended
     meaning.

   • White space is ignored at the beginnings of lines.

   • Macros can't be reliably used in the argument to accent commands
     (see Inserting Accents).

   • Macros should not be used in node names.  See Node Names.

   • The backslash escape for commas in macro arguments does not work;
     ‘@comma{}’ must be used.

   • Ending a macro body with ‘@c’ may cause text following the macro
     invocation to be ignored as a comment in ‘texi2any’.  This is not
     the case when processing with TeX.  This was often done to "comment
     out" an unwanted newline at the end of a macro body, but this is
     not necessary any more, as the final newline before ‘@end macro’ is
     not included in the macro body anyway.

   • In general, you can't arbitrarily substitute a macro (or ‘@value’)
     call for Texinfo command arguments, even when the text is the same.
     Texinfo is not M4 (or even plain TeX).  It might work with some
     commands, it fails with others.  Best not to do it at all.  For
     instance, this fails:

          @macro offmacro
          off
          @end macro
          @headings @offmacro

     This looks equivalent to ‘@headings off’, but for TeXnical reasons,
     it fails with a mysterious error message (namely, ‘Paragraph ended
     before @headings was complete’).

   • Expanding macros in a math context may lead to poor spacing in TeX
     output.  For example:

          @iftex
          @macro atan
          \\mathop{\\rm atan}
          @end macro
          @end iftex

          @math{@atan{}(x)}

     The braces following ‘@atan’ are treated by TeX as a subformula,
     leading to extra space before the opening parenthesis.  You can
     work around this by defining a raw TeX macro instead:

          @tex
          \gdef\atan#1{\mathop{\rm atan}}
          @end tex

     The ‘#1’ in this definition absorbs the braces, so that the spacing
     is as expected for the ‘\mathop’ object.

   • If you have problems using conditionals within a macro, an
     alternative is to use separate macro definitions inside conditional
     blocks.  For example, instead of

          @macro Mac
          @iftex
          text for TeX output
          @end iftex
          @ifnottex
          text for not TeX output
          @end ifnottex
          @end macro

     you can do the following instead:

          @iftex
          @macro Mac
          text for TeX output
          @end macro
          @end iftex

          @ifnottex
          @macro Mac
          text for not TeX output
          @end macro
          @end ifnottex

   • Macros cannot define macros in the natural way.  To do this, you
     must use conditionals and raw TeX.  For example:

          @ifnottex
          @macro ctor {name, arg}
          @macro \name\
          something involving \arg\ somehow
          @end macro
          @end macro
          @end ifnottex
          @tex
          \gdef\ctor#1{\ctorx#1,}
          \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}}
          @end tex

   The following limitations are by design:

   • If you want to pass an argument with the Texinfo command ‘@,’ (to
     produce a cedilla, see Inserting Accents), you have to use
     ‘@value’ or another workaround.  Otherwise, the comma may be taken
     as separating the arguments.  With ‘texi2any’, the comma can be
     escaped by a backslash.  With TeX another workaround need to be
     used, therefore we recommend using such a workaround.

     For example,

          @macro mactwo{argfirst, argsecond}
          \argfirst\+\argsecond\.
          @end macro
          @set fc Fran@,cois
          @mactwo{@value{fc},}

     produces:

          François+.

   • ‘@verbatim’ and macros do not mix; for instance, you can't start a
     verbatim block inside a macro and end it outside (see
     @verbatim).  Starting any environment inside a macro and ending
     it outside may or may not work, for that matter.

   • Macros that completely define macros are ok, but it's not possible
     to have incompletely nested macro definitions.  That is, ‘@macro’
     and ‘@end macro’ (likewise for ‘@rmacro’) must be correctly paired.
     For example, you cannot start a macro definition within a macro,
     and then end that nested definition outside the macro.

   In the ‘makeinfo’ implementation before Texinfo 5.0, ends of lines
from expansion of a ‘@macro’ definition did not end an @-command
line-delimited argument (‘@chapter’, ‘@center’, etc.).  This is no
longer the case.  For example:

     @macro twolines{}
     aaa
     bbb
     @end macro
     @center @twolines{}

   In the current ‘texi2any’, this is equivalent to:

     @center aaa
     bbb

with just ‘aaa’ as the argument to ‘@center’.  In the earlier
implementation, it would have been parsed as this:

     @center aaa bbb

17.4 ‘@alias NEW=EXISTING’
==========================

The ‘@alias’ command defines a new command to be just like an existing
one.  This is useful for defining additional markup names, thus
preserving additional semantic information in the input even though the
output result may be the same.

   Write the ‘@alias’ command on a line by itself, followed by the new
command name, an equals sign, and the existing command name.  Whitespace
around the equals sign is optional and ignored if present.  Thus:

     @alias NEW = EXISTING

   For example, if your document contains citations for both books and
some other media (movies, for example), you might like to define a macro
‘@moviecite{}’ that does the same thing as an ordinary ‘@cite{}’ but
conveys the extra semantic information as well.  You'd do this as
follows:

     @alias moviecite = cite

   Macros do not always have the same effect as aliases, due to vagaries
of argument parsing.  Also, aliases are much simpler to define than
macros.  So the command is not redundant.

   Unfortunately, it's not possible to alias Texinfo environments; for
example, ‘@alias lang=example’ is an error.

   Aliases must not be recursive, directly or indirectly.

   It is not advisable to redefine any TeX primitive, plain TeX, or
Texinfo command name as an alias.  Unfortunately this is a very large
set of names, and the possible resulting errors from TeX are
unpredictable.

   Alias identifiers should be the same as for macro names, that is
alphanumerics and (except as the first character) ‘-’.  However, with
TeX, letters only should be used.  So, we recommend using only letters.

17.5 Line Macros
================

You can also define a macro using the ‘@linemacro’ command.  The syntax
for line macro definitions is similar to that for ‘@macro’.

   However, the syntax for using a macro defined this way is different.
The macro call uses the rest of the line, with arguments separated by
spaces.  The line macro facility is mainly intended to allow you to
define commands that operate similarly to the builtin commands for
providing definitions (see Definition Commands).

   For example:

     @linemacro defbuiltin {name, args}
     @defline {Builtin} \name\ \args\
     @end linemacro

   The above macro may be used as

     @defblock
     @defbuiltin foo (bar)
     Explanation
     @end defblock

   This produces the following result:

 -- Builtin: foo (bar)
     Explanation

   Here the first argument is ‘foo’, and is substituted where ‘\name\’
appears in the macro body.  Likewise, ‘(bar)’ is substituted for
‘\args\’.

   You can include spaces in a macro argument by surrounding the
argument by braces.  Any pair of braces enclosing an argument is removed
before substitution.  Any empty arguments (including the last one) must
be given as ‘{}’.  Additionally, non-initial spaces may appear in the
final argument in the argument list without surrounding braces (as in
the example below).

   If an argument line for a line macro ends in a ‘@’ character, then
this character together with the following newline are included in a
macro argument, and the following line in the input file is also used to
get the arguments for the macro.  Note that any substitution of the
‘@<NEWLINE>’ sequence must be in a valid context, such as a definition
line (see Def Cmd Continuation Lines).

   Another example:

     @linemacro deffunc {type, name, args}
     @findex \name\
     @deftypeline {Func} {\type\} \name\ \args\
     @end linemacro

     @defblock
     @deffunc {long int} F (int @var{one}, int @var{two}, @
     int @var{three}, int @var{four}, int @var{five})
     Explanation
     @end defblock

Note how braces are needed around ‘\type\’ in the macro body in case the
‘type’ argument contains a space.  This example produces the output
below and enters an index entry for ‘F’.

 -- Func: long int F (int ONE, int TWO, int THREE, int FOUR, int FIVE)
     Explanation

   Line macros produce a whole number of lines of output in their
expansion.  There may be better compatibility between the Texinfo
processors (‘texi2any’ and TeX with ‘texinfo.tex’) for macros defined
with ‘@linemacro’ than for those defined with ‘@macro’.

17.6 ‘@definfoenclose’: Customized Highlighting
===============================================

An ‘@definfoenclose’ command may be used to define a highlighting
command for online output formats.  A command defined using
‘@definfoenclose’ marks text by enclosing it in strings that precede and
follow the text.

   In practice, there is little use for this command, and we do not
recommend you use it.  Support for ‘@definfoenclose’ may be removed in
future releases of Texinfo.

   Write a ‘@definfoenclose’ command at the beginning of a line followed
by three comma-separated arguments.  The first argument to
‘@definfoenclose’ is the @-command name (without the ‘@’); the second
argument is the start delimiter string; and the third argument is the
end delimiter string.  The latter two arguments enclose the highlighted
text in the output.

   A delimiter string may contain spaces.  Neither the start nor end
delimiter is required.  If you do not want a start delimiter but do want
an end delimiter, you must follow the command name with two commas in a
row; otherwise, the end delimiter string you intended will naturally be
(mis)interpreted as the start delimiter string.

   An enclosure command defined this way takes one argument in braces,
since it is intended for new markup commands (see Marking Text).

   For example, you can write:

     @definfoenclose phoo,//,\\

near the beginning of a Texinfo file to define ‘@phoo’ as an Info and
HTML command that inserts '//' before and '\\' after the argument to
‘@phoo’.  You can then write ‘@phoo{bar}’ wherever you want '//bar\\'
highlighted in Info and HTML.

   For TeX formatting, you could write

     @iftex
     @alias phoo = i
     @end iftex

to define ‘@phoo’ as a command that causes TeX to typeset the argument
to ‘@phoo’ in italics.

   Each definition applies to its own formatter: one for TeX, the other
for online formats.  The TeX definitions need to be in ‘@iftex’.
‘@definfoenclose’ command need not be within ‘@ifinfo’ unless you want
to use different definitions for different online output formats.
‘@definfoenclose’ defined commands have no effect in DocBook and LaTeX
output, their argument is output as-is.  An ‘@alias’ could also be used
for these formats.

   ‘@definfoenclose’ definitions must not be recursive, directly or
indirectly.

17.7 External Macro Processors: Line Directives
===============================================

Texinfo macros (and its other text substitution facilities) work fine in
straightforward cases.  If your document needs unusually complex
processing, however, their fragility and limitations can be a problem.
In this case, you may want to use a different macro processor
altogether, such as M4 (see m4) or CPP (see cpp).

   With one exception, Texinfo does not need to know whether its input
is "original" source or preprocessed from some other source file.
Therefore, you can arrange your build system to invoke whatever programs
you like to handle macro expansion or other preprocessing needs.
Texinfo does not offer built-in support for any particular preprocessor,
since no one program seemed likely to suffice for the requirements of
all documents.

   The one exception is line numbers in error messages.  In that case,
the line number should refer to the original source file, whatever it
may be.  There's a well-known mechanism for this: the so-called ‘#line’
directive.  Texinfo supports this.

17.7.1 ‘#line’ Directive
------------------------

An input line such as this:

     #line 100 "foo.ptexi"

indicates that the next line was line 100 of the file ‘foo.ptexi’, and
so that's what an error message should refer to.  Both M4 (see
Preprocessor features (m4)) and CPP (see Line Control (cpp), and
Preprocessor Output (cpp)) can generate such lines.

   The ‘texi2any’ program recognizes these lines by default, except
within ‘@verbatim’ blocks (see @verbatim).  Their recognition can be
turned off completely with ‘CPP_LINE_DIRECTIVES’ (see Global Customization Variables),
though there is normally no reason to do so.

   For those few programs (M4, CPP, Texinfo) which need to document
‘#line’ directives and therefore have examples which would otherwise
match the pattern, the command ‘@hashchar{}’ can be used (see
Inserting a Hashsign).  The example line above looks like this in the
source for this manual:

     @hashchar{}line 100 "foo.ptexi"

   The ‘@hashchar’ command was added to Texinfo in 2013.  If you don't
want to rely on it, you can also use ‘@set’ and ‘@value’ to insert the
literal ‘#’:

     @set hash #
     @value{hash}line 1 "example.c"

   Or, if suitable, a ‘@verbatim’ environment can be used instead of
‘@example’.  As mentioned above, ‘#line’-recognition is disabled inside
verbatim blocks.

17.7.2 ‘#line’ and TeX
----------------------

As mentioned, ‘texi2any’ recognizes the ‘#line’ directives described in
the previous section.  However, ‘texinfo.tex’ does not and cannot.
Therefore, such a line will be incorrectly typeset verbatim if TeX sees
it.  The solution is to use ‘texi2any’'s macro expansion options before
running TeX.  There are three approaches:

   • If you run ‘texi2dvi’ or its variants (see Format with texi2dvi),
     you can pass ‘-E’ and ‘texi2dvi’ will run ‘texi2any’
     first to expand macros and eliminate ‘#line’.

   • If you run ‘texi2any’, you can specify ‘--no-ifinfo --iftex -E
     somefile.out’, and then give ‘somefile.out’ to ‘texi2dvi’ in a
     separate command.

   • Or you can run ‘texi2any --dvi --Xopt -E’.  (Or ‘--pdf’ instead of
     ‘--dvi’.)  ‘texi2any’ will then call ‘texi2dvi -E’.

   One last caveat regarding use with TeX: since the ‘#line’ directives
are not recognized, the line numbers emitted by the ‘@errormsg{}’
command (see Conditional Commands), or by TeX itself, are the
(incorrect) line numbers from the derived file which TeX is reading,
rather than the preprocessor-specified line numbers.

17.7.3 ‘#line’ Syntax Details
-----------------------------

Syntax details for the ‘#line’ directive: the ‘#’ character can be
preceded or followed by whitespace, the word ‘line’ is optional, and the
file name can be followed by a whitespace-separated list of integers
(these are so-called "flags" output by CPP in some cases).  For those
who like to know the gory details, the actual (Perl) regular expression
which is matched is this:

     /^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/

   As far as we've been able to tell, the trailing integer flags only
occur in conjunction with a file name, so that is reflected in the
regular expression.

   As an example, the following is a syntactically valid ‘#line’
directive, meaning line 1 of ‘/usr/include/stdio.h’:

     # 1 "/usr/include/stdio.h" 2 3 4

   Unfortunately, the quoted file name (‘"..."’) has to be optional,
because M4 (especially) can often generate ‘#line’ directives within a
single file.  Since the ‘line’ is also optional, the result is that
lines might match which you wouldn't expect, e.g.,

     # 1

   The possible solutions are described above (see #line Directive).

18 Include Files
****************

When a Texinfo processor sees an ‘@include’ command in a Texinfo file,
it processes the contents of the file named by the ‘@include’ and
incorporates them into the output files being created.  Include files
thus let you keep a single large document as a collection of
conveniently small parts.

18.1 How to Use Include Files
=============================

To include another file within a Texinfo file, write the ‘@include’
command at the beginning of a line and follow it on the same line by the
name of a file to be included.  For example:

     @include buffers.texi

   ‘@value{VAR}’ references are expanded on the ‘@include’ line.  Other
than that, the only @-commands allowed are ‘@@’, ‘@{’, ‘@}’ and
associated @-commands such as ‘@atchar{}’.

   An included file should simply be a segment of text that you expect
to be included as is into the overall or “outer” Texinfo file; it should
not contain the standard beginning and end parts of a Texinfo file.  In
particular, you should not start an included file with a line saying
‘\input texinfo’; if you do, that text is inserted into the output file
literally.  Likewise, you should not end an included file with a ‘@bye’
command; nothing after ‘@bye’ is formatted.

   In the long-ago past, you were required to write an ‘@setfilename’
line at the beginning of an included file, but no longer.  Now, it does
not matter whether you write such a line.  If an ‘@setfilename’ line
exists in an included file, it is ignored.

   GNU Emacs Texinfo mode provides ‘texinfo-multiple-files-update’ to
update node pointers and master menu with multiple include files.  See
Update Multiple Files.

18.2 Sample File with ‘@include’
================================

Here is an example of an outer Texinfo file with ‘@include’ files within
it:

     \input texinfo @c -*-texinfo-*-

     @settitle Include Example

     @node Top
     @top Include Example

     @include foo.texi
     @include bar.texi
     @include concept-index.texi
     @bye

   An included file, such as ‘foo.texi’, might look like this:

     @node First
     @chapter First Chapter

     Contents of first chapter ...

   The full contents of ‘concept-index.texi’ might be as simple as this:

     @node Concept Index
     @unnumbered Concept Index

     @printindex cp

   The outer Texinfo source file for ‘The GNU Emacs Lisp Reference
Manual’ is named ‘elisp.texi’.  This outer file has already contained a
master menu with 417 entries and a list of 41 ‘@include’ files.

18.3 ‘@verbatiminclude’ FILE: Include a File Verbatim
=====================================================

You can include the exact contents of a file in the document with the
‘@verbatiminclude’ command:

     @verbatiminclude FILENAME

   The contents of FILENAME is printed in a verbatim environment (see
@verbatim).  Generally, the file is printed exactly as it is, with all
special characters and white space retained.  No indentation is added;
if you want indentation, enclose the ‘@verbatiminclude’ within
‘@example’ (see @example).

   ‘@value{VAR}’ references are expanded on the ‘@verbatiminclude’ line.
This makes it possible to include files in other directories within a
distribution, for instance:

     @verbatiminclude @value{top_srcdir}/NEWS

(You still have to get ‘top_srcdir’ defined in the first place.)

   Other than that, the only @-commands allowed are ‘@@’, ‘@{’, ‘@}’ and
associated @-commands such as ‘@atchar{}’.

   For a method on printing the file contents in a smaller font size,
see the end of the section on ‘@verbatim’.

19 Formatting and Printing with TeX
***********************************

Running the ‘texi2dvi’ or ‘texi2pdf’ command is the simplest way to
create printable output.  These commands are installed as part of the
Texinfo package.

   In more detail, typesetting and printing a Texinfo file is a
multi-step process in which you use the TeX program to create a file for
printing (called a DVI or PDF file), and then print the file.
Optionally, you may also create indices using the ‘texindex’ command
after first running TeX; and then you must run TeX again.  ‘texi2dvi’
takes care of all of this, running TeX and ‘texindex’ as needed (see
Format with texi2dvi).

   When you use the shell commands, you can either work directly in the
operating system shell or work within a shell inside GNU Emacs (or some
other computing environment).  You can give formatting and printing
commands from a shell within GNU Emacs, just like any other shell
command.  To create a shell within Emacs, type ‘M-x shell’ (see
Shell (emacs)).  If you are using GNU Emacs, you can also use commands
provided by Texinfo mode instead of shell commands.  See Printing with Emacs.

   For specifing details of the printed output such as paper size, see
Global Document Commands.

19.1 Use TeX
============

The typesetting program called TeX is used to format a Texinfo document
for printable output.  TeX is a very powerful typesetting program and,
when used correctly, does an exceptionally good job.  It is not included
in the Texinfo package, being a vast suite of software in itself.

   TeX is a document formatter that is used by the FSF for its
documentation.  It is the easiest way to get printed output (e.g., PDF
and PostScript) for Texinfo manuals.  TeX is freely redistributable, and
you can get it over the Internet or on physical media.  See
<http://tug.org/texlive>.

19.2 Format with ‘texi2dvi’ or ‘texi2pdf’
=========================================

The ‘texi2dvi’ program takes care of all the steps for producing a TeX
DVI file from a Texinfo document.  Similarly, ‘texi2pdf’ produces a PDF
file(1).

   To run ‘texi2dvi’ or ‘texi2pdf’ on an input file ‘foo.texi’, do this
(where ‘prompt$ ’ is your shell prompt):

     prompt$ texi2dvi foo.texi
     prompt$ texi2pdf foo.texi

   As shown in this example, the file names given to ‘texi2dvi’ and
‘texi2pdf’ must include any extension, such as ‘.texi’.

   For a list of all the options, run ‘texi2dvi --help’.  Some of the
options are discussed below.

   With the ‘--pdf’ option, ‘texi2dvi’ produces PDF output instead of
DVI, by running ‘pdftex’ instead of ‘tex’.  Alternatively, the command
‘texi2pdf’ is an abbreviation for running ‘texi2dvi --pdf’.  The command
‘pdftexi2dvi’ is also provided as a convenience for AUC-TeX (see
auctex), as it prefers to merely prepend ‘pdf’ to DVI producing
tools to have PDF producing tools.

   With the ‘--dvipdf’ option, ‘texi2dvi’ produces PDF output by running
TeX and then a DVI-to-PDF program: if the ‘DVIPDF’ environment variable
is set, that value is used, else the first program extant among
‘dvipdfmx’, ‘dvipdfm’, ‘dvipdf’, ‘dvi2pdf’, ‘dvitopdf’.  This method
generally supports CJK typesetting better than ‘pdftex’.

   With the ‘--ps’ option, ‘texi2dvi’ produces PostScript instead of
DVI, by running ‘tex’ and then ‘dvips’ (see dvips).  (Or the
value of the ‘DVIPS’ environment variable, if set.)

   ‘texi2dvi’ can also be used to process LaTeX files.  Normally
‘texi2dvi’ is able to guess the input file language by its contents and
file name extension; however, if it guesses wrong you can explicitly
specify the input language using ‘--language=LANG’ command line option,
where LANG is either ‘latex’ or ‘texinfo’.

   One useful option to ‘texi2dvi’ is ‘--command=CMD’.  This inserts CMD
on a line by itself at the start of the file in a temporary copy of the
input file, before running TeX.  With this, you can specify different
printing formats, such as ‘@smallbook’ (see @smallbook),
‘@afourpaper’ (see A4 Paper), or ‘@pagesizes’ (see @pagesizes),
without actually changing the document source.  (You can also do this on
a site-wide basis with ‘texinfo.cnf’; see Preparing for TeX).

   The option ‘-E’ (equivalently, ‘-e’ and ‘--expand’) does Texinfo
macro expansion using ‘texi2any’ instead of the TeX implementation
(see Macro Details).  Each implementation has its own limitations
and advantages.

   ‘texi2dvi’ takes the ‘--build=MODE’ option to specify where the TeX
compilation takes place, and, as a consequence, how auxiliary files are
treated.  The build mode can also be set using the environment variable
‘TEXI2DVI_BUILD_MODE’.  The valid values for MODE are:

‘local’
     Compile in the current directory, leaving all the auxiliary files
     around.  This is the traditional TeX use.

‘tidy’
     Compile in a local ‘*.t2d’ directory, where the auxiliary files are
     left.  Output files are copied back to the original file.

     Using the ‘tidy’ mode brings several advantages:
        - the current directory is not cluttered with plethora of
          temporary files.
        - clutter can be even further reduced using ‘--build-dir=dir’:
          all the ‘*.t2d’ directories are stored there.
        - clutter can be reduced to zero using, e.g.,
          ‘--build-dir=/tmp/\$USER.t2d’ or ‘--build-dir=\$HOME/.t2d’.
        - the output file is updated after every successful TeX run, for
          sake of concurrent visualization of the output.  In a ‘local’
          build the viewer stops during the whole TeX run.
        - if the compilation fails, the previous state of the output
          file is preserved.
        - PDF and DVI compilation are kept in separate subdirectories
          preventing any possibility of auxiliary file incompatibility.

     On the other hand, because ‘tidy’ compilation takes place in
     another directory, occasionally TeX won't be able to find some
     files (e.g., when using ‘\graphicspath’): in that case, use ‘-I’ to
     specify the additional directories to consider.

‘clean’
     Same as ‘tidy’, but remove the auxiliary directory afterwards.
     Every compilation therefore requires the full cycle.

   ‘texi2dvi’ will use ‘etex’ if it is available, because it runs faster
in some cases, and provides additional tracing information when
debugging ‘texinfo.tex’.  Nevertheless, this extended version of TeX is
not required, and the DVI output is identical.

   ‘texi2dvi’ attempts to detect auxiliary files output by TeX, either
by using the ‘-recorder’ option, or by scanning for ‘\openout’ in the
log file that a run of TeX produces.  You may control how ‘texi2dvi’
does this with the ‘TEXI2DVI_USE_RECORDER’ environment variable.  Valid
values are:

‘yes’
     use the ‘-recorder’ option, no checks.

‘no’
     scan for ‘\openout’ in the log file, no checks.

‘yesmaybe’
     check whether ‘-recorder’ option is supported, and if yes use it,
     otherwise check for tracing ‘\openout’ in the log file is
     supported, and if yes use it, else it is an error.

‘nomaybe’
     same as ‘yesmaybe’, except that the ‘\openout’ trace in log file is
     checked first.

   The default is ‘nomaybe’.  This environment variable is provided for
troubleshooting purposes, and may change or disappear in the future.

   ---------- Footnotes ----------

   (1) “PDF” stands for 'Portable Document Format'.  It was invented by
Adobe Systems for document interchange, based on their PostScript
language.

19.3 Format with ‘tex’/‘texindex’
=================================

You can do the basic formatting of a Texinfo file with the shell command
‘tex’ followed by the name of the Texinfo file.  For example:

     tex foo.texi

TeX will produce a “DVI file” as well as several auxiliary files
containing information for indices, cross-references, etc.  The DVI file
(for “DeVice Independent” file) can be printed on virtually any device,
perhaps after a further conversion (see the previous section).

   The ‘tex’ formatting command itself does not sort the indices; it
writes an output file of unsorted index data.  To generate a printed
index after running the ‘tex’ command, you first need a sorted index to
work from.  The ‘texindex’ command sorts indices.  (‘texi2dvi’,
described in the previous section, runs ‘tex’ and ‘texindex’ as
necessary.)

   ‘tex’ outputs unsorted index files under names following a standard
convention: the name of your main input file with any ‘.texi’ or similar
extension replaced by the two letter index name.  For example, the raw
index output files for the input file ‘foo.texi’ would be, by default,
‘foo.cp’, ‘foo.vr’, ‘foo.fn’, ‘foo.tp’, ‘foo.pg’ and ‘foo.ky’.  Those
are exactly the arguments to give to ‘texindex’.

   Instead of specifying all the unsorted index file names explicitly,
it's typical to use ‘??’ as shell wildcards and give the command in this
form:

     texindex foo.??

This command will run ‘texindex’ on all the unsorted index files,
including any two letter indices that you have defined yourself using
‘@defindex’ or ‘@defcodeindex’.  You can safely run ‘texindex foo.??’
even if there are files with two letter extensions that are not index
files, such as ‘foo.el’.  The ‘texindex’ command reports but otherwise
ignores such files.

   For each file specified, ‘texindex’ generates a sorted index file
whose name is made by appending ‘s’ to the input file name; for example,
‘foo.cps’ is made from ‘foo.cp’.  The ‘@printindex’ command looks for a
file with that name (see Printing Indices & Menus).  TeX does not
read the raw index output file, and ‘texindex’ does not alter it.

   After you have sorted the indices, you need to rerun ‘tex’ on the
Texinfo file.  This regenerates the output file, this time with
up-to-date index entries.

   Finally, you may need to run ‘tex’ one more time, to get the page
numbers in the cross-references correct.

   To summarize, this is a five-step process.  (Alternatively, it's a
one-step process: run ‘texi2dvi’; see the previous section.)

  1. Run ‘tex’ on your Texinfo file.  This generates a DVI file (with
     undefined cross-references and no indices), and the raw index files
     (with two letter extensions).

  2. Run ‘texindex’ on the raw index files.  This creates the
     corresponding sorted index files (with three letter extensions).

  3. Run ‘tex’ again on your Texinfo file.  This regenerates the DVI
     file, this time with indices and defined cross-references, but with
     page numbers for the cross-references from the previous run,
     generally incorrect.

  4. Sort the indices again, with ‘texindex’.

  5. Run ‘tex’ one last time.  This time the correct page numbers are
     written for the cross-references.

   To generate PDF, you can run the ‘pdftex’ program instead of plain
‘tex’.  That is, run ‘pdftex foo.texi’ instead of ‘tex foo.texi’ in the
examples above.

19.3.1 Formatting Partial Documents
-----------------------------------

Sometimes you may wish to print a document while you know it is
incomplete, or to print just one chapter of a document.  In such a case,
the usual auxiliary files that TeX creates and warnings TeX gives about
undefined cross-references are just nuisances.  You can avoid them with
the ‘@novalidate’ command, which you must give _before_ any sectioning
or cross-reference commands.

   Thus, the beginning of your file would look approximately like this:

     \input texinfo
     @novalidate
     ...

‘@novalidate’ also turns off validation in ‘texi2any’, just like its
‘--no-validate’ option (see Invoking texi2any).

   Furthermore, you need not run ‘texindex’ each time after you run
‘tex’.  The ‘tex’ formatting command simply uses whatever sorted index
files happen to exist from a previous use of ‘texindex’.  If those are
out of date, that is usually ok while you are creating or debugging a
document.

19.3.2 Details of ‘texindex’
----------------------------

In Texinfo version 6, released in 2015, the ‘texindex’ program was
completely reimplemented.  The principal functional difference is that
index entries beginning with a left brace or right brace (‘{’ resp. ‘}’)
can work properly.  For example, these simple index entries are
processed correctly, including the "index initial" shown in the index:

     @cindex @{
     @cindex @}
     ...
     @printindex cp

   Although not a matter of functionality, readers may be interested to
know that the new ‘texindex’ is a literate program
(<https://en.wikipedia.org/wiki/Literate_programming>) using Texinfo for
documentation and (portable) ‘awk’ for code.  A single source file,
‘texindex/ti.twjr’ in this case, produces the runnable program, a
printable document, and an online document.

   The system is called TexiWeb Jr. and was created by Arnold Robbins,
who also wrote the new ‘texindex’.  Not coincidentally, he is also the
long-time maintainer of ‘gawk’ (GNU Awk, see gawk).  The file
‘texindex/Makefile.am’ shows example usage of the system.

19.4 Preparing for TeX
======================

TeX needs to find the ‘texinfo.tex’ file that the ‘\input texinfo’
command on the first line reads.  The ‘texinfo.tex’ file tells TeX how
to handle @-commands; it is included in all standard GNU distributions.
The latest version released for general use is available from the usual
GNU servers and mirrors:

     <https://ftp.gnu.org/gnu/texinfo/texinfo.tex>
     <https://ftpmirror.gnu.org/texinfo/texinfo.tex>

   The latest development version is available from the Texinfo source
repository:

     <https://git.savannah.gnu.org/cgit/texinfo.git/plain/doc/texinfo.tex>

   ‘texinfo.tex’ is essentially a standalone file, so, if you need or
want to try a newer version than came with your system, it nearly always
suffices to download it and put it anywhere that TeX will find it.  You
can replace any existing ‘texinfo.tex’ with a newer version (of course
saving the original in case of disaster).

   Also, you should install ‘epsf.tex’, if it is not already installed
from another distribution.  More details are at the end of the
description of the ‘@image’ command (see Images).

   To use quotation marks other than those used in English, you'll need
to have the European Computer Modern fonts (e.g., ‘ecrm1000’) and (for
PDF output) CM-Super fonts (see Inserting Quotation Marks).

   To use the ‘@euro’ command, you'll need the ‘feym*’ fonts (e.g.,
‘feymr10’).  See @euro.

   All of the above files should be installed by default in a reasonable
TeX installation.

   Optionally, you may create a file ‘texinfo.cnf’ for site
configuration.  When processing a Texinfo file, TeX looks for this file
in its search path, which includes the current directory and standard
installation directories.  You can use this file for local conventions.
For example, if ‘texinfo.cnf’ contains the line ‘@afourpaper’ (see A4 Paper),
then all Texinfo documents will be processed with that page
size in effect.  If you have nothing to put in ‘texinfo.cnf’, you do not
need to create it.

   You can set the ‘TEXINPUTS’ environment variable to allow TeX to find
‘texinfo.cnf’.  (This also works for ‘texinfo.tex’ and any other file
TeX might read).  For example, if you are using a Bourne
shell-compatible shell (‘sh’, ‘bash’, ‘ksh’, ...), your ‘.profile’ file
could contain the lines:

     TEXINPUTS=.:/home/me/mylib:
     export TEXINPUTS

These settings would cause TeX first to look for an ‘\input’ file in the
current directory, indicated by the ‘.’, then in a hypothetical user
‘me’'s ‘mylib’ directory, and finally in the system directories.  (A
leading, trailing, or doubled ‘:’ indicates searching the system
directories at that point.)

19.5 Overfull "hboxes"
======================

TeX is sometimes unable to typeset a line within the normal margins.
This most often occurs when TeX comes upon what it interprets as a long
word that it cannot hyphenate, such as an electronic mail network
address or a very long identifier.  When this happens, TeX prints an
error message like this:

     Overfull @hbox (20.76302pt too wide)

(In TeX, lines are in "horizontal boxes", hence the term, "hbox".
‘@hbox’ is a TeX primitive not used in the Texinfo language.)

   TeX also provides the line number in the Texinfo source file and the
text of the offending line, which is marked at all the places that TeX
considered hyphenation.  See Debugging with TeX, for more
information about typesetting errors.

   If the Texinfo file has an overfull hbox, you can rewrite the
sentence so the overfull hbox does not occur, or you can decide to leave
it.  A small excursion into the right margin often does not matter and
may not even be noticeable.

   If you have many overfull boxes and/or an antipathy to rewriting, you
can coerce TeX into greatly increasing the allowable interword spacing,
thus (if you're lucky) avoiding many of the bad line breaks, like this:

     @tex
     \global\emergencystretch = .9\hsize
     @end tex

(You should adjust the fraction as needed.)  This huge value for
‘\emergencystretch’ cannot be the default, since then the typeset output
would generally be of noticeably lower quality; its default value is
‘.15\hsize’.  ‘\hsize’ is the TeX dimension containing the current line
width.

   For any overfull boxes you do have, TeX will print a large, ugly,
black rectangle beside the line that contains the overfull hbox unless
told otherwise.  This is so you will notice the location of the problem
if you are correcting a draft.

   To prevent such a monstrosity from marring your final printout, write
the following in the beginning of the Texinfo file on a line of its own,
before the ‘@maketitle’ or ‘@titlepage’ command:

     @finalout

19.6 Printing Japanese and Chinese
==================================

Texinfo comes with support files for processing input in the Japanese
and Chinese languages.

   For Japanese, you use the ‘texinfo-ja.tex’ file.  Your main input
file should begin with a ‘\input texinfo-ja’ line, rather than the
standard ‘\input texinfo’.  Use the UTF-8 character encoding as usual.
You must process the files with either XeTeX or LuaTeX.

   For Chinese, you use the ‘texinfo-zh.tex’ file.  Your main input file
should begin with a ‘\input texinfo-zh’ line, rather than the standard
‘\input texinfo’.  Use the UTF-8 character encoding as usual.  You must
process the files with XeTeX.

   For example, you would run ‘PDFTEX=xetex texi2pdf MY-INPUT-FILE.TEXI’
to use XeTeX to produce PDF output.  You may have to install XeTeX (or
LuaTeX), the ‘zhspacing’ package, and/or font packages.

   Neither Japanese nor Chinese is supported with the standard TeX (or
pdfTeX) program, as it cannot support the fonts and thousands of glyphs
needed for these languages.

   The Texinfo distribution comes with a couple of sample files that you
can use to test support for these languages: ‘short-sample-ja.texi’ for
Japanese, and ‘short-sample-zh.texi’ for Chinese.

   For more information on these extensions to TeX, see the XeTeX home
page (https://tug.org/xetex/) and the LuaTeX website
(https://www.luatex.org/).

20 ‘texi2any’: The Translator for Texinfo
*****************************************

‘texi2any’ is the generic translator for Texinfo that can produce
different output formats and is highly customizable.  It supports these
formats:

     Info (by default, or with ‘--info’),
     HTML (with ‘--html’),
     EPUB 3 (with ‘--epub3’),
     plain text (with ‘--plaintext’),
     LaTeX (with ‘--latex’),
     DocBook (with ‘--docbook’),
     Texinfo XML (with ‘--xml’).

   ‘makeinfo’ is an alias for ‘texi2any’.  By default, both ‘texi2any’
and ‘makeinfo’ generate Info output; indeed, there are no differences in
behavior based on the name.

   Beside these default formats, command line options to ‘texi2any’ can
change many aspects of the output.  Beyond that, initialization files
provide even more control over the final output--nearly anything not
specified in the Texinfo input file.  Initialization files are written
in Perl, and anything which can be specified on the command line can
also be specified within a initialization file.

   Two functionally equivalent implementations of ‘texi2any’ can be
built in GNU Texinfo, one in Perl and another in compiled native code
(in C). The native code implementation is still experimental.  The Perl
program can use Perl extension modules in compiled native code, while
the native code program embeds a Perl interpreter for the parts that
require Perl.

   In the default case, the Perl implementation is installed.  You can
select the experimental C implementation instead at build time by
passing the ‘--enable-using-c-texi2any’ option to ‘configure’.

20.1 Invoking ‘texi2any’ from a Shell
=====================================

To process a Texinfo file, invoke ‘texi2any’ followed by the name of the
Texinfo file.  Also select the format you want to output with the
appropriate command line option (default is Info).  Thus, to create the
Info file for Bison, type the following to the shell:

     texi2any --info bison.texi

   You can specify more than one input file name; each is processed in
turn.  If an input file name is ‘-’, standard input is read.

   The ‘texi2any’ program accepts many options.  Perhaps the most basic
are those that change the output format.  By default, ‘texi2any’ outputs
Info.

   Each command line option is either a long name preceded by ‘--’ or a
single letter preceded by ‘-’.  You can use abbreviations for the long
option names as long as they are unique.

   For example, you could use the following shell command to create an
Info file for ‘bison.texi’ in which lines are filled to only 68 columns:

     texi2any --fill-column=68 bison.texi

   You can write two or more options in sequence, like this:

     texi2any --no-split --fill-column=70 ...

(This would keep the Info file together as one possibly very long file
and would also set the fill column to 70.)

   The options are (approximately in alphabetical order):

‘--commands-in-node-names’
     This option now does nothing, but remains for compatibility.  (It
     used to ensure that @-commands in node names were expanded
     throughout the document, especially ‘@value’.  This is now done by
     default.)

‘--conf-dir=DIR’
     Prepend DIR to the directory search list for finding customization
     files that may be loaded with ‘--init-file’ (see below).  The DIR
     value can be a single directory, or a list of several directories
     separated by the usual path separator character (‘:’ on Unix-like
     systems, ‘;’ on Windows).

‘--css-include=FILE’
     When producing HTML, literally include the contents of FILE, which
     should contain Cascading Style Sheets specifications, in the
     ‘<style>’ block of the HTML output.  If FILE is ‘-’, read standard
     input.  See HTML CSS.

‘--css-ref=URL’
     When producing HTML, add a ‘<link>’ tag to the output which
     references a cascading style sheet at URL.  This allows using
     standalone style sheets.

‘-D VAR’
‘-D 'VAR VALUE'’
     Cause the Texinfo variable VAR to be defined.  This is equivalent
     to ‘@set VAR’ in the Texinfo file (see @set @clear @value).

     The argument to the option is always one word to the shell; if it
     contains internal whitespace, the first word is taken as the
     variable name and the remainder as the value.  For example, ‘-D
     'myvar someval'’ is equivalent to ‘@set myvar someval’.

‘--docbook’
     Generate DocBook output (rather than Info).

‘--document-language=LANG’
     Use LANG to translate Texinfo keywords which end up in the output
     document.  The default is the locale specified by the
     ‘@documentlanguage’ command if there is one, otherwise English
     (see @documentlanguage).

‘--dvi’
     Generate a TeX DVI file using ‘texi2dvi’, rather than Info (see
     texi2any Printed Output).

‘--dvipdf’
     Generate a PDF file using ‘texi2dvi --dvipdf’, rather than Info
     (see texi2any Printed Output).

‘--enable-encoding’
‘--disable-encoding’
     By default, or with ‘--enable-encoding’, output accented and
     special characters in Info and plain text output based on the
     document encoding.  With ‘--disable-encoding’, 7-bit ASCII
     transliterations are output.  Also obeyed in other output formats
     for index keys sorting and for some plain text output.

‘--epub3’
     Generate EPUB 3 output.

‘--error-limit=LIMIT’
‘-e LIMIT’
     Report LIMIT errors before aborting (on the assumption that
     continuing would be useless); default 100.

‘--fill-column=WIDTH’
‘-f WIDTH’
     Specify the maximum number of columns in a line; this is the
     right-hand edge of a line.  Paragraphs that are filled will be
     filled to this width.  (Filling is the process of breaking up and
     connecting lines so that lines are the same length as or shorter
     than the number specified as the fill column.  Lines are broken
     between words.)  The default value is 72.

‘--footnote-style=STYLE’
‘-s STYLE’
     Set the footnote style to STYLE: either ‘end’ for the end node
     style (the default) or ‘separate’ for the separate node style.  The
     value set by this option overrides the value set in a Texinfo file
     by a ‘@footnotestyle’ command (see Footnote Styles).

     In Info, when the footnote style is ‘separate’, ‘texi2any’ makes a
     new node containing the footnotes found in the current node.  When
     the footnote style is ‘end’, ‘texi2any’ places the footnote
     references at the end of the current node.

     In HTML, when the footnote style is ‘end’, or if the output is not
     split, footnotes are put at the end of the output.  If set to
     ‘separate’, and the output is split, they are placed in a separate
     file.

‘--force’
‘-F’
     Ordinarily, if the input file has errors, the output files are not
     created.  With this option, they are preserved.

‘--help’
‘-h’
     Print a message with available options and basic usage, then exit
     successfully.

‘--html’
     Generate HTML output (rather than Info).  By default, the HTML
     output is split into one output file per node, and the split output
     is written into a subdirectory based on the name of the input file.
     See Generating HTML.

‘-I DIR’
     Append DIR to the directory search list for finding files that are
     included using the ‘@include’ command.  By default, ‘texi2any’
     searches the current directory and the input file path leading
     directory if there is one (and it is not the current directory).
     The DIR value can be a single directory or a list of several
     directories separated by the usual path separator character (‘:’ on
     Unix-like systems, ‘;’ on Windows).

‘--ifdocbook’
‘--ifhtml’
‘--ifinfo’
‘--iflatex’
‘--ifplaintext’
‘--iftex’
‘--ifxml’
     For the given format, process ‘@ifFORMAT’ and ‘@FORMAT’ commands,
     and do not process ‘@ifnotFORMAT’, regardless of the format being
     output.  For instance, if ‘--iftex’ is given, then ‘@iftex’ and
     ‘@tex’ blocks will be read, and ‘@ifnottex’ blocks will be ignored.

‘--no-ifdocbook’
‘--no-ifhtml’
‘--no-ifinfo’
‘--no-iflatex’
‘--no-ifplaintext’
‘--no-iftex’
‘--no-ifxml’
     For the given format, do not process ‘@ifFORMAT’ and ‘@FORMAT’
     commands, and do process ‘@ifnotFORMAT’, regardless of the format
     being output.  For instance, if ‘--no-ifhtml’ is given, then
     ‘@ifhtml’ and ‘@html’ blocks will not be read, and ‘@ifnothtml’
     blocks will be.

‘--info’
     Generate Info output.  By default, if the output file contains more
     than about 300,000 bytes, it is split into shorter subfiles of
     about that size.  The name of the output file and any subfiles is
     determined by the input file name, or by ‘@setfilename’, if present
     (see Setting the Output File Name).  See Tag and Split Files.

‘--init-file=FILE’
     Load FILE as code to modify the behavior and output of the
     generated manual.  It is customary to use the ‘.pm’ or the ‘.init’
     extensions for these customization files, but that is not enforced;
     the FILE name can be anything.  The ‘--conf-dir’ option (see above)
     can be used to add to the list of directories in which these
     customization files are searched for.

‘--internal-links=FILE’
     In HTML mode, output a tab-separated file containing three columns:
     the internal link to an item, the type of the item and the name of
     the item or the term corresponding to the item which was indexed or
     entered.

     The items output are:
     output units
          Output units are the main unit of output documents.  Output
          units contain the content associated with a node or a
          sectioning command.  The item name is the associated node or a
          sectioning command name.
     sectioning commands
          The command name without ‘@’, adjusted for raise/lowersections
          is prepended to the item name.
     nodes, anchors and floats
          The type of the element is the command name without ‘@’.
     index entries
          The type of the element is the name of the index.

     The items are in the natural sorting order for the given element.
     This dump can be useful for post-processors.

‘--latex’
     Generate LaTeX output.

‘--macro-expand=FILE’
‘-E FILE’
     Output the Texinfo source, with all Texinfo macros expanded, to
     FILE.  Normally, the result of macro expansion is used internally
     by ‘texi2any’ and then discarded.

‘--no-headers’
     Do not include menus or node separator lines in the output.

     When generating Info, this is the same as using ‘--plaintext’,
     resulting in a simple plain text file.  Furthermore, output is to
     standard output unless overridden with ‘-o’.  (This behavior is for
     backward compatibility.)

     When generating HTML, and output is split, also output navigation
     links only at the beginning of each file.  If output is not split,
     do not include navigation links at the top of each node at all.
     See Generating HTML.

‘--node-files’
‘--no-node-files’
     With ‘--node-files’, when generating HTML, create redirection files
     for anchors and any nodes not already output with the file name
     corresponding to the node name (see HTML Xref Node Name Expansion).
     This makes it possible for section- and
     chapter-level cross-manual references to succeed (see HTML Xref Configuration).

     If the output is split, this is enabled by default.  If the output
     is not split, ‘--node-files’ enables the creation of the
     redirection files, in addition to the monolithic main output file.
     ‘--no-node-files’ suppresses the creation of redirection files in
     any case.  This option has no effect with any output format other
     than HTML.  See Generating HTML.

‘--no-validate’
‘--no-pointer-validate’
     Suppress the pointer-validation phase of ‘texi2any’--a dangerous
     thing to do.  This can also be done with the ‘@novalidate’ command
     (see Formatting Partial Documents).

     If you do not suppress pointer validation, ‘texi2any’ will check
     the validity of cross-references and menu entries in the Texinfo
     file, as well as node pointers if they are given explicitly.

‘--no-warn’
     Suppress warning messages (but not error messages).

‘--number-footnotes’
‘--no-number-footnotes’
     With ‘--no-number-footnotes’, suppress automatic footnote
     numbering.  By default, footnotes are numbered sequentially within
     a node, i.e., the current footnote number is reset to 1 at the
     start of each node.

‘--number-sections’
‘--no-number-sections’
     With ‘--number-sections’ (the default), output chapter, section,
     and appendix numbers as in printed manuals.  This works only with
     hierarchically structured manuals.  You should specify
     ‘--no-number-sections’ if your manual is not normally structured.

‘--output=FILE’
‘-o FILE’
     Specify that the output should be directed to FILE.  This overrides
     any file name specified in a ‘@setfilename’ command found in the
     Texinfo source.  If neither ‘@setfilename’ nor this option are
     specified, the input file name is used to determine the output
     name.  See Setting the Output File Name.

     If FILE is ‘-’, output goes to standard output and ‘--no-split’ is
     implied.

     If FILE is a directory or ends with a ‘/’ the usual rules are used
     to determine the output file name (namely, use ‘@setfilename’ or
     the input file name) but the files are written to the FILE
     directory.  For example, ‘texi2any -o bar/ foo.texi’, with or
     without ‘--no-split’, will write ‘bar/foo.info’, and possibly other
     files, under ‘bar/’.

     When generating HTML and output is split, FILE is used as the name
     for the directory into which all files are written.  For example,
     ‘texi2any -o bar --html foo.texi’ will write ‘bar/index.html’,
     among other files.

     When generating EPUB a container directory for the files and
     directories needed for the EPUB format is created, as well as the
     EPUB output file.  If FILE corresponds to a directory, the
     container directory is placed within FILE.  The EPUB output file is
     never put in this directory.  If FILE corresponds to a file, it is
     used for the EPUB output file name.

‘--output-indent=VAL’
     This option now does nothing, but remains for compatibility.  (It
     used to alter indentation in XML/DocBook output.)

‘-P PATH’
     Prepend PATH to the directory search list for ‘@include’.  See ‘-I’
     above.

‘--paragraph-indent=INDENT’
‘-p INDENT’
     Set the paragraph indentation style to INDENT.  The value set by
     this option overrides the value set in a Texinfo file by an
     ‘@paragraphindent’ command (see @paragraphindent).  The value
     of INDENT is interpreted as follows:

     ‘asis’
          Preserve any existing indentation (or lack thereof) at the
          beginnings of paragraphs.

     ‘0’ or ‘none’
          Delete any existing indentation.

     NUM
          Indent each paragraph by NUM spaces.

     The default is to indent by two spaces, except for paragraphs
     following a section heading, which are not indented.

‘--pdf’
     Generate a PDF file using ‘texi2dvi --pdf’, rather than Info (see
     texi2any Printed Output).

‘--plaintext’
     Output a plain text file (rather than Info): do not include menus
     or node separator lines in the output.  This results in a
     straightforward plain text file that you can (for example) send in
     email without complications, or include in a distribution (for
     example, an ‘INSTALL’ file).

     With this option the output goes to standard output by default,
     instead of to a file with a name based on the input file name or
     ‘@setfilename’; this can be overridden with ‘-o’.

‘--ps’
     Generate a PostScript file using ‘texi2dvi --ps’, rather than Info
     (see texi2any Printed Output).

‘--set-customization-variable VAR=VALUE’
‘-c VAR=VALUE’
     Set the customization variable VAR to VALUE.  The ‘=’ is optional,
     but both VAR and VALUE must be quoted to the shell as necessary so
     the result is a single word.  Many aspects of ‘texi2any’ behavior
     and output may be controlled by customization variables, beyond
     what can be set in the document by @-commands and with other
     command line switches.  See Customization Variables.

‘--split=HOW’
‘--no-split’
     When generating Info, by default large output files are split into
     smaller subfiles, of approximately 300k bytes.  When generating
     HTML, by default each output file contains one node (see
     Generating HTML).  ‘--no-split’ suppresses this splitting of the
     output.

     Alternatively, ‘--split=HOW’ may be used to specify at which level
     the HTML output should be split.  The possible values for HOW are:

     ‘chapter’
          The output is split at ‘@chapter’ and other sectioning
          @-commands at this level (‘@appendix’, etc.).

     ‘section’
          The output is split at ‘@section’ and similar.

     ‘node’
          The output is split at every node.  This is the default.

     Plain text output can be split similarly to HTML.  This may be
     useful for extracting sections from a Texinfo document and making
     them available as separate files.

‘--split-size=NUM’
     Keep Info files to at most NUM characters if possible; default is
     300,000.  (However, a single node will never be split across Info
     files.)

‘--trace-includes’
     Print the name of each included file to standard output, including
     any indirectly included files.  An include file is printed only if
     it was actually found.  When this option is given, ‘texi2any’ does
     not output in any output format.  (The purpose of this option is to
     make it easier to collect the sources of a Texinfo manual.)

‘--transliterate-file-names’
     Enable transliteration of non-ASCII characters in node and
     sectioning commands names for the purpose of file name and
     sectioning commands identifiers creation.  The file names and
     identifiers obtained that way are platform and processor dependent.
     See HTML Xref 8-bit Character Expansion.

     Redirection files for anchors and nodes are not affected, therefore
     if ‘--node-files’ is enabled, files with non-translitered names are
     created too.  It is recommended to have non-translitered file names
     created for nodes such that cross-references to the generated
     manual succeed.  See --node-files.  See HTML Xref Configuration.

‘-U VAR’
     Cause VAR to be undefined.  This is equivalent to ‘@clear VAR’ in
     the Texinfo file (see @set @clear @value).

‘--verbose’
     Cause ‘texi2any’ to display messages saying what it is doing.
     Normally, ‘texi2any’ only outputs messages if there are errors or
     warnings.

‘--version’
‘-V’
     Print the version number, then exit successfully.

‘--Xopt STR’
     Pass STR (a single shell word) to ‘texi2dvi’; may be repeated
     (see texi2any Printed Output).

‘--xml’
     Generate Texinfo XML output (rather than Info).

20.2 Environment Variables Recognized by ‘texi2any’
===================================================

‘texi2any’ also reads the environment variable ‘TEXINFO_OUTPUT_FORMAT’
to determine the output format, if not overridden by a command line
option.  The value should be one of:

     docbook  dvi  dvipdf  epub3  html  info  latex  pdf  plaintext  ps  xml

   If not set or otherwise specified, Info output is the default.

   ‘TEXINFO_OUTPUT_FORMAT’ may take some other special values, which do
not correspond to any command-line settable output format (see Output Format Selection).

   The customization variable of the same name is also read; if set,
that overrides an environment variable setting, but not a command-line
option.  See Output Format Selection.

   You can control the Perl ‘texi2any’ implementation's use of Perl
extension modules by setting the ‘TEXINFO_XS’ environment variable.
These modules are compiled native code that the interpreted Perl code
can use.  Ideally, these extension modules should just work, and the
only noticeable difference they should make is that ‘texi2any’ finishes
running sooner.  However, you can use this environment variable for the
purposes of troubleshooting: for example, if you have problems with the
output of ‘texi2any’ varying depending on whether the extension modules
are in use.

   The following values of ‘TEXINFO_XS’ are recognized by ‘texi2any’:

‘default’
     The default behavior.  Try to load extension modules, and silently
     fall back to the interpreted Perl implementations if this fails.

‘warn’
     Try to load extension modules, and if this fails, give a warning
     message before falling back to the interpreted Perl
     implementations.

‘required’
     Try to load extension modules, and if this fails, give a message
     and abort.

‘debug’
     Try to load extension modules, printing many messages while doing
     so.

‘omit’
     Do not use extension modules.

   You can disable the use of the native code implementation in the Perl
‘texi2any’ implementation for the main processing steps more finely.  If
native code modules are not used for a step, they cannot be used for the
following steps.  Three steps are distinguished, each associated with an
environment variable:

_parsing_
     Corresponds to the conversion of Texinfo input into an internal
     tree format used for further processing.  Set ‘TEXINFO_XS_PARSER’
     to ‘0’ to disable the use of the native code implementation of the
     parser module.
_structure_
     Corresponds to the determination of sectioning and node structures.
     Set ‘TEXINFO_XS_STRUCTURE’ to ‘0’ to disable the use of the native
     code implementation of Perl modules in that step.
_conversion_
     Set ‘TEXINFO_XS_CONVERT’ to ‘0’ to disable the use of the native
     code for conversion of the tree to output format.  Note that many
     output formats do not have a native code implementation for this
     step.

   This may be useful for working around bugs or incompatibilities
between the native code implementation and the implementation in pure
Perl code.

   The C ‘texi2any’ implementation uses only native code for the
_parsing_ and _structure_ steps.  For the _conversion_ step, native code
is used if possible.  If Perl code is called, the program always try to
load available Perl extension modules.  Failing to load an extension is
reported and the program aborts.  Setting ‘TEXINFO_XS’ to ‘debug’ may
still be useful to get more information.  Setting ‘TEXINFO_XS’ to ‘omit’
with the C ‘texi2any’ implementation is an error.

   You can control the C ‘texi2any’ implementation's use of embedded
Perl, by setting the ‘TEXINFO_C_EMBED_PERL’ environment variable to ‘0’
to disable the use of embedded Perl.  Set with care, as HTML
customization initialization files, conversion to most output formats
and optimal index sorting require Perl.

20.3 ‘texi2any’ Printed Output
==============================

To justify the name Texinfo-to-_any_, ‘texi2any’ has basic support for
creating printed output in the various formats: TeX DVI, PDF, and
PostScript.  This is done via the simple method of executing the
‘texi2dvi’ program when those output formats are requested, after
checking the validity of the input to give users the benefit of
‘texi2any’'s error checking.  If you don't want such error checking,
perhaps because your manual plays advanced TeX tricks together with
‘texinfo.tex’, just invoke ‘texi2dvi’ directly.

   The output format options for this are ‘--dvi’, ‘--dvipdf’, ‘--pdf’,
and ‘--ps’.  See Format with texi2dvi, for more details on these
options and general ‘texi2dvi’ operation.  In addition, the ‘--verbose’,
‘--silent’, and ‘--quiet’ options are passed on if specified; the ‘-I’
and ‘-o’ options are likewise passed on with their arguments, and
‘--debug’ without its argument.

   The only option remaining that is related to the ‘texi2dvi’
invocation is ‘--Xopt’.  Here, just the argument is passed on and
multiple ‘--Xopt’ options accumulate.  This provides a way to construct
an arbitrary command line for ‘texi2dvi’.  For example, running

     texi2any --Xopt -t --Xopt @afourpaper --pdf foo.texi

is equivalent to running

     texi2dvi -t @afourpaper --pdf foo.texi

except for the validity check.

   Although one might wish that other options to ‘texi2any’ would take
effect, they don't.  For example, running ‘texi2any --no-number-sections
--dvi foo.texi’ still results in a DVI file with numbered sections.
(Perhaps this could be improved in the future, if requests are
received.)

   The actual name of the command that is invoked is specified by the
‘TEXI2DVI’ customization variable (see Customization Variables for Multiple Formats).
As you might guess, the default is ‘texi2dvi’.

   ‘texi2any’ itself does not generate any normal output when it invokes
‘texi2dvi’, only diagnostic messages.

20.4 Customization Variables
============================

     Warning: These customization variable names and meanings may change
     in any Texinfo release.  We always try to avoid incompatible
     changes, but we cannot absolutely promise, since needs change over
     time.

   Many aspects of the behavior and output of ‘texi2any’ may be modified
by modifying so-called “customization variables”.  These fall into a few
general categories:

   • Those associated with @-commands; for example, ‘@documentlanguage’.

   • Those associated with command-line options; for example, the
     customization variable ‘SPLIT’ is associated with the ‘--split’
     command-line option.  ‘TEXINFO_OUTPUT_FORMAT’ is set based on
     output format command line options and allows specifying the output
     format.

   • Those affecting the global behavior of ‘texi2any’, in particular
     Texinfo code parsing.

   • Those associated with particular output formats.  (Variables only
     relevant for HTML output are documented in HTML Output Customization.)

   • Those relevant for multiple output formats.

   You may set customization variables on the command line using
‘--set-customization-variable 'VAR VALUE'’ (quoting the variable/value
pair to the shell) or ‘--set-customization-variable VAR=VALUE’ (using
‘=’).  A special VALUE is ‘undef’, which sets the variable to this
special "undefined" Perl value.

   The sections below give the details for each of these.

20.4.1 Customization Variables for @-Commands
---------------------------------------------

Each of the following @-commands has an associated customization
variable with the same name (minus the leading ‘@’):

     @afivepaper            @afourpaper        @afourlatex
     @afourwide             @allowcodebreaks   @bsixpaper
     @contents              @codequotebacktick
     @codequoteundirected   @deftypefnnewline  @documentdescription
     @documentencoding      @documentlanguage  @evenfooting
     @evenfootingmarks      @evenheading       @evenheadingmarks
     @everyfooting          @everyfootingmarks @everyheading
     @everyheadingmarks     @exampleindent     @firstparagraphindent
     @fonttextsize          @footnotestyle     @frenchspacing
     @headings              @kbdinputstyle     @microtype
     @novalidate            @oddfooting        @oddfootingmarks
     @oddheading            @oddheadingmarks   @pagesizes
     @paragraphindent       @setfilename       @setchapternewpage
     @shortcontents         @smallbook         @summarycontents
     @urefbreakstyle        @xrefautomaticsectiontitle

   Setting such a customization variable to a value ‘foo’ is similar to
executing ‘@CMD foo’.  It is not exactly the same, though, since any
side effects of parsing the Texinfo source are not redone.  Also, some
variables do not take Texinfo code when generating particular formats,
but an argument that is already formatted.  This is the case, for
example, for HTML for ‘documentdescription’.

   Note that if ‘texi2any’ is invoked to process the file with TeX
(e.g., with the ‘--pdf’ option), then these customization variables may
not be passed on to TeX.

20.4.2 Customization Variables and Options
------------------------------------------

The following table gives the customization variables associated with
some command line options.  See Invoking texi2any, for the meaning
of the options.

Option                               Variable
--------------------------------------------------------------------------
‘--enable-encoding’                  ‘ENABLE_ENCODING’
‘--document-language’                ‘documentlanguage’
‘--error-limit’                      ‘ERROR_LIMIT’
‘--fill-column’                      ‘FILLCOLUMN’
‘--footnote-style’                   ‘footnotestyle’
‘--force’                            ‘FORCE’
‘--headers’                          ‘HEADERS’, ‘FORMAT_MENU’
‘--internal-links’                   ‘INTERNAL_LINKS’
‘--macro-expand’                     ‘MACRO_EXPAND’
‘--no-validate’                      ‘novalidate’
‘--no-warn’                          ‘NO_WARN’
‘--node-files’                       ‘NODE_FILES’
‘--number-footnotes’                 ‘NUMBER_FOOTNOTES’
‘--number-sections’                  ‘NUMBER_SECTIONS’
‘--output’                           ‘OUTFILE’, ‘SUBDIR’
‘--paragraph-indent’                 ‘paragraphindent’
‘--split’                            ‘SPLIT’
‘--split-size’                       ‘SPLIT_SIZE’
‘--trace-includes’                   ‘TRACE_INCLUDES’
‘--transliterate-file-names’         ‘TRANSLITERATE_FILE_NAMES’
‘--verbose’                          ‘VERBOSE’

   Setting such a customization variable to a value ‘foo’ is essentially
the same as specifying the ‘--OPT=foo’ if the option takes an argument,
or ‘--OPT’ if not.

20.4.3 Output Format Selection
------------------------------

The customization variable ‘TEXINFO_OUTPUT_FORMAT’ takes the value of
the format output by ‘texi2any’.  This can be one of the usual output
formats that can be specified with options, or various other special
output formats:

‘docbook’
‘dvi’
‘dvipdf’
‘epub3’
‘html’
‘info’
‘pdf’
‘plaintext’
‘ps’
‘xml’
     These correspond to the command-line options (and
     ‘TEXINFO_OUTPUT_FORMAT’ environment variable values) of the same
     name.  The ‘TEXINFO_OUTPUT_FORMAT’ customization variable value is
     set when command-line options (or ‘TEXINFO_OUTPUT_FORMAT’
     environment variable values) set the output format.  See Invoking texi2any.

‘debugtree’
     Instead of generating a regular output format, output a text
     representation of the tree obtained by parsing the input texinfo
     document.

‘parse’
     Do only Texinfo source parsing; there is no output.

‘plaintexinfo’
     Output the Texinfo source with all the macros, ‘@include’ and
     ‘@value{}’ expanded.  This is similar to setting ‘--macro-expand’,
     but instead of being output in addition to the normal conversion,
     output of Texinfo is the main output.

‘rawtext’
     Output raw text, with minimal formatting.  For example, footnotes
     are ignored and there is no paragraph filling.  This is used by the
     parser for file names and copyright text in HTML comments, for
     example.

‘structure’
     Do only Texinfo source parsing and determination of the document
     structure; there is no output.

‘texinfosxml’
     Output the document in TexinfoSXML representation, a syntax for
     writing XML data using Lisp S-expressions.

‘textcontent’
     Output the text content only, stripped of commands; this is useful
     for spell checking or word counting, for example.  The trivial
     ‘detexinfo’ script setting this is in the ‘util’ directory of the
     Texinfo source as an example.  It's one line:

          exec texi2any -c TEXINFO_OUTPUT_FORMAT=textcontent "$@"

20.4.4 Global Customization Variables
-------------------------------------

This table gives the customization variables which affect the global
behavior of ‘texi2any’.

‘CHECK_MISSING_MENU_ENTRY’
     When a ‘@menu’ block occurs in a node, check if there is a menu
     entry for all subordinate nodes in the document sectioning
     structure.  On by default.

‘CHECK_NORMAL_MENU_STRUCTURE’
     Warn if the node pointers (either explicitly or automatically set)
     are not consistent with the order of node menu entries.  This is a
     more thorough structure check than that provided by
     ‘CHECK_MISSING_MENU_ENTRY’.  On by default.

‘COLLATION_LANGUAGE’
     By default, ‘texi2any’ sorts document indices according to the
     “Unicode Collation Algorithm” (defined in Unicode Technical
     Standard #10 (http://www.unicode.org/reports/tr10/)), without
     language-specific collation tailoring.  If set, use the language
     for linguistic tailoring of index sorting.

     Currently, ‘texi2any’ gives no warning if there is no support for
     linguistic tailoring due to either missing software or missing
     support for the specified language.

     In Perl, the ‘Unicode::Collate::Locale’ module is used for
     linguistic tailoring; therefore if this module is not installed,
     the variable will be silently ignored.

     If ‘USE_UNICODE_COLLATION’ is set to ‘0’, there is no Unicode
     collation and so no linguistic tailoring either.

     See also the ‘DOCUMENTLANGUAGE_COLLATION’ variable, described
     below.

‘COMMAND_LINE_ENCODING’
     Encoding used to decode and encode command-line arguments.  Default
     is based on the locale encoding.  This may affect file names
     inserted into output files or error messages printed by the
     program.

     Note that some file and directory names from the command line may
     not be decoded immediately, and may not be decoded at all.

     It is also used to encode command-line argument passed to commands
     called from ‘texi2any’.  For example, ‘latex2html’ will be called
     from ‘texi2any’ if ‘HTML_MATH’ is set to ‘l2h’.

‘CPP_LINE_DIRECTIVES’
     Recognize ‘#line’ directives in a "preprocessing" pass (see
     External Macro Processors); on by default.

‘DEBUG’
     If set, debugging output is generated; default is off (zero).

‘DOC_ENCODING_FOR_INPUT_FILE_NAME’
     If set, use the input Texinfo document encoding information for the
     encoding of input file names, such as file names specified as
     ‘@include’ or ‘@verbatiminclude’ arguments.  If unset, use the
     locale encoding instead.  Default is set, except on MS-Windows
     where the locale encoding is used by default.

     Note that this is for file names only; the default encoding or
     ‘@documentencoding’ is always used for the encoding of file content
     (see @documentencoding).

     The ‘INPUT_FILE_NAME_ENCODING’ variable overrides this variable.

‘DOC_ENCODING_FOR_OUTPUT_FILE_NAME’
     If set, use the input Texinfo document encoding information for the
     encoding of output file names, such as files specified with
     ‘--output’.  If unset, use the locale encoding instead.  Default is
     unset, so files names are encoded using the current locale.

     Note that this is for file names only; ‘OUTPUT_ENCODING_NAME’ is
     used for the encoding of file content.

     The ‘OUTPUT_FILE_NAME_ENCODING’ variable overrides this variable.

‘DOCUMENTLANGUAGE_COLLATION’
     If set, try to use the language specified in a ‘@documentlanguage’
     directive for language-specific tailoring of index sorting.  See
     also the ‘COLLATION_LANGUAGE’ variable, described above.  (see
     @documentlanguage.)

‘DUMP_STRUCTURE’
     For debugging.  If set, the tree constructed upon parsing a Texinfo
     document and determining the document structure is output to the
     file; if set to ‘-’ output to standard error.  Default false.

‘DUMP_TEXI’
     For debugging.  If set, no conversion is done, only parsing and
     macro expansion.  If the option ‘--macro-expand’ is set, the
     Texinfo source is also expanded to the corresponding file.  Default
     false.

‘DUMP_TREE’
     For debugging.  If set, the tree constructed upon parsing a Texinfo
     document is output to the file; if set to ‘-’ output to standard
     error.  For backward compatibility, for one release, also output to
     standard error if set to ‘1’.  Default false.

‘FORMAT_MENU’
     If set to ‘menu’, output Texinfo menus.  This is the default for
     Info.  ‘sectiontoc’ is the default setting for HTML, where instead
     of the contents of ‘@menu’ blocks being output, a list of
     subordinate sections is output in each node.  Set to
     ‘menu_no_detailmenu’ instead of ‘menu’ in HTML if you want menus
     but no automatically generated ‘@detailmenu’ in the Top node master
     menu.  If set to ‘nomenu’, do not output menus.

     This variable is set to ‘nomenu’ when generating DocBook, or when
     ‘--no-headers’ is specified.

‘IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME’
     If set, spaces are ignored after an @-command that takes braces.
     Default true, matching the TeX behavior.

‘INPUT_FILE_NAME_ENCODING’
     Encoding used for input file names.  This variable overrides any
     encoding from the document or current locale.  Normally, you do not
     need to set this variable, but it can be used if file names are in
     a certain character encoding on a filesystem.  An alternative is to
     set ‘DOC_ENCODING_FOR_INPUT_FILE_NAME’ to ‘0’ to use the locale
     encoding.  See also ‘OUTPUT_FILE_NAME_ENCODING’.

‘LOCALE_ENCODING’
     Locale encoding obtained from the system.  You should not need to
     explicitly set this variable.

‘MAX_MACRO_CALL_NESTING’
     The maximal number of recursive calls of @-commands defined through
     ‘@rmacro’; default 100000.  The purpose of this variable is to
     avoid infinite recursions.

‘MESSAGE_ENCODING’
     Encoding used to encode messages output by ‘texi2any’.  Default is
     based on the locale encoding.

‘NO_INDEX’
     If set, index entries are not recorded and @-commands related to
     indices, such as ‘@printindex’, ‘@synindex’ or ‘@defindex’ have no
     effect.  Default false.

‘NO_USER_COMMANDS’
     If set, definitions of user-defined @-command are ignored.
     ‘@alias’, ‘@definfoenclose’, ‘@defindex’, ‘@macro’ and similar
     @-commands have no effect.  Default false.

‘OUTPUT_ENCODING_NAME’
     Normalized encoding name used for output files.  Should be a usable
     charset name in HTML, typically one of the preferred IANA encoding
     names.  By default, if an input encoding is set (typically through
     ‘@documentencoding’), this information is used to set the output
     encoding name, otherwise the output encoding is based on the
     default encoding.  See @documentencoding.

‘OUTPUT_FILE_NAME_ENCODING’
     Encoding used for output file names.  This variable overrides any
     encoding from the document or current locale.

     Normally, you do not need to set this variable, but it can be used
     if file names should be created in a certain character encoding on
     a filesystem.  See also ‘INPUT_FILE_NAME_ENCODING’.

‘PACKAGE’
‘PACKAGE_VERSION’
‘PACKAGE_AND_VERSION’
‘PACKAGE_URL’
‘PACKAGE_NAME’
     The implementation's short package name, package version, package
     name and version concatenated, package URL, and full package name,
     respectively.  By default, these variables are all set through
     Autoconf, Automake, and ‘configure’.

‘PREFIX’
     The output file prefix, which is prepended to some output file
     names.  By default it is set by ‘@setfilename’ or from the input
     file (see Setting the Output File Name).  How this value is
     used depends on the value of other customization variables or
     command line options, such as whether the output is split.  The
     default is unset.

‘PROGRAM’
     Name of the program used.  By default, it is set to the name of the
     program launched, with a trailing ‘.pl’ removed.

‘SORT_ELEMENT_COUNT’
     If set, the name of a file to which a list of elements (nodes or
     sections, depending on the output format) is dumped, sorted by the
     number of lines they contain after removal of @-commands; default
     unset.  This is used by the program ‘texi-elements-by-size’ in the
     ‘util/’ directory of the Texinfo source distribution (see
     texi-elements-by-size).

‘SORT_ELEMENT_COUNT_WORDS’
     When dumping the elements-by-size file (see preceding item), use
     word counts instead of line counts; default false.

‘TEST’
     If set to a positive integer, some variables which are normally
     dynamically generated anew for each run (date, program name,
     version) are set to fixed and given values.  Some file names may
     also have the directory part removed.  Also code that gives more
     reproducible output may be selected.  This is useful to compare the
     output to a reference file, as is done for the tests.  Features not
     selected in the default case but interesting for tests are also
     enabled.  For example, code related to memory release and checks on
     released memory.  If the value is higher, more checks are enabled,
     which may require additional Perl modules installation.  The
     default is undef.

‘TEXINFO_OUTPUT_FORMAT’
     The generated output format.  Set from command line with options
     such as ‘--html’, as the ‘TEXINFO_OUTPUT_FORMAT’ environment
     variable value (see texi2any Environment Variables) or as a
     customization option.  See Output Format Selection

     The value set in the ‘TEXINFO_OUTPUT_FORMAT’ variable is in general
     the same as the name used to set the format, but not always.  If
     the format is set to ‘xml’, with ‘--xml’, with the
     ‘TEXINFO_OUTPUT_FORMAT’ environment variable or with a
     customization variable the ‘TEXINFO_OUTPUT_FORMAT’ customization
     variable is set to a more specific output format name ‘texinfoxml’.
     That kind of difference in naming should not have any user-visible
     consequence.

‘TREE_TRANSFORMATIONS’
     The associated value is a comma separated list of transformations
     that can be applied to the Texinfo tree prior to outputting the
     result.  If more than one is specified, the ordering is irrelevant;
     each is always applied at the necessary point during processing.

     By default, the tree transformations
     ‘move_index_entries_after_items’ and
     ‘relate_index_entries_to_table_entries’ are executed for HTML and
     DocBook output.  Here's an example of updating the master menu in a
     document:

          texi2any \
            -c TREE_TRANSFORMATIONS=regenerate_master_menu \
            -c TEXINFO_OUTPUT_FORMAT=plaintexinfo \
            mydoc.texi \
            -o /tmp/out

     (Caveat: Since ‘plaintexinfo’ output expands Texinfo macros and
     conditionals, it's necessary to remove any such differences before
     installing the updates in the original document.  This may be
     remedied in a future release.)

     The following transformations are currently supported (many are
     used in the ‘pod2texi’ utility distributed with Texinfo; see
     Invoking pod2texi):

     ‘complete_tree_nodes_menus’
          Add menu entries or whole menus for nodes associated with
          sections of any level, based on the sectioning tree.

     ‘complete_tree_nodes_missing_menu’
          Add whole menus for nodes associated with sections without
          menu.  The menus are based on the sectioning tree.

     ‘fill_gaps_in_sectioning’
          Adds empty ‘@unnumbered...’ sections in a tree to fill gaps in
          sectioning.  For example, an ‘@unnumberedsec’ will be inserted
          if a ‘@chapter’ is followed by a ‘@subsection’.

     ‘insert_nodes_for_sectioning_commands’
          Insert nodes for sectioning commands lacking a corresponding
          node.

     ‘move_index_entries_after_items’
          In ‘@enumerate’ and ‘@itemize’, move index entries appearing
          just before an ‘@item’ to just after the ‘@item’.  Comment
          lines between index entries are moved too.  As mentioned, this
          is always done for HTML and DocBook output.

     ‘regenerate_master_menu’
          Update the Top node master menu, either replacing the (first)
          ‘@detailmenu’ in the Top node menu, or creating it at the end
          of the Top node menu.

     ‘relate_index_entries_to_table_entries’
          In ‘@table’, ‘@vtable’ and ‘@ftable’, reassociate the index
          entry information from an index @-command appearing right
          after an ‘@item’ line with the first element of the ‘@item’.
          Remove the index @-command from the tree.

‘USE_SETFILENAME_EXTENSION’
     Default is on for Info, off for other output.  If set, use exactly
     what ‘@setfilename’ gives for the output file name, including the
     extension.  You should not need to explicitly set this variable.

‘USE_UNICODE_COLLATION’
     By default, ‘texi2any’ sorts document indices according to the
     “Unicode Collation Algorithm” (defined in Unicode Technical
     Standard #10 (http://www.unicode.org/reports/tr10/)), which
     performs a “multi-level” ordering of strings containing Unicode
     code points.  (To do this, the program uses the ‘Unicode::Collate’
     module, a standard part of Perl installations.)  However, the use
     of this algorithm incurs noticeably longer run times when
     processing manuals with large indices.

     Set this variable to ‘0’ to use a simpler, faster sorting
     algorithm.

     You may find this useful for speeding up ‘texi2any’ if you don't
     have many non-ASCII characters in index entry text, or if you don't
     care about having the indices sorted correctly, especially when
     working on the draft of a manual.

‘USE_UNIDECODE’
     If set to false, do not use the ‘Text::Unidecode’ Perl module to
     transliterate more characters from Perl code; default true.

20.4.5 Info and Plaintext Customization Variables
-------------------------------------------------

This table gives the customization variables which apply to Info and
Plaintext formats only.

‘ASCII_DASHES_AND_QUOTES’
     For Info output, when set, use plain ASCII characters to represent
     quotation marks, hyphens and dashes when these are given in the
     Texinfo source as ‘-’, ‘--’, ‘---’, ‘`’, ‘``’, ‘'’, and ‘''’,
     rather than UTF-8 directional quotation marks, en dashes, vel sim.
     On by default.

‘ASCII_GLYPH’
     For Info output, use ASCII output for glyph commands such as the
     copyright sign (‘@copyright{}’, becoming ‘(C)’), and the bullet
     symbol (‘@bullet{}’, becoming ‘*’), rather than other Unicode
     sequences.  Off by default.

‘ASCII_PUNCTUATION’
     Avoid any unnecessary or gratuitous non-ASCII, UTF-8 sequences in
     the output.  Implies both ‘ASCII_DASHES_AND_QUOTES’ and
     ‘ASCII_GLYPH’ and additionally affects the output of commands such
     as ‘@samp’ which output quotation marks.

‘AUTO_MENU_DESCRIPTION_ALIGN_COLUMN’
     For Info output, column at which to start a menu entry description
     provided by ‘@nodedescription’ or ‘@nodedescriptionblock’.
     Undefined by default, in which case 45% of the fill column value is
     used (see Invoking texi2any).

‘AUTO_MENU_MAX_WIDTH’
     Maximum number of columns in a menu entry line in Info when adding
     a description from ‘@nodedescription’ or ‘@nodedescriptionblock’.
     Undefined by default, in which case 10% more than the fill column
     value is used (see Invoking texi2any).

‘CLOSE_DOUBLE_QUOTE_SYMBOL’
     When a closing double quote is needed, for ‘@dfn’ in Info, use this
     character.  The default for Info is set the same as for
     ‘OPEN_DOUBLE_QUOTE_SYMBOL’, except that the Unicode code is a
     closing double quote (see below).

‘INDEX_SPECIAL_CHARS_WARNING’
     If set, warn about ‘:’ in index entry, as not all Info readers may
     be able to process these.  For Info and plaintext only.  Default
     false, because parsing problems there don't prevent navigation;
     readers can still relatively easily find their way to the node in
     question.

‘INFO_MATH_IMAGES’
     (Experimental.)  If set, convert the contents of ‘@math’ and
     ‘@displaymath’ into images, and reference these in the produced
     Info file.  This variable requires a working TeX installation, the
     ‘preview’ package of LaTeX, as well as the ‘dvipng’ program.  It
     may be suitable for math-heavy documents that are unlikely to be
     viewed in a text terminal.

     This feature is marked as experimental as it would require extra
     support in Info-viewing programs (currently, only the Info mode of
     Emacs) to view the images correctly.  The images should be visible
     with existing versions of Emacs, but they may be the wrong size or
     appear misaligned with surrounding text.  It is possible that we
     will change the output for this option given further feedback.
     See Info Format Image for more details about how images are
     currently output with this option.

‘INFO_SPECIAL_CHARS_QUOTE’
     If set, whenever there are problematic characters for Info output
     in places such as node names or menu items, surround the part of
     the construct where they appear with quoting characters, as
     described in Info Format Specification.  Default is set for
     Info and unset for plaintext.  See Node Line Requirements.

‘INFO_SPECIAL_CHARS_WARNING’
     If set, warn about problematic constructs for Info output (such as
     the string ‘::’) in node names, menu items, and cross-references.
     If not defined, set unless ‘INFO_SPECIAL_CHARS_QUOTE’ is set.
     Default is set for Info and not defined for plaintext.  Similar
     warnings in index entries are covered by
     ‘INDEX_SPECIAL_CHARS_WARNING’.

‘OPEN_DOUBLE_QUOTE_SYMBOL’
     When an opening double quote is needed, for ‘@dfn’ output in Info,
     use the specified character.  If ‘--disable-encoding’ is set or the
     document encoding is not UTF-8, ‘"’ is used.  Otherwise, the Info
     output uses a Unicode left double quote.

20.4.6 LaTeX Customization Variables
------------------------------------

     warning: LaTeX output customization is experimental.  Nothing is
     decided, everything can change, and we would welcome any feedback.

   This table gives the customization variables which apply to LaTeX
output only.

‘CLASS_BEGIN_USEPACKAGE’
     If set, the corresponding text will replace the LaTeX
     ‘\documentclass’, package imports that are always output and are
     output right after ‘\documentclass’, and package imports that
     depend on the document encoding setting the input and font encoding
     (‘inputenc’ and ‘fontenc’).

     The text replaced is along:
          \documentclass{book}
          \usepackage{amsfonts}
          \usepackage{amsmath}
          \usepackage[gen]{eurosym}
          \usepackage{textcomp}
          \usepackage{graphicx}
          \usepackage{etoolbox}
          \usepackage{titleps}
          \usepackage[utf8]{inputenc}
          \usepackage[T1]{fontenc}

‘END_USEPACKAGE’
     If set, the corresponding text will replace the package imports
     that depend on the Texinfo commands used, and the last packages
     imports that are always output and output after all the other
     packages imports.  The last package imports corresponds to
     ‘\usepackage[hidelinks]{hyperref}’.

     Here is an example of the corresponding text for a document with
     indices, ‘@need’, ‘@multitable’, definition commands, ‘@cartouche’,
     lists, and ‘@float’:
          \usepackage{imakeidx}
          \usepackage{needspace}
          \usepackage{array}
          \usepackage{embrac}
          \usepackage{expl3}
          \usepackage{tabularx}
          \usepackage[framemethod=tikz]{mdframed}
          \usepackage{enumitem}
          \usepackage{float}
          \usepackage[hidelinks]{hyperref}

‘LATEX_FLOATS_FILE_EXTENSION’
     Set new floats definition file extension for LaTeX output.  Default
     ‘tfl’.

20.4.7 Other Formats Customization Variables
--------------------------------------------

This table gives the customization which apply to specific formats only,
for formats without separate customization variables description
section.

‘TXI_MARKUP_NO_SECTION_EXTENT’
     For XML.  Do not include lower level sectioning commands inside
     upper-level sectioning command markup.  Default false.

‘TEXI2DVI’
     Name of the command used to produce PostScript, PDF, and DVI;
     default ‘texi2dvi’.  See texi2any Printed Output.

‘TEXTCONTENT_COMMENT’
     For stripped text content output (i.e., when
     ‘TEXINFO_OUTPUT_FORMAT’ is set to ‘textcontent’).  If set, also
     output comments.  Default false.

‘TEXINFO_DTD_VERSION’
     For XML.  Version of the DTD used in the XML output preamble.  The
     default is set based on a variable in ‘configure.ac’.

20.4.8 Customization Variables for Multiple Formats
---------------------------------------------------

This table gives the customization which apply to multiple formats.

‘CLOSE_QUOTE_SYMBOL’
     When a closing quote is needed, e.g. for ‘@samp’ output, use this
     character; default ‘&#8217;’ in DocBook.  Undefined in the default
     case in HTML and set to ‘&rsquo;’ if ‘USE_NUMERIC_ENTITY’ is not
     set, to ‘&#8217;’ if set, and to a quote character if
     ‘OUTPUT_CHARACTERS’ is set and the output encoding includes that
     character.

     The default for Info is set the same as for ‘OPEN_QUOTE_SYMBOL’,
     except that the Unicode code is a closing quote (see below).

‘DOCTYPE’
     For DocBook, HTML, XML.  Specifies the ‘SystemLiteral’, the
     entity's system identifier.  This is a URI which may be used to
     retrieve the entity, and identifies the canonical DTD for the
     document.  The default value is different for each of HTML, DocBook
     and XML.

‘EXTENSION’
     The extension added to the output file name.  The default is
     different for each output format.

‘NO_TOP_NODE_OUTPUT’
     If set do not output the Top node content.  The Top node is still
     parsed, but the content is discarded.  Not set in the default case
     for HTML.  Set in the default case for EPUB.  If ‘SHOW_TITLE’ is
     ‘undef’, setting ‘NO_TOP_NODE_OUTPUT’ also sets ‘SHOW_TITLE’ for
     HTML.

     Setting ‘NO_TOP_NODE_OUTPUT’, which removes the Top node and adds a
     title page corresponds more to the formatting of a book.  Setting
     ‘NO_TOP_NODE_OUTPUT’ to false, with ‘SHOW_TITLE’ remaining ‘undef’,
     and false, corresponds more to a document setup for browsing, with
     a direct access to the information at the Top node.

     For DocBook, ‘NO_TOP_NODE_OUTPUT’ is set to true.  Setting
     ‘NO_TOP_NODE_OUTPUT’ to false causes the Top node content to be
     output.  It is not recommended to output the Top node in DocBook as
     the title and copying texts are always output.  This option is kept
     for DocBook for compatibility, as before 2022 the Top node was
     output in DocBook.  It could be removed in the future.

‘OPEN_QUOTE_SYMBOL’
     When an opening quote is needed, e.g., for ‘@samp’ output, use the
     specified character; default ‘&#8216;’ for DocBook.  Undefined in
     the default case in HTML and set to ‘&lsquo;’ if
     ‘USE_NUMERIC_ENTITY’ is not set, to ‘&#8216;’ if set, and to a
     quote character if ‘OUTPUT_CHARACTERS’ is set and the output
     encoding includes that character.

     For Info, the default depends on the enabled document encoding.  If
     ‘--disable-encoding’ is set or the document encoding is not UTF-8,
     ‘'’ is used.  This character usually appears as an undirected
     single quote on modern systems.  Otherwise, the Info output uses a
     Unicode left quote.

‘OUTPUT_CHARACTERS’
     If not set, the default, output accented and special characters in
     HTML, XML and DocBook using XML entities, and in LaTeX using
     macros.  If set, output accented characters in HTML, XML, DocBook
     and LaTeX output and special characters in HTML and LaTeX output
     based on the document encoding.  See @documentencoding, and
     Inserting Accents.

‘TOP_NODE_UP’
     Up node for the Top node; default ‘(dir)’.  This node name is
     supposed to be already formatted for the output format.  In HTML
     can be used in attribute, so should not contain any element.  Used
     for HTML output only if ‘TOP_NODE_UP_URL’ is set to override the
     URL, see ‘TOP_NODE_UP_URL’ in HTML Customization Variables List.
     See File Names and Links Customization for HTML.

‘USE_NODES’
     The main unit of output documents is an “output unit”.  Usually a
     node is associated with a following sectioning command, while a
     sectioning command is associated with a previous node; they both
     together make up the output unit.

     For Plaintext and HTML.  Preferentially use nodes to decide where
     output units are separated if ‘USE_NODES’ is set.  If set to false,
     preferentially use sectioning to decide where output units are
     separated.  The default is true.

‘USE_NUMERIC_ENTITY’
     For HTML, XML and DocBook.  If set, use numeric entities instead of
     named entities.  By default, set to true for DocBook output.

20.5 Internationalization of Document Strings
=============================================

‘texi2any’ writes fixed strings into the output document at various
places: cross-references, page footers, the help page, alternate text
for images, and so on.  The string chosen depends on the value of the
‘documentlanguage’ at the time of the string being output (see
@documentlanguage, for the Texinfo command interface).

   The Gettext framework with the ‘texinfo_document’ domain is used for
those strings (see gettext).  Translated strings are written as
Texinfo, and may include @-commands.  In translated strings, the varying
parts of the string are denoted by ‘{arg_name}’, but not by ‘%s’ and the
like.  (This convention is common for ‘gettext’ in Perl and is fully
supported in GNU Gettext; see Perl Format Strings (gettext))
For example, in the following, ‘{section}’ will
be replaced by the section name:

     see {section}

   The expansion of a translation string is done like this:

  1. First, the string is translated.  The locale is
     DOCUMENTLANGUAGE‘.’DOCUMENTENCODING.

     If the DOCUMENTLANGUAGE has the form ‘ll_CC’, that is tried first,
     and then just ‘ll’.

  2. Next, in most cases, the string is expanded as Texinfo, and
     converted.  The arguments are substituted; for example,
     ‘{arg_name}’ is replaced by the corresponding actual argument.

     It is also possible for the string and the argument to be already
     converted.  In that case, the arguments are simply substituted.
     Similarly, ‘{arg_name}’ is replaced by the corresponding actual
     argument.

   In the following example, ‘{date}’, ‘{program_homepage}’ and
‘{program}’ are the arguments of the string.  Since they are used in
‘@uref’, their order is not predictable.  ‘{date}’, ‘{program_homepage}’
and ‘{program}’ are substituted after the expansion:

     Generated on @emph{{date}} using
     @uref{{program_homepage}, @emph{{program}}}.

   This approach is admittedly a bit complicated.  Its usefulness is
that it supports specifying the formatting of the translated string
independently of the output format.

   For example, the ‘@pxref’ translation string can be like this:

     see {node_file_href} section `{section}' in @cite{{book}}

which allows for specifying a string independently of the output format,
while nevertheless with rich formatting it may be translated
appropriately in many languages.

   If Perl is used for strings translation in ‘texi2any’, the
‘libintl-perl’ package is used as the ‘gettext’ implementation; more
specifically, the pure Perl implementation is used, so Texinfo can
support consistent behavior across all platforms and installations,
which would not otherwise be possible.  ‘libintl-perl’ is included in
the Texinfo distribution and always installed, to ensure that it is
available if needed.  It is also possible to use the system
‘libintl-perl’ (the choice can be made at build-time).

20.6 Invoking ‘pod2texi’: Convert Pod to Texinfo
================================================

The ‘pod2texi’ program translates Perl Pod documentation file(s) to
Texinfo.  There are two basic modes of operation: generating a
standalone manual from each input Pod, or (if ‘--base-level=1’ or higher
is given) generating Texinfo subfiles suitable for use with ‘@include’.

   The ‘pod2texi’ program may be useful outside of the rest of Texinfo;
thus, the invocation of ‘pod2texi’ is documented in the Pod language
using the man page format to follow the convention used in Perl
standalone programs, with a version on the web
<https://www.gnu.org/software/texinfo/manual/pod2texi.html> and a
version included below.  The version included in the manual is also an
example of ‘pod2texi’ use, as it is converted from Pod using ‘pod2texi’.

20.6.1 pod2texi
---------------

pod2texi NAME
.............

pod2texi - convert Pod to Texinfo

pod2texi SYNOPSIS
.................

  pod2texi [OPTION]... POD...

pod2texi DESCRIPTION
....................

Translate Pod file(s) to Texinfo.  There are two basic modes of
operation.  First, by default, each Pod is translated to a standalone
Texinfo manual.

   Second, if ‘--base-level’ is set higher than 0, each Pod is
translated to a file suitable for ‘@include’, and one more file with a
main menu and all the ‘@include’ is generated.

pod2texi OPTIONS
................

*--appendix-sections*

     Use appendix sectioning commands (‘@appendix’, ...)  instead of the
     default numbered sectioning Texinfo @-commands (‘@chapter’,
     ‘@section’, ...).

*--base-level*=_NUM|NAME_

     Sets the level of the ‘head1’ commands.  It may be an integer or a
     Texinfo sectioning command (without the ‘@’): 1 corresponds to the
     ‘@chapter’/‘@unnumbered’ level, 2 to the ‘@section’ level, and so
     on.  The default is 0, meaning that ‘head1’ commands are still
     output as chapters, but the output is arranged as a standalone
     manual.

     If the level is not 0, the Pod file is rendered as a fragment of a
     Texinfo manual suitable for ‘@include’.  In this case, each Pod
     file has an additional sectioning command covering the entire file,
     one level above the ‘--base-level’ value.  Therefore, to make each
     Pod file a chapter in a large manual, you should use ‘section’ as
     the base level.

     For an example of making Texinfo out of the Perl documentation
     itself, see ‘contrib/perldoc-all’ in the Texinfo source
     distribution.

*--debug*=_NUM_

     Set debugging level to _NUM_.

*--generate-setfilename*

     Generate a ‘@setfilename’ line for standalone manuals.  Can be
     negated with ‘--no-generate-setfilename’.  Ignored if
     ‘--base-level’ is not 0.

*--headings-as-sections*

     Use headings commands (‘@heading’, ...)  instead of the default
     numbered sectioning Texinfo @-commands (‘@chapter’, ‘@section’,
     ...).  The sectioning command covering the entire file output for
     each Pod file if *--base-level* is not 0 is a numbered command.

*--help*

     Display help and exit.

*--menus*

     Output node menus.  If there is a main manual, its Top node menu is
     always output, since a master menu is generated.  Other nodes menus
     are not output in the default case.

*--outdir*=_NAME_

     If there is a main manual with include files (each corresponding to
     an input Pod file), then the generated Texinfo files are put in
     directory _NAME_. Default is based on ‘--subdir’.

*--output*=_NAME_

     Name for the first manual, or the main manual if there is a main
     manual.  Default is to write to standard output.

*--no-section-nodes*

     Use anchors for sections instead of nodes.

*--no-fill-section-gaps*

     Do not fill sectioning gaps with empty ‘@unnumbered’ files.
     Ordinarily, it's good to keep the sectioning hierarchy intact.

*--preamble*=_STR_

     Insert _STR_ as top boilerplate before menu and includes.  If _STR_
     is set to ‘-’, read the top boilerplate from the standard input.
     The default top boilerplate is a minimal beginning for a Texinfo
     document.

*--setfilename*=_STR_

     Use _STR_ in top boilerplate before menu and includes for
     ‘@setfilename’ for the main manual, if ‘--base-level’ is not set to
     0.  Ignored if ‘--base-level’ is 0.  No ‘@setfilename’ is output in
     the default case for the main manual.

*--subdir*=_NAME_

     If there is a main manual with include files (each corresponding to
     an input Pod file), then those include files are included from
     _NAME_.

     If ‘--outdir’ is set, _NAME_ should in general be set to the
     relative directory between the main manual and ‘--outdir’ argument.

*--unnumbered-sections*

     Use unnumbered sectioning commands (‘@unnumbered’, ...)  instead of
     the default numbered sectioning Texinfo @-commands (‘@chapter’,
     ‘@section’, ...).

*--top*=_TOP_

     Name of the ‘@top’ element for the main manual.  May contain
     Texinfo code.

*--version*

     Display version information and exit.

pod2texi SEE ALSO
.................

Pod::Simple::Texinfo
(https://www.gnu.org/software/texinfo/manual/Pod/Simple/Texinfo.html).
perlpod (https://metacpan.org/pod/perlpod).  The Texinfo manual.
Texinfo home page: <https://www.gnu.org/software/texinfo/>

pod2texi COPYRIGHT AND LICENSE
..............................

Copyright 2012-2026 Free Software Foundation, Inc.

   This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

   There is NO WARRANTY, to the extent permitted by law.

pod2texi AUTHOR
...............

Patrice Dumas <bug-texinfo@gnu.org>.

20.7 ‘texi2html’: Ancestor of ‘texi2any’
========================================

Conceptually, the ‘texi2html’ program is the parent of today's
‘texi2any’ program.  ‘texi2html’ was developed independently, originally
by Lionel Cons in 1998; at the time, ‘makeinfo’ could not generate HTML.
Many other people contributed to ‘texi2html’ over the years.

   The present ‘texi2any’ uses little of the actual code of ‘texi2html’,
and has quite a different basic approach to the implementation (namely,
parsing the Texinfo document into a tree), but still, there is a family
resemblance.

   By design, ‘texi2any’ supports nearly all the features of ‘texi2html’
in some way.  However, we did not attempt to maintain strict
compatibility, so no ‘texi2html’ executable is installed by the Texinfo
package.  An approximation can be run with an invocation like this:

     texi2any --set-customization-variable TEXI2HTML=1 ...

but, to emphasize, this is _not_ a drop-in replacement for the previous
‘texi2html’.  Here are the biggest differences:

   • Most blatantly, the command line options of ‘texi2html’ are now
     customization variables, for the most part.  A table of approximate
     equivalents is given below.

   • The program-level customization API is very different in
     ‘texi2any’.

   • Indices cannot be split.

   We do not intend to reimplement these differences.  Therefore, the
route forward for authors is alter manuals and build processes as
necessary to use the new features and methods of ‘texi2any’.  The
‘texi2html’ maintainers (one of whom is the principal author of
‘texi2any’) do not intend to make further releases.

   Here is the table showing ‘texi2html’ options and corresponding
‘texi2any’ customization variables.

‘--toc-links’          ‘TOC_LINKS’
‘--short-ext’          ‘EXTENSION’ set to ‘htm’
‘--prefix’             ‘PREFIX’
‘--def-table’          ‘DEF_TABLE’
‘--html-xref-prefix’   ‘EXTERNAL_DIR’
‘--l2h’                ‘HTML_MATH’ set to ‘l2h’
‘--l2h-l2h’            ‘L2H_L2H’
‘--l2h-skip’           ‘L2H_SKIP’
‘--l2h-tmp’            ‘L2H_TMP’
‘--l2h-file’           ‘L2H_FILE’
‘--l2h-clean’          ‘L2H_CLEAN’
‘--use-nodes’          ‘USE_NODES’
‘--monolithic’         ‘MONOLITHIC’
‘--top-file’           ‘TOP_FILE’
‘--frames’             no equivalent
‘--menu’               ‘FORMAT_MENU’
‘--debug’              ‘DEBUG’
‘--doctype’            ‘DOCTYPE’
‘--frameset-doctype’   no equivalent
‘--test’               ‘TEST’

   Finally, any ‘texi2html’ users seeking more detailed information can
check the first part of the archived file ‘doc/texi2oldapi.texi’ in the
Texinfo source repository.

21 Creating and Installing Info Files
*************************************

This chapter gives some information on the Info output and describes how
to install Info files.  For the creation of Info files with ‘texi2any’,
see Generic Translator texi2any, and with Emacs, see Info Formatting.
See Info Files, for general information about the
file format.  See Info Format Specification, for a detailed
technical specification of the Info format.

21.1 Installing an Info File
============================

Info files are usually kept in the ‘info’ directory.  You can read Info
files using the standalone Info program or the Info reader built into
Emacs.  (see info, for an introduction to Info.)

21.1.1 The Directory File ‘dir’
-------------------------------

For Info to work, the ‘info’ directory must contain a file that serves
as a top-level directory for the Info system.  By convention, this file
is called ‘dir’.  (You can find the location of this file within Emacs
by typing ‘C-h i’ to enter Info and then typing ‘C-x C-f’ to see the
location of the ‘info’ directory.)

   The ‘dir’ file is itself an Info file.  It contains the top-level
menu for all the Info files in the system.  The menu looks like this:

     * Menu:
     * Info:    (info).     Documentation browsing system.
     * Emacs:   (emacs).    The extensible, self-documenting
                           text editor.
     * Texinfo: (texinfo).  With one source file, make
                           either a printed manual using
                           @TeX{} or an Info file.
     ...

   Each of these menu entries points to the 'Top' node of the Info file
that is named in parentheses.  (The menu entry does not need to specify
the 'Top' node, since Info goes to the 'Top' node if no node name is
mentioned.  See Nodes in Other Info Files.)

   Thus, the ‘Info’ entry points to the 'Top' node of the ‘info’ file
and the ‘Emacs’ entry points to the 'Top' node of the ‘emacs’ file.

   In each of the Info files, the 'Up' pointer of the 'Top' node refers
back to the ‘dir’ file.  For example, the line for the 'Top' node of the
Emacs manual looks like this in Info:

     File: emacs  Node: Top, Up: (DIR), Next: Distrib

In this case, the ‘dir’ file name is written in uppercase letters--it
can be written in either upper- or lowercase.  This is not true in
general, it is a special case for ‘dir’.

   See the ‘util/dir-example’ file in the Texinfo distribution for a
large sample ‘dir’ file.

21.1.2 Listing a New Info File
------------------------------

To add a new Info file to your system, you must write a menu entry to
add to the menu in the ‘dir’ file in the ‘info’ directory.  For example,
if you were adding documentation for GDB, you would write the following
new entry:

     * GDB: (gdb).           The source-level C debugger.

The first part of the menu entry is the menu entry name, followed by a
colon.  The second part is the name of the Info file, in parentheses,
followed by a period.  The third part is the description.

   The name of an Info file often has a ‘.info’ extension.  Thus, the
Info file for GDB might be called either ‘gdb’ or ‘gdb.info’.  The Info
reader programs automatically try the file name both with and without
‘.info’(1); so it is better to avoid clutter and not to write ‘.info’
explicitly in the menu entry.  For example, the GDB menu entry should
use just ‘gdb’ for the file name, not ‘gdb.info’.

   ---------- Footnotes ----------

   (1) On MS-DOS/MS-Windows systems, Info will try the ‘.inf’ extension
as well.

21.1.3 Info Files in Other Directories
--------------------------------------

If an Info file is not in the ‘info’ directory, there are three ways to
specify its location:

  1. Write the file name in the ‘dir’ file as the second part of the
     menu.

  2. Specify the Info directory name in the ‘INFOPATH’ environment
     variable in your ‘.profile’ or ‘.cshrc’ initialization file.  (Only
     you and others who set this environment variable will be able to
     find Info files whose location is specified this way.)

  3. If you are using Emacs, list the name of the file in a second ‘dir’
     file, in its directory; and then add the name of that directory to
     the ‘Info-directory-list’ variable in your personal or site
     initialization file.

     This variable tells Emacs where to look for ‘dir’ files (the files
     must be named ‘dir’).  Emacs merges the files named ‘dir’ from each
     of the listed directories.  (In Emacs version 18, you can set the
     ‘Info-directory’ variable to the name of only one directory.)

   For example, to reach a test file in the ‘/home/bob/info’ directory,
you could add an entry like this to the menu in the standard ‘dir’ file:

     * Test: (/home/bob/info/info-test).  Bob's own test file.

In this case, the absolute file name of the ‘info-test’ file is written
as the second part of the menu entry.

   If you don't want to edit the system ‘dir’ file, you can tell Info
where to look by setting the ‘INFOPATH’ environment variable in your
shell startup file.  This works with both the Emacs and standalone Info
readers.

   Emacs uses the ‘INFOPATH’ environment variable to initialize the
value of Emacs's own ‘Info-directory-list’ variable.  The standalone
Info reader merges any files named ‘dir’ in any directory listed in the
‘INFOPATH’ variable into a single menu presented to you in the node
called ‘(dir)Top’.

   However you set ‘INFOPATH’, if its last character is a colon (on
MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced by
the default (compiled-in) path.  This gives you a way to augment the
default path with new directories without having to list all the
standard places.  For example (using ‘sh’ syntax):

     INFOPATH=/home/bob/info:
     export INFOPATH

will search ‘/home/bob/info’ first, then the standard directories.
Leading or doubled colons are not treated specially.

   When you create your own ‘dir’ file for use with
‘Info-directory-list’ or ‘INFOPATH’, it's easiest to start by copying an
existing ‘dir’ file and replace all the text after the ‘* Menu:’ with
your desired entries.  That way, the punctuation and special ‘CTRL-_’
characters that Info needs will be present.

   As one final alternative, which works only with Emacs Info, you can
change the ‘Info-directory-list’ variable.  For example:

     (add-hook 'Info-mode-hook '(lambda ()
     	     (add-to-list 'Info-directory-list
     			  (expand-file-name "~/info"))))

21.1.4 Installing Info Directory Files
--------------------------------------

When you install an Info file onto your system, you can use the program
‘install-info’ to update the Info directory file ‘dir’.  Normally the
makefile for the package runs ‘install-info’, just after copying the
Info file into its proper installed location.

   In order for the Info file to work with ‘install-info’, you include
the commands ‘@dircategory’ and ‘@direntry’...‘@end direntry’ in the
Texinfo source file.

   Use ‘@dircategory’ to specify a category for the manual, which
determines which part of the Info directory to put it in.  (see
Directory Category.)  Use ‘@direntry’ to specify the menu entry, or
entries, to add to the Info directory file.  Some manuals (such as the
manual you are reading now, or that of GNU Coreutils; see
coreutils) will have several entries.  It is typical to have one
dir entry for each program that a package installs, usually to the
program's 'Invoking' node.  This lets users easily find the
documentation for the different programs they can run.  Likewise, a
manual for a C library may install a dir entry for each function it
provides.

   Here is how these commands are used in this manual:

     @dircategory Texinfo documentation system
     @direntry
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     @end direntry

   Here's what this produces in the Info file:

     INFO-DIR-SECTION Texinfo documentation system
     START-INFO-DIR-ENTRY
     * Texinfo: (texinfo).           The GNU documentation format.
     * install-info: (texinfo)Invoking install-info. ...
     ...
     END-INFO-DIR-ENTRY

The ‘install-info’ program sees these lines in the Info file, and that
is how it knows what to do.

   Always use the ‘@direntry’ and ‘@dircategory’ commands near the
beginning of the Texinfo input, before the first ‘@node’ command.  If
you use them later on in the input, ‘install-info’ will not notice them.

   ‘install-info’ will automatically reformat the description of the
menu entries it is adding.  As a matter of convention, the description
of the main entry (above, ‘The GNU documentation format’) should start
at column 32, starting at zero (as in ‘what-cursor-position’ in Emacs).
This will make it align with most others.  Description for individual
utilities best start in column 48, where possible.  For more information
about formatting see the ‘--calign’, ‘--align’, and ‘--max-width’
options in Invoking install-info.

   If you use ‘@dircategory’ more than once in the Texinfo source, each
usage specifies the 'current' category; any subsequent ‘@direntry’
commands will add to that category.

21.1.5 Invoking ‘install-info’
------------------------------

‘install-info’ inserts menu entries from an Info file into the top-level
‘dir’ file in the Info system (see the previous sections for an
explanation of how the ‘dir’ file works).  ‘install-info’ also removes
menu entries from the ‘dir’ file.  It's most often run as part of
software installation, or when constructing a ‘dir’ file for all manuals
on a system.  Synopsis:

     install-info [OPTION...] [INFO-FILE [DIR-FILE]]

   If INFO-FILE or DIR-FILE are not specified, the options (described
below) that define them must be.  There are no compile-time defaults,
and standard input is never used.  ‘install-info’ can read only one Info
file and write only one ‘dir’ file per invocation.

   If DIR-FILE (however specified) does not exist, ‘install-info’
creates it if possible (with no entries).

   If any input file is compressed with ‘gzip’ (see gzip),
‘install-info’ automatically uncompresses it for reading.  And if
DIR-FILE is compressed, ‘install-info’ also automatically leaves it
compressed after writing any changes.  If DIR-FILE itself does not
exist, ‘install-info’ tries to open ‘DIR-FILE.gz’, ‘DIR-FILE.xz’,
‘DIR-FILE.bz2’, ‘DIR-FILE.lz’, and ‘DIR-FILE.lzma’, in that order.

   Options:

‘--add-once’
     Specifies that the entry or entries will only be put into a single
     section.

‘--align=COLUMN’
     Specifies the column that the second and subsequent lines of menu
     entry's description will be formatted to begin at.  The default for
     this option is ‘35’.  It is used in conjunction with the
     ‘--max-width’ option.  COLUMN starts counting at 1.

‘--append-new-sections’
     Instead of alphabetizing new sections, place them at the end of the
     DIR file.

‘--calign=COLUMN’
     Specifies the column that the first line of menu entry's
     description will be formatted to begin at.  The default for this
     option is ‘33’.  It is used in conjunction with the ‘--max-width’
     option.  When the name of the menu entry exceeds this column,
     entry's description will start on the following line.  COLUMN
     starts counting at 1.

‘--debug’
     Report what is being done.

‘--delete’
     Delete the entries in INFO-FILE from DIR-FILE.  The file name in
     the entry in DIR-FILE must be INFO-FILE (except for an optional
     ‘.info’ in either one).  Don't insert any new entries.  Any empty
     sections that result from the removal are also removed.

‘--description=TEXT’
     Specify the explanatory portion of the menu entry.  If you don't
     specify a description (either via ‘--entry’, ‘--item’ or this
     option), the description is taken from the Info file itself.

‘--dir-file=NAME’
     Specify file name of the Info directory file.  This is equivalent
     to using the DIR-FILE argument.

‘--dry-run’
     Same as ‘--test’.

‘--entry=TEXT’
     Insert TEXT as an Info directory entry; TEXT should have the form
     of an Info menu item line plus zero or more extra lines starting
     with whitespace.  If you specify more than one entry, they are all
     added.  If you don't specify any entries, they are determined from
     information in the Info file itself.

‘--help’
     Display a usage message with basic usage and all available options,
     then exit successfully.

‘--info-file=FILE’
     Specify Info file to install in the directory.  This is equivalent
     to using the INFO-FILE argument.

‘--info-dir=DIR’
     Specify the directory where the directory file ‘dir’ resides.
     Equivalent to ‘--dir-file=DIR/dir’.

‘--infodir=DIR’
     Same as ‘--info-dir’.

‘--item=TEXT’
     Same as ‘--entry=TEXT’.  An Info directory entry is actually a menu
     item.

‘--keep-old’
     Do not replace pre-existing menu entries.  When ‘--remove’ is
     specified, this option means that empty sections are not removed.

‘--max-width=COLUMN’
     Specifies the column that the menu entry's description will be
     word-wrapped at.  COLUMN starts counting at 1.

‘--maxwidth=COLUMN’
     Same as ‘--max-width’.

‘--menuentry=TEXT’
     Same as ‘--name’.

‘--name=TEXT’
     Specify the name portion of the menu entry.  If the TEXT does not
     start with an asterisk ‘*’, it is presumed to be the text after the
     ‘*’ and before the parentheses that specify the Info file.
     Otherwise TEXT is taken verbatim, and is taken as defining the text
     up to and including the first period (a space is appended if
     necessary).  If you don't specify the name (either via ‘--entry’,
     ‘--item’ or this option), it is taken from the Info file itself.
     If the Info does not contain the name, the basename of the Info
     file is used.

‘--no-indent’
     Suppress formatting of new entries into the ‘dir’ file.

‘--quiet’
‘--silent’
     Suppress warnings, etc., for silent operation.

‘--remove’
     Same as ‘--delete’.

‘--remove-exactly’
     Also like ‘--delete’, but only entries if the Info file name
     matches exactly; ‘.info’ and/or ‘.gz’ suffixes are _not_ ignored.

‘--section=SEC’
     Put this file's entries in section SEC of the directory.  If you
     specify more than one section, all the entries are added in each of
     the sections.  If you don't specify any sections, they are
     determined from information in the Info file itself.  If the Info
     file doesn't specify a section, the menu entries are put into the
     Miscellaneous section.

‘--section REGEX SEC’
     Same as ‘--regex=REGEX --section=SEC --add-once’.

     ‘install-info’ tries to detect when this alternate syntax is used,
     but does not always guess correctly.  Here is the heuristic that
     ‘install-info’ uses:
       1. If the second argument to ‘--section’ starts with a hyphen,
          the original syntax is presumed.

       2. If the second argument to ‘--section’ is a file that can be
          opened, the original syntax is presumed.

       3. Otherwise the alternate syntax is used.

     When the heuristic fails because your section title starts with a
     hyphen, or it happens to be a file that can be opened, the syntax
     should be changed to ‘--regex=REGEX --section=SEC --add-once’.

‘--regex=REGEX’
     Put this file's entries into any section that matches REGEX.  If
     more than one section matches, all of the entries are added in each
     of the sections.  Specify REGEX using basic regular expression
     syntax, more or less as used with ‘grep’, for example.

‘--test’
     Suppress updating of the directory file.

‘--version’
     Display version information and exit successfully.

21.2 Tag Files and Split Files
==============================

Info files always contain a “tag table”, to be able to jump to nodes
quickly.  Info files can be “nonsplit” (also called “unsplit”) or
“split”.

   If the Info file contains less than about 300,000 characters the file
should be nonsplit.  In that case, the tag table should appear at the
end of the Info file.  If the Texinfo file contains more than about
300,000 characters, Texinfo processors split the large Info file into
shorter “indirect” subfiles of about 300,000 characters each.  With
‘texi2any’, splitting may be prevented by ‘--no-split’, and the default
size of 300,000 characters may be modified with ‘--split-size’ (see
Invoking texi2any).

   When a file is split, Info itself makes use of a shortened version of
the original file that contains just the tag table and references to the
files that were split off.  The split-off files are called “indirect”
files.

   The split-off files have names that are created by appending ‘-1’,
‘-2’, ‘-3’ and so on to the output file name, specified by the
‘@setfilename’ command or the input file name.  The shortened version of
the original file continues to have the name specified by ‘@setfilename’
or the input file name.

   At one stage in writing this document, for example, the Info file was
saved as the file ‘test-texinfo’ and that file looked like this:

     Info file: test-texinfo,    -*-Text-*-
     produced by texinfo-format-buffer
     from file: new-texinfo-manual.texinfo

     ^_
     Indirect:
     test-texinfo-1: 102
     test-texinfo-2: 50422
     test-texinfo-3: 101300
     ^_^L
     Tag table:
     (Indirect)
     Node: overview^?104
     Node: info file^?1271
     Node: printed manual^?4853
     Node: conventions^?6855
     ...

(But ‘test-texinfo’ had far more nodes than are shown here.)  Each of
the split-off, indirect files, ‘test-texinfo-1’, ‘test-texinfo-2’, and
‘test-texinfo-3’, is listed in this file after the line that says
‘Indirect:’.  The tag table is listed after the line that says ‘Tag
table:’.

   In the list of indirect files, the number following the file name
records the cumulative number of bytes in the preceding indirect files,
not counting the file list itself, the tag table, or any permissions
text in the first file.  In the tag table, the number following the node
name records the location of the beginning of the node, in bytes from
the beginning of the (unsplit) output.

   If you are using ‘texinfo-format-buffer’ to create Info files, you
may want to run the ‘Info-validate’ command.  (The ‘texi2any’ command
does such a good job on its own, you do not need ‘Info-validate’.)
However, you cannot run the ‘M-x Info-validate’ node-checking command on
indirect files.  For information on how to prevent files from being
split with ‘texinfo-format-buffer’ and how to validate the structure of
the nodes, see Using Info-validate.

21.3 Info Format FAQ
====================

Here are some questions that have been frequently asked on the project
mailing lists and elsewhere.

Why when I run ‘info FOO’ do I get the same output as ‘man FOO’?

     Check that the Info manuals are installed.  Not all GNU/Linux
     distributions install all the Info manuals by default.  This is
     regrettable, as often the Info manual provides more information
     than the provided man page.

Why not use HTML instead of Info?

     Manuals are rarely written in the Info format itself, but are
     generated from Texinfo source by the ‘texi2any’ program.
     ‘texi2any’ can generate HTML as well as Info from Texinfo source.
     You can also access and download HTML manuals from the GNU website
     (<https://www.gnu.org/manual/manual.html>).  Additionally, some
     GNU/Linux distributions provide packages for the installation of
     HTML manuals.

     Info still has some advantages over HTML for locally installed
     documentation.  The Info browsers support index lookup and support
     for links between locally installed manuals in multiple locations.
     It's important to have documentation installed locally on your
     machine rather than relying on the Internet; this makes accessing
     documentation more reliable, and ensures it matches installed
     versions of packages.  It's hoped that support for browsing locally
     installed Texinfo documentation in some form of HTML can be
     improved in the future.

Why provide the command-line ‘info’ program when the Emacs Info reader is better?

     The Emacs Info reader can display images, and fully supports using
     a mouse.  There are not many differences among the Info readers
     besides that.  Command-line ‘info’ can be configured to change the
     default key bindings, as well as change the color of
     cross-references and search results, and to enable mouse scrolling
     support.  You should not need to be experienced with the Emacs
     editor to use ‘info’.  (Some recommend another program called
     ‘pinfo’, but this lacks in important features like index lookup.)

     Some prefer to be able to scroll through the entire manual at once
     (as happens with man pages), rather than being limited to a single
     'node' of content at once.  Of course, there is no accounting for
     taste, but a single, unstructured block of text becomes more
     awkward as a manual becomes longer and more complicated.  (However,
     if you really want to, you can view an info manual all at once in
     the ‘less’ pager with ‘info FOO | less’.)

Why do I have 'see' appearing in front of all of my links?

     By default, Emacs Info mode either changes the marker ‘*note’ for
     cross-references to 'see', or hides it completely.  Command-line
     ‘info’ does the same if ‘hide-note-references’ is set.
     Unfortunately, there is no way to do this reliably, as both the
     ‘@pxref’ and ‘@ref’ commands in Texinfo output this marker in the
     Info output, and the 'see' text is only appropriate for ‘@pxref’.

Yes, but how do I get a plain link, with no extra markup?

     You can't.  Info is a plain text format that is displayed mostly
     as-is in the viewers, and without the ‘*note’ text there would be
     nothing to mark text as a link.

     For output formats such as HTML, you can use the ‘@link’ command to
     produce a plain link.  See @link.  This does not produce a
     working cross-reference in Info output or in a printed copy of the
     manual, though.

Why do lines containing links appear mysteriously short?

     This due to Emacs (or ‘info’ with ‘hide-note-references’ set to
     ‘On’) hiding ‘*note’ strings, as mentioned above.

Can the Info format be extended to support fonts, colors or reflowable text?

     Any extension would be incompatible with existing Info-viewing
     programs.  Extra markup added to Info files would be displayed to
     the user, making files ugly and unreadable.

     When Texinfo files are processed into Info files, information about
     which Texinfo commands were used to markup text is lost.  Moreover,
     it is not possible to reliably detect whether text can be reflowed
     (e.g. a paragraph of prose), or whether line breaks should be kept
     (e.g. a code sample, or poem).

     Info's core purpose is to display documentation on text terminals.
     If you want more, you are recommended to use the HTML output from
     ‘texi2any’ instead.

22 Generating HTML
******************

‘texi2any’ generates Info output by default, but given the ‘--html’
option, it will generate HTML, for web browsers and other programs.
This chapter gives some details on such HTML output.

   ‘texi2any’ has many user-definable customization variables with which
you can influence the HTML output.  See HTML Output Customization.
In particular, there is support for syntax highlighting in ‘@example’
(see Syntax Highlighting).  You can also write so-called
“initialization files”, or “init files” for short, to modify almost
every aspect of HTML output.  Initialization files contain code and are
loaded by ‘--init-file’ (see Invoking texi2any).

   Some initialization files are maintained with Texinfo and installed
in the default case.  For example, ‘chm.pm’ produces the intermediate
compressed HTML Help format files that can be subsequently converted to
the CHM format.

   The documentation of ‘texi2any’ HTML output adaptation using
customization files is in a separate manual.  See texi2any_api.

22.1 HTML Translation
=====================

The HTML generated by ‘texi2any’ generates standard HTML output.  The
output is intentionally quite plain for maximum portability and
accessibility.

   You can customize the output via CSS (see HTML CSS) or other
means (see HTML Output Customization).  If you cannot accomplish a
reasonable customization, feel free to report that.

   *Navigation bar:* By default, a navigation bar is inserted at the
start of each node, analogous to Info output.  If the ‘--no-headers’
option is used, the navigation bar is only inserted at the beginning of
split files.  Header ‘<link>’ elements in split output support Info-like
navigation with browsers which implement this feature.

   *Raw HTML*: ‘texi2any’ will include segments of Texinfo source
between ‘@ifhtml’ and ‘@end ifhtml’ in the HTML output (but not any of
the other conditionals, by default).  Source between ‘@html’ and ‘@end
html’ is passed without change to the output (i.e., suppressing the
normal escaping of input ‘<’, ‘>’ and ‘&’ characters which have special
significance in HTML).  See Conditional Commands.

   *Standards*: It is intentionally not our goal, and not even always
possible, to pass through every conceivable validation test without any
diagnostics.  Different validation tests have different goals, often
about pedantic enforcement of some standard or another.  Our overriding
goal is to help users, not blindly comply with standards.

   Please report output from an error-free run of ‘texi2any’ which has
_practical_ browser or EPUB reader portability problems as a bug (see
Reporting Bugs).

   In practice, the HTML produced by ‘texi2any’ is slowly adjusted over
time towards the latest HTML standard, while also trying to keep
compatibility with earlier produced HTML. We use transitional markup and
try to be slow enough to give time for the diverse HTML readers to
adjust (and for standards to reincorporate useful features that were
dropped...).

22.2 HTML Splitting
===================

When splitting output at nodes (which is the default), ‘texi2any’ writes
HTML output into (basically) one output file per Texinfo source ‘@node’.

   Each output file name is the node name with spaces replaced by ‘-’'s
and special characters changed to ‘_’ followed by their code point in
hex (see HTML Xref).  This is to make it portable and easy to use as
a file name.  In the unusual case of two different nodes having the same
name after this treatment, they are written consecutively to the same
file, with HTML anchors so each can be referred to independently.

   If ‘texi2any’ is run on a system which does not distinguish case in
file names, nodes which are the same except for case (e.g., ‘index’ and
‘Index’) will also be folded into the same output file with anchors.
You can also pretend to be on a case insensitive filesystem by setting
the customization variable ‘CASE_INSENSITIVE_FILENAMES’.

   It is also possible to split at chapters or sections with ‘--split’
(see Splitting Output).  In that case, the file names are
constructed after the name of the node associated with the relevant
sectioning command.  Also, unless ‘--no-node-files’ is specified, a
redirection file is output for every node in order to more reliably
support cross-references to that manual (see HTML Xref).

   When splitting, the HTML output files are written into a
subdirectory.  The subdirectory name is derived from the base name (that
is, any extension is removed), with ‘_html’ appended.  For example, HTML
output for ‘gcc.texi’ would be written into a subdirectory named
‘gcc_html/’.  The subdirectory name is based on ‘@setfilename’ or on the
input file name (see Setting the Output File Name).

In any case, the top-level output file within the directory is always
named ‘index.html’.

   Monolithic output (‘--no-split’) is named according to
‘@setfilename’, if present (with any ‘.info’ extension replaced with
‘.html’), ‘--output’ (the argument is used literally), or based on the
input file name as a last resort (see Setting the Output File Name).

22.3 HTML CSS
=============

Cascading Style Sheets (CSS) is an Internet standard for influencing the
display of HTML documents: see <http://www.w3.org/Style/CSS/>.

   By default, some CSS code is included to better implement the
appearance of some Texinfo environments.  For example:

     pre.display { font-family:inherit }

   The above tells the web browser to use the same font as the main
document inside ‘<pre>’ elements used for ‘@display’ environments.  By
default, the HTML ‘<pre>’ command uses a monospaced font.

   Please see the reference above for a full explanation of CSS.

   You can influence the CSS in the HTML output with two ‘texi2any’
options: ‘--css-include=FILE’ and ‘--css-ref=URL’.

   The option ‘--css-ref=URL’ adds to each output HTML file a ‘<link>’
tag referencing a CSS at the given URL.  This allows using external
style sheets.

   The option ‘--css-include=FILE’ includes the contents FILE in the
HTML output, as you might expect.  However, the details are somewhat
tricky, as described in the following, to provide maximum flexibility.

   The CSS file first line may be a ‘@charset’ directive.  If present,
this directive is used to determine the encoding of the CSS file.  The
line is not copied into the output.

   The CSS file may begin with so-called ‘@import’ directives, which
link to external CSS specifications for browsers to use when
interpreting the document.  Again, a full description is beyond our
scope here, but we'll describe how they work syntactically, so we can
explain how they are handled.

   There can be more than one ‘@import’, but they have to come first in
the file, with only whitespace and comments interspersed, no normal
definitions.  Comments in CSS files are delimited by ‘/* ... */’, as in
C.  An ‘@import’ directive must be in one of these two forms:

     @import url(http://example.org/foo.css);
     @import "http://example.net/bar.css";

   The crucial characters are the ‘@’ at the beginning and the semicolon
terminating the directive.  When reading the CSS file, any such
‘@’-directive is simply copied into the output, as follows:

   • If FILE contains only normal CSS declarations, it is included after
     the default CSS, thus overriding it.

   • If FILE begins with ‘@import’ specifications (see below), then the
     ‘import’'s are included first (they have to come first, according
     to the standard), and then the default CSS is included.  If you
     need to override the default CSS from an ‘@import’, you can do so
     with the ‘! important’ CSS construct, as in:
          pre.example { font-size: inherit ! important }

   • If FILE contains both ‘@import’ and inline CSS specifications, the
     ‘@import’'s are included first, then default CSS, and lastly the
     inline CSS from FILE.

   • Any @-directive other than ‘@import’ and ‘@charset’ is treated as a
     CSS declaration, meaning the default CSS is included and then the
     rest of the file is prepended.

   If the CSS file is malformed or erroneous, the output is unspecified.
The meaning of the CSS file is not interpreted in any way; the special
‘@’ and ‘;’ characters are looked for the text is blindly copied into
the output.  Comments in the CSS file may or may not be included in the
output.

   By default, classes are added to the HTML elements and CSS rules for
these classes are output at the beginning of each HTML file.  Set the
‘NO_CSS’ customization variable to prevent classes being added and CSS
being used.  Set ‘INLINE_CSS_STYLE’ to have CSS code put in HTML
elements in the ‘style’ attribute rather than at the beginning of the
output.

   Since ‘texi2any’ only inserts CSS code needed by the HTML actually
output, the full list of CSS code potentially inserted is not visible in
the output document.  To get the full list of CSS rules, call ‘texi2any’
with the ‘SHOW_BUILTIN_CSS_RULES’ customization variable set to output
the built-in default CSS rules on the standard output and exit, like:
     texi2any -c SHOW_BUILTIN_CSS_RULES=1

22.4 ‘@documentdescription’: Summary Text
=========================================

When producing HTML output for a document, a ‘<meta>’ element is written
in the ‘<head>’ to give some idea of the content of the document.  By
default, this “description” is the title of the document, taken from the
‘@settitle’ command (see @settitle).  To change this, use the
‘@documentdescription’ environment, as in:

     @documentdescription
     descriptive text.
     @end documentdescription

This will produce the following output in the ‘<head>’ of the HTML:

     <meta name=description content="descriptive text.">

22.5 Generating EPUB
====================

EPUB is a format designed for reading electronic books on portable
devices.  ‘texi2any’ generated EPUB 3.3 in 2024.  An EPUB file is a ZIP
archive container, holding informative files as well as the manual
rendered in HTML.

   The generation of the EPUB file depends on the ‘Archive::Zip’ Perl
module being installed.  This dependency is checked at runtime.  By
default, trying to output EPUB without this dependency raises an error.
However, if the EPUB output file is not generated, with the
customization variable ‘EPUB_CREATE_CONTAINER_FILE’ set to 0, it is not
an error if ‘Archive::Zip’ is not installed.

   The ‘texi2any’ tests related to EPUB generation do not require the
installation of ‘Archive::Zip’, as they set ‘EPUB_CREATE_CONTAINER_FILE’
to 0 and keep the directory containing the files and directories needed
for the EPUB file by setting the ‘EPUB_KEEP_CONTAINER_FOLDER’
customization variable to 1.

22.5.1 Container Directory and Output Files
-------------------------------------------

A directory containing the files and directories needed for the EPUB
format is created when outputting EPUB.  The name of this container
directory is derived from the base name of the input file (that is, any
extension is removed), with ‘_epub_package’ postpended.  If an output
directory is specified, with ‘--output’, or with the ‘SUBDIR’
customization variable, the container directory is created in that
directory instead of the current directory.  At the beginning of a new
run, the container directory and all its contents are removed.  The
container directory is also removed after the final EPUB file has been
generated in the default case.

   The HTML files produced from the Texinfo manual are output in
subdirectories of the container directory.  Image files referred to from
the Texinfo manual, if found, are copied to subdirectories of the
container directory.

   The EPUB output file is a ZIP archive of the container directory.
The file name is derived from the base name, with the ‘.epub’ extension
postpended.  If an output file is specified, with ‘--output’, or with
the ‘OUTFILE’ customization function, this file name is used instead.
The output EPUB file is never placed in the directory specified by
‘--output’ or ‘SUBDIR’; only the container directory is placed there, as
explained just above.

   The EPUB output file is not generated if the customization variable
‘EPUB_CREATE_CONTAINER_FILE’ is set to 0.  The container directory is
left after the final EPUB file has been generated if
‘EPUB_KEEP_CONTAINER_FOLDER’ is set.

   See Invoking texi2any.

22.5.2 EPUB Cross-References
----------------------------

The EPUB format does not support references from an EPUB file to another
EPUB file.  Therefore any references to "external" Texinfo manuals
should resolve to an external URL. ‘texi2any’ produces these links with
HTML cross-reference configuration (see HTML Xref Configuration).
Since the links in the resulting EPUB are incorrect if no information is
found for the cross-references, ‘texi2any’ issues a warning by default
for missing cross-references information.  If these warnings are
unwanted, set ‘CHECK_HTMLXREF’ to 0.

22.5.3 Achieving strict EPUB conformance
----------------------------------------

By default, ‘texi2any’ produces EPUB expected by conformance checkers as
far as possible.  You may still need to adjust your Texinfo manual to
achieve full conformance to:
   • Make sure that references to external manuals resolve to URLs
     (see EPUB Cross-References).
   • Avoid Texinfo code more forgiving than XHTML. In general valid
     Texinfo is converted to valid XHTML, but there are exceptions.  For
     example, you should avoid nested references and nested sectioning
     commands and references, content before ‘@table’ first ‘@item’ and
     omitting the second column of ‘@table’ ‘@item’.
   • Remove spaces in Texinfo input file names.
   • Remove form feeds that end up in output.

22.5.4 HTML Generated for EPUB
------------------------------

The HTML generated for EPUB is XHTML conformant, UTF-8 encoded, and
formatted without the usual HTML navigation headers and footers.

   ‘texi2any’ achieves this internally by setting customization
variables, such as ‘USE_XML_SYNTAX’, ‘HEADERS’ or
‘OUTPUT_ENCODING_NAME’.  Some features of printed output are used in
EPUB.  In particular, the Top node does not appear in the EPUB output,
while a title page is generated.  This is obtained by setting
‘NO_TOP_NODE_OUTPUT’.  See HTML Output Customization.

   The ‘OUTFILE’ and ‘SUBDIR’ customization variables values correspond
initially to the EPUB directory container and/or the EPUB output file
(see EPUB Output File and Directory).  These customization variables
values are undefined or reset to the locations in the container
directory where the XHTML files are output for the HTML generation.

   This use of customization variables by ‘texi2any’ is mentioned here
because resetting such variables is unusual; however, the variables
reset are used internally for the conversion, and should not interact
with any customization set by the user.

22.6 Code Examples Syntax Highlighting in HTML
==============================================

You can use the ‘HIGHLIGHT_SYNTAX’ variable for syntax highlighting of
source code in ‘@example’ blocks for the HTML output, with the help of
external software.  You can set ‘HIGHLIGHT_SYNTAX’ to one of several
special values:

‘highlight’
     Use ‘highlight’ from
     <http://www.andre-simon.de/doku/highlight/en/highlight.php>.
‘pygments’
     Use ‘pygmentize’ from <https://pygments.org/>.
‘source-highlight’
     Use ‘source-highlight’ (see source-highlight).

   The first argument on an ‘@example’ line (see @example) gives the
name of the language used for syntax highlighting.  ‘@example’ blocks
without such an argument are only highlighted if
‘HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE’ if set, which variable gives the
language to use for highlighting such blocks.

   If you use a value for ‘HIGHLIGHT_SYNTAX’ that is not listed above,
it is a template for a command line that is executed to highlight code.
This gives you more control over the exact command-line options used for
the highlighting program, and allows you use other programs than those
listed above.  In this template, the name of the highlighted language is
substituted for occurrences of ‘%l’, and ‘%’ is substituted for ‘%%’.
‘texi2any’ passes the content of each ‘@example’ block (converted to
simple text) on standard input, and the highlighted HTML is read from
the standard output.

   For example, if you set ‘HIGHLIGHT_SYNTAX’ to ‘colorcode -l=%l’ and
there is an ‘@example C++’ block in the document, the ‘colorcode -l=C++’
command line is executed with the ‘@example’ block passed to the
standard input of the executed command, and the result is read from the
standard output of the executed command.

22.7 HTML Cross-references
==========================

Cross-references between Texinfo manuals in HTML format become standard
HTML ‘<a>’ links.  This section describes the algorithm used, so that
Texinfo can cooperate with other programs, such as ‘texi2html’, by
writing mutually compatible HTML files.

   This algorithm may or may not be used for links _within_ HTML output
for a Texinfo file.  Since no issues of compatibility arise in such
cases, we do not need to specify this.

   We try to support references to such "external" manuals in both
monolithic and split forms.  A “monolithic” (mono) manual is entirely
contained in one file, and a “split” manual has a file for each node.
(see HTML Splitting.)

   The algorithm was primarily devised by Patrice Dumas in 2003-04.