This manual is for GNU Texinfo (version 6.8, 8 June 2021), a
documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

   Copyright (C) 1988, 1990-1993, 1995-1999, 2001-2021 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, with no Front-Cover Texts,
     and with no Back-Cover Texts. A copy of the license is included in
     the section entitled "GNU Free Documentation License".

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

Use doubled single-quote characters to begin and end quotations:
``...''.  TeX converts two single quotes to left- and right-hand doubled
quotation marks, and Info converts doubled single-quote characters to
ASCII double quotes: ``...'' becomes "...".

   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.

   In order to get the symbols for the quotation marks in encoded Info
output, it is necessary to specify '@documentencoding UTF-8'.  (see
@documentencoding.)  Double guillemets are also present in ISO 8859-1
(aka Latin 1) and ISO 8859-15 (aka Latin 9).

   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.

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).

   Traditions for quotation mark usage vary to a great extent between
languages (<http://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 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 (TeX, 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 '@math' and '@displaymath': Formatting Mathematics
=======================================================

You can write a short mathematical expression with the '@math' command.
Write the mathematical expression between braces, like this:

     @math{\sin 2\pi \equiv \cos 3\pi}

which looks like this:
     \sin 2\pi \equiv \cos 3\pi

   The '@math' command has no special effect on the Info output or (by
default) the HTML output, merely outputting the contents verbatim.

   For the TeX output, '@math' switches into math mode.  This allows you
to use all the plain TeX math control sequences for symbols, functions,
and so on, starting with '\'.  It's best to use '\' instead of '@' for
any such mathematical commands; otherwise, 'texi2any' will complain.

   By default, the HTML output is only enclosed by '<em>'.  'texi2any'
provides three options for displaying properly formatted mathematics for
HTML. You can select these with the 'HTML_MATH' variable (see HTML Customization Variables).
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 and
latex2html 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}

   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.  In
general, the contents of '@math' or '@displaymath' should be plain TeX
only, with no interspersed Texinfo commands.

   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 with any of the 'HTML_MATH' options).

11.8 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 'makeinfo' is concerned, but TeX is not so lucky.

11.8.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
Info, 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 Info, the result is just 'LaTeX'.  (LaTeX is another
macro package built on top of TeX, very loosely analogous to Texinfo in
that it emphasizes logical structure, but much (much) larger.)

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

11.8.2 '@copyright{}' ((C))
---------------------------

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

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

11.8.3 '@registeredsymbol{}' ((R))
----------------------------------

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

11.8.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 would work for the Info file
output, but would produce the wrong amount of space between the periods
in the printed manual.

   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.8.5 '@bullet' (*)
--------------------

Use the '@bullet{}' command to generate a large round dot, or the
closest possible thing to one.  In Info, an asterisk is used.  Here is a
bullet: *

   When you use '@bullet' in '@itemize', you do not need to type the
braces, because '@itemize' supplies them.  (see @itemize).

11.8.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.

   Texinfo cannot magically synthesize support for the Euro symbol where
the underlying system (fonts, software, whatever) does not support it.
Therefore, you may find it preferable to use the word "Euro".  (In
banking contexts, the abbreviation for the Euro is EUR.)

   In order to get the Euro symbol in encoded Info output, for example,
it is necessary to specify '@documentencoding ISO-8859-15' or
'@documentencoding UTF-8' (see @documentencoding.)  The Euro symbol
is in ISO 8859-15 (aka Latin 9), and is _not_ in the more widely-used
ISO 8859-1 (Latin 1).

   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.8.7 '@pounds' (£): Pounds Sterling
-------------------------------------

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

11.8.8 '@textdegree' (°): Degrees Symbol
----------------------------------------

Use the '@textdegree{}' command to generate '°'.  Where possible, this
is the normal symbol for degrees.  Otherwise, it is an 'o'.

11.8.9 '@minus' (-): Inserting a Minus Sign
-------------------------------------------

Use the '@minus{}' command to generate a minus sign.  In a fixed-width
font, this is a single hyphen, but in a proportional font, 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.

In the fixed-width font used by Info, '@minus{}' is the same as a
hyphen.

   You should not use '@minus{}' inside '@code' or '@example' because
the width distinction is not made in the fixed-width font they use.

   When you use '@minus' to specify the mark beginning each entry in an
itemized list, you do not need to type the braces (see @itemize).

   If you actually want to typeset some math that does a subtraction, it
is better to use '@math'.  Then the regular '-' character produces a
minus sign, as in '@math{a-b}' (see Inserting Math).

11.8.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.9 Glyphs for Programming
===========================

In Texinfo, code is often illustrated in examples that are delimited by
'@example' and '@end example', or by '@lisp' and '@end lisp'.  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.9.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.9.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.9.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

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

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.9.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:

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

11.9.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,

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

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.9.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,

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

produces

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

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

11.9.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.9.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 by default; this glyph is
also available independently via the command '@arrow{}'.

   You can change the glyph produced by '@click' with the command
'@clickstyle', which takes a command name as its single argument on the
rest of the line, much like '@itemize' and friends (see @itemize).
The command should produce a glyph, and the usual empty braces '{}' are
omitted.  Here's an example:

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

now produces:

     ... File => Open ...

11.10 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.  (see
@documentencoding.)

   In HTML, XML, 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 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.

12.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.

12.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 format.

12.3 '@-' and '@hyphenation': Helping TeX Hyphenate
===================================================

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
help TeX out.  Texinfo supports two commands for this:

'@-'
     Insert a discretionary hyphen, i.e., a place where TeX can (but
     does not have to) hyphenate.  This is especially useful when you
     notice 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}'
     Tell TeX how to hyphenate HY-PHEN-A-TED WORDS.  As shown, you put a
     '-' at each hyphenation point.  For example:
          @hyphenation{man-u-script man-u-scripts}
     TeX only uses the specified hyphenation points when the words match
     exactly, so give all necessary variants, such as plurals.

   Info, HTML, and other non-TeX output is not hyphenated, so none of
these commands have any effect there.

12.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 HTML and TeX output.

12.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.

   You can also use the '@w' command to prevent TeX from automatically
hyphenating a long name or phrase that happens to fall near the end of a
line.  'makeinfo' does not ever hyphenate words.

   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 in Info or plain text
output, though.

12.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').

12.7 '@sp' N: Insert Blank Lines
================================

A line beginning with and containing only '@sp N' generates N blank
lines of space in both the printed manual and the Info file.  '@sp' also
forces a paragraph break.  For example,

     @sp 2

generates two blank lines.

   The '@sp' command is most often used in the title page.

12.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 the '@titlepage' section
of a Texinfo file to start the copyright page.

12.9 '@group': Prevent Page Breaks
==================================

The '@group' command (on a line by itself) is used inside an '@example'
or similar construct to begin an unsplittable vertical group, which will
appear entirely on one page in the printed output.  The group is
terminated by a line containing only '@end group'.  These two lines
produce no output of their own, and in the Info file output they have no
effect at all.

   Although '@group' would make sense conceptually in a wide variety of
contexts, its current implementation works reliably 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.)  In other contexts, '@group' can cause anomalous vertical
spacing.

   This formatting requirement means that you should write:

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

with the '@group' and '@end group' commands inside the '@example' and
'@end example' commands.

   The '@group' command is most often used to hold an example together
on one page.  In this Texinfo manual, more than 100 examples contain
text that is enclosed between '@group' and '@end group'.

   If you forget to end a group, you may get strange and unfathomable
error messages when you run TeX.  This is because TeX keeps trying to
put the rest of the Texinfo file onto the one page and does not start to
generate error messages until it has processed considerable text.  It is
a good rule of thumb to look for a missing '@end group' if you get
incomprehensible error messages in TeX.

12.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 tells TeX to
start a new page 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.

13 Definition Commands
**********************

The '@deffn' command and the other "definition commands" enable you to
describe functions, variables, macros, commands, user options, special
forms and other such artifacts in a uniform format.

   In the Info file, a definition causes the entity
category--'Function', 'Variable', or whatever--to appear at the
beginning of the first line of the definition, followed by the entity's
name and arguments.  In the printed manual, the command causes TeX to
print the entity's name and its arguments on the left margin and print
the category next to the right margin.  In both output formats, the body
of the definition is indented.  Also, the name of the entity is entered
into the appropriate index: '@deffn' enters the name into the index of
functions, '@defvr' enters it into the index of variables, and so on
(see Predefined Indices).

   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.

13.1 The Template for a Definition
==================================

The '@deffn' command is used for definitions of entities that resemble
functions.  To write a definition using the '@deffn' command, 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.  (You may embed examples in the body.)  Finally, end
the definition with an '@end deffn' command written on a line of its
own.

   The other definition commands follow the same format: a line with the
'@def...' command and whatever arguments are appropriate for that
command; the body of the definition; and a corresponding '@end' line.

   The template for a definition looks like this:

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

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.

   Some of the definition commands are more general than others.  The
'@deffn' command, for example, is the general definition command for
functions and the like--for entities that may take arguments.  When you
use this command, you specify the category to which the entity belongs.
Three predefined, specialized variations ('@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.

   See Sample Function Definition, for a detailed example of a
function definition, including the use of '@example' inside the
definition.

13.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).

13.3 Optional and Repeated Arguments
====================================

Some entities take optional or repeated arguments, conventionally
specified by using 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 '@defspec' 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{}

The function is listed in the Command and Variable Index under 'foobar'.

13.4 '@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'.  The
'@deffnx' command works exactly like '@deffn' except that it does not
generate extra vertical white space between it and the preceding line.

   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).

13.5 The Definition Commands
============================

Texinfo provides more than a dozen definition commands, all of which are
described in this section.

   The definition commands automatically enter the name of the entity in
the appropriate index: for example, '@deffn', '@defun', and '@defmac'
enter function names in the index of functions; '@defvr' and '@defvar'
enter variable names in the index of variables.

   Although the examples that follow mostly illustrate Lisp, the
commands can be used for other programming languages.

13.5.1 Functions and Similar Entities
-------------------------------------

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

'@deffn CATEGORY NAME ARGUMENTS...'
     The '@deffn' command is the general definition command for
     functions, interactive commands, and similar entities that may take
     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.

     '@deffn' prints argument names such as NCHARS in slanted type in
     the printed output, because we think of these names as
     metasyntactic variables--they stand for the actual argument values.
     Within the text of the description, however, 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.

     The template for '@deffn' is:

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

'@defun NAME ARGUMENTS...'
     The '@defun' command is the definition command for functions.
     '@defun' is equivalent to '@deffn Function ...'.  Terminate the
     definition with '@end defun' on a line of its own.  Thus, the
     template is:

          @defun FUNCTION-NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end defun

'@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.

13.5.2 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.

     The template is:

          @defvr CATEGORY NAME
          BODY-OF-DEFINITION
          @end defvr

     '@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

     The template is:

          @defvar NAME
          BODY-OF-DEFINITION
          @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} ...' and works like '@defvar'.
     It creates an entry in the index of variables.

13.5.3 Functions in Typed Languages
-----------------------------------

The '@deftypefn' command and its variations are for describing functions
in 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 are
     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, the type of 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').

     Since in typed languages, the actual names of the arguments are
     typically scattered among data type names and keywords, Texinfo
     cannot find them without help.  You can either (a) write everything
     as straight text, and it will be printed in slanted type; (b) use
     '@var' for the variable names, which will uppercase the variable
     names in Info and use the slanted typewriter font in printed
     output; (c) use '@var' for the variable names and '@code' for the
     type names and keywords, which will be dutifully obeyed.

     The template for '@deftypefn' is:

          @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
          BODY-OF-DESCRIPTION
          @end deftypefn

     Note that if the CATEGORY or DATA TYPE is more than one word then
     it must be enclosed in braces to make it a single argument.

     If you are describing a procedure in a language that has packages,
     such as Ada, you might consider using '@deftypefn' in a manner
     somewhat contrary to the convention described in the preceding
     paragraphs.  For example:

          @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.)

     '@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 in typed languages.  The command is equivalent to
     '@deftypefn Function ...'.  The template is:

          @deftypefun TYPE NAME ARGUMENTS...
          BODY-OF-DESCRIPTION
          @end deftypefun

     '@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
is to put the return type on a line by itself.  So Texinfo provides an
option to do that: '@deftypefnnewline on'.

   This affects typed functions only--not untyped functions, 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.

13.5.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
               ...

     The template is:

          @deftypevr CATEGORY DATA-TYPE NAME
          BODY-OF-DESCRIPTION
          @end deftypevr

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

          @deftypevar DATA-TYPE NAME
          BODY-OF-DESCRIPTION
          @end deftypevar

   These commands create entries in the index of variables.

13.5.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

     The template is:

          @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
          BODY-OF-DEFINITION
          @end deftp

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

13.5.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.

13.5.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.  Ordinarily, the data type is a
     programming language construct that should be marked with '@code'.
     For instance:

          @deftypecv {Class Option} Window @code{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.  Ordinarily, the data
     type is a programming language construct that should be marked with
     '@code'.  For instance:

          @deftypeivar Window @code{int} border-pattern
          ...
          @end deftypeivar

     produces:

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

     '@deftypeivar' creates an entry in the index of variables.

13.5.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 general definition command for these
     method-like entities.

     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.

     The template is:
          @defop CATEGORY CLASS NAME ARGUMENTS...
          BODY-OF-DEFINITION
          @end defop

     '@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 definition command for typed
     operations in object-oriented programming.  It is similar to
     '@defop' with the addition of the DATA-TYPE parameter to specify
     the return type of the method.  '@deftypeop' creates an entry in
     the index of functions.

'@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 typed languages, such as C++ and Java.  It is
     similar to the '@defmethod' command with the addition of the
     DATA-TYPE parameter to specify the return type of the method.
     '@deftypemethod' creates an entry in the index of functions.

   The typed commands are affected by the '@deftypefnnewline' option
(see Functions in Typed Languages).

13.6 Conventions for Writing Definitions
========================================

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.

13.7 A Sample Function Definition
=================================

A function definition uses the '@defun' and '@end defun' commands.  The
name of the function follows immediately after the '@defun' command and
it is followed, on the same line, by the parameter list.

   Here is a definition from Calling Functions (elisp).

      -- 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 looks like this:

     @defun apply function &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 and Variable
Index under 'apply'.

   Ordinary variables and user options are described using a format like
that for functions except that variables do not take arguments.

14 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.

14.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 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.  If the command is not used at all, the
default is 'en_US' for US English.

   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).

   For Info and other online output, 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.  Some strings, such as "Node:",
"Next:", "Menu:", etc., are keywords in Info output, so are not
translated there; they are translated in other output formats.

   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).

   In September 2006, the W3C Internationalization Activity released a
new recommendation for specifying languages:
<http://www.rfc-editor.org/rfc/bcp/bcp47.txt>.  When Gettext supports
this new scheme, Texinfo will too.

   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
<http://en.wikipedia.org/wiki/ISO_3166>.

14.2 '@documentencoding ENC': Set Input Encoding
================================================

The '@documentencoding' command declares the input document encoding,
and can also affect the encoding of the output.  Write it on a line by
itself, with a valid encoding specification following, near the
beginning of the file.

     @documentencoding ENC

   Texinfo supports these encodings:

'US-ASCII'
     This has no particular effect, but it's included for completeness.

'UTF-8'
     The vast global character encoding, expressed in 8-bit bytes.

'ISO-8859-1'
'ISO-8859-15'
'ISO-8859-2'
     These specify the 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 is the commonly used encoding for the Russian language.

'koi8-u'
     This is the commonly used encoding for the Ukrainian language.

   Specifying an encoding ENC has the following effects:

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

     Local Variables:
     coding: ENC
     End:

   Also, in Info and plain text output, unless the option
'--disable-encoding' is given to 'makeinfo', accent constructs and
special characters, such as '@'e', are output as the actual 8-bit or
UTF-8 character in the given encoding where possible.

   In HTML output, a '<meta>' tag is output, in the '<head>' section of
the HTML, that specifies ENC.  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=ENC">

   In XML and DocBook output, UTF-8 is always used for the output,
according to the conventions of those formats.

   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.  (Our
plan to support other scripts is to create a LaTeX back-end to
'texi2any', where the support is already present.)

   For maximum portability of Texinfo documents across the many
different user environments in the world, we recommend sticking to 7-bit
ASCII in the input unless your particular manual needs a substantial
amount of non-ASCII, e.g., it's written in German.  You can use the '@U'
command to insert an occasional needed character (see Inserting Unicode).

15 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.

15.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 by TeX when
it typesets the printed manual, and by 'makeinfo' when not producing
Info 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.

'@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
     @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.

15.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
     @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).

15.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 '@ifhtml ... @end ifhtml' to delimit Texinfo
source to be included in HTML output only, and '@html ... @end html' for
a region of raw HTML.

   Likewise, you can use '@ifxml ... @end ifxml' to delimit Texinfo
source to be included in XML output only, and '@xml ... @end xml' for a
region of raw XML.  Regions of raw text in other formats will also be
present in the XML output, but with protection of XML characters and
within corresponding elements.  For example, the raw HTML text:

     @html
     <br />
     @end html

will be included in the XML output as:

     <html>
     &lt;br /&gt;
     </html>

   Again likewise, you can use '@ifdocbook ... @end ifdocbook' to
delimit Texinfo source to be included in DocBook output only, and
'@docbook ... @end docbook' for a region of raw DocBook.

   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.  Use the raw formatter commands
for their intended purpose, of providing material directly in the
underlying format.  When you simply want to give different Texinfo
specifications for different output formats, use the '@if...'
conditionals and stay in Texinfo syntax.

15.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  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.

15.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 are brief descriptions of these commands, see the following
sections for more details:

'@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'.

15.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.  However, unlike most other commands which take the rest of
the line as a value, '@set' need not appear at the beginning of a line.

   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 formatters then replace a '@value{FLAG}' command with the
string to which FLAG is set.  Thus, when 'foo' is set as shown above,
the Texinfo formatters 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 formatters transform

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

   If you write

     @clear howmuch

then the formatters 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}

15.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 either printed or Info 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; in both printed and
Info output, 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

15.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.

15.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:

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

     (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.

15.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 'makeinfo'
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
(<http://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)).

15.7 Conditional Nesting
========================

Conditionals can be nested; however, the details are a little tricky.
The difficulty comes with failing conditionals, such as '@ifhtml' when
HTML is not being produced, where the included text is to be ignored.
However, it is not to be _completely_ ignored, since it is useful to
have one '@ifset' inside another, for example--that is a way to include
text only if two conditions are met.  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

   Technically, Texinfo requires that for a failing conditional, the
ignored text must be properly nested with respect to that failing
conditional.  Unfortunately, it's not always feasible to check that
_all_ conditionals are properly nested, because then the processors
could have to fully interpret the ignored text, which defeats the
purpose of the command.  Here's an example illustrating these rules:

     @ifset a
     @ifset b
     @ifclear ok  - ok, ignored
     @end junky   - ok, ignored
     @end ifset
     @c WRONG - missing @end ifset.

   Finally, as mentioned above, all conditional commands must be on
lines by themselves, with no text (even spaces) before or after.
Otherwise, the processors cannot reliably determine which commands to
consider for nesting purposes.

16 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).

   * '@alias' is a convenient way to define a new name for an existing
     command.

   * '@definfoenclose' allows you to define new commands with customized
     output for all non-TeX output formats.

   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).

16.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).

   For a macro to work consistently with TeX, MACRONAME must consist
entirely of letters: no digits, hyphens, underscores, or other special
characters.  So, we recommend using only letters.  However, 'makeinfo'
will accept anything consisting 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).

   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

16.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.
For 'makeinfo', 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, 'makeinfo' implements two rules for "automatic quoting" in
some circumstances:

  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, 'makeinfo' does not control 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.

   'makeinfo' 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.

16.3 Macro Details and Caveats
==============================

By design, macro expansion does not happen in the following contexts in
'makeinfo':

   * '@macro' and '@unmacro' lines;

   * '@if...' lines, including '@ifset' and similar;

   * '@set', '@clear', '@value';

   * '@clickstyle' lines;

   * '@end' lines.

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 'makeinfo' 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.

   * 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

   * 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).

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

   * Likewise, 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.  For example,

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

     produces:

          François+.

   * Ending a macro body with '@c' may cause text following the macro
     invocation to be ignored as a comment in 'makeinfo'.  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').

   * 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 'makeinfo' implementation also has the following limitations (by
design):

   * '@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 'makeinfo', 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

16.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.

   'makeinfo' will accept the same identifiers for aliases as it does
for macro names, that is, alphanumerics and (except as the first
character) '-'.

16.5 '@definfoenclose': Customized Highlighting
===============================================

An '@definfoenclose' command may be used to define a highlighting
command for all the non-TeX 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
formatting command that inserts '//' before and '\\' after the argument
to '@phoo'.  You can then write '@phoo{bar}' wherever you want '//bar\\'
highlighted in Info.

   For TeX formatting, you could write

     @iftex
     @global@let@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 everything else.  The raw TeX commands need to be in '@iftex'.
'@definfoenclose' command need not be within '@ifinfo' unless you want
to use different definitions for different output formats.

   Here is another example: write

     @definfoenclose headword, , :

near the beginning of the file, to define '@headword' as an Info
formatting command that inserts nothing before and a colon after the
argument to '@headword'.

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

16.6 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.

16.6.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 'makeinfo' program recognizes these lines by default, except
within '@verbatim' blocks (see @verbatim).  Their recognition can be
turned off completely with 'CPP_LINE_DIRECTIVES' (see Other 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.

16.6.2 '#line' and TeX
----------------------

As mentioned, 'makeinfo' 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 'makeinfo''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 'makeinfo'
     first to expand macros and eliminate '#line'.

   * If you run 'makeinfo' or its variants (see Generic Translator 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 'makeinfo --dvi --Xopt -E'.  (Or '--pdf' instead of
     '--dvi'.)  'makeinfo' 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.  This is another
example of why we recommend running 'makeinfo' for the best diagnostics
(see makeinfo Advantages).

16.6.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).

17 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.

17.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

   @-commands are expanded in file names.  The one most likely to be
useful is '@value' (see @set @value), and even then only in
complicated situations.

   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.

17.2 'texinfo-multiple-files-update'
====================================

GNU Emacs Texinfo mode provides the 'texinfo-multiple-files-update'
command.  This command creates or updates 'Next', 'Previous', and 'Up'
pointers of included files as well as those in the outer or overall
Texinfo file, and it creates or updates a main menu in the outer file.
Depending on whether you call it with optional arguments, the command
updates only the pointers in the first '@node' line of the included
files or all of them:

'M-x texinfo-multiple-files-update'
     Called without any arguments:

        - Create or update the 'Next', 'Previous', and 'Up' pointers of
          the first '@node' line in each file included in an outer or
          overall Texinfo file.

        - Create or update the 'Top' level node pointers of the outer or
          overall file.

        - Create or update a main menu in the outer file.

'C-u M-x texinfo-multiple-files-update'
     Called with 'C-u' as a prefix argument:

        - Create or update pointers in the first '@node' line in each
          included file.

        - Create or update the 'Top' level node pointers of the outer
          file.

        - Create and insert a master menu in the outer file.  The master
          menu is made from all the menus in all the included files.

'C-u 8 M-x texinfo-multiple-files-update'
     Called with a numeric prefix argument, such as 'C-u 8':

        - Create or update _all_ the 'Next', 'Previous', and 'Up'
          pointers of all the included files.

        - Create or update _all_ the menus of all the included files.

        - Create or update the 'Top' level node pointers of the outer or
          overall file.

        - And then create a master menu in the outer file.  This is
          similar to invoking 'texinfo-master-menu' with an argument
          when you are working with just one file.

   Note the use of the prefix argument in interactive use: with a
regular prefix argument, just 'C-u', the 'texinfo-multiple-files-update'
command inserts a master menu; with a numeric prefix argument, such as
'C-u 8', the command updates _every_ pointer and menu in _all_ the files
and then inserts a master menu.

17.3 Include Files Requirements
===============================

If you plan to use the 'texinfo-multiple-files-update' command, the
outer Texinfo file that lists included files within it should contain
nothing but the beginning and end parts of a Texinfo file, and a number
of '@include' commands listing the included files.  It should not even
include indices, which should be listed in an included file of their
own.

   Moreover, each of the included files must contain exactly one highest
level node (conventionally, '@chapter' or equivalent), and this node
must be the first node in the included file.  Furthermore, each of these
highest level nodes in each included file must be at the same
hierarchical level in the file structure.  Usually, each is a
'@chapter', an '@appendix', or an '@unnumbered' node.  Thus, normally,
each included file contains one, and only one, chapter or
equivalent-level node.

   The outer file should contain only _one_ node, the 'Top' node.  It
should _not_ contain any nodes besides the single 'Top' node.  The
'texinfo-multiple-files-update' command will not process them.

17.4 Sample File with '@include'
================================

Here is an example of an outer Texinfo file with '@include' files within
it before running 'texinfo-multiple-files-update', which would insert a
main or master menu:

     \input texinfo @c -*-texinfo-*-
     @settitle Include Example

     ... See Sample Texinfo Files, for
     examples of the rest of the frontmatter ...

     @ifnottex
     @node Top
     @top Include Example
     @end ifnottex

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

   An included file, such as 'foo.texinfo', might look like this:

     @node First
     @chapter First Chapter

     Contents of first chapter ...

   The full contents of 'concept-index.texinfo' 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 contains a master menu
with 417 entries and a list of 41 '@include' files.

17.5 '@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).

   The name of the file is taken literally, with a single exception:
'@value{VAR}' references are expanded.  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.)

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

18 Formatting and Printing Hardcopy
***********************************

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, three major shell commands are used to print
formatted output from a Texinfo manual: one converts the Texinfo source
into something printable, a second sorts indices, and a third actually
prints the formatted document.  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).

   If you are using GNU Emacs, you can use commands provided by Texinfo
mode instead of shell commands.  In addition to the three commands to
format a file, sort the indices, and print the result, Texinfo mode
offers key bindings for commands to recenter the output buffer, show the
print queue, and delete a job from the print queue.

   In the United States, documents are most often printed on 8.5 inch by
11 inch pages (216mm by 280mm); this is the default size.  But you can
also print for 7 inch by 9.25 inch pages (178mm by 235mm, the
'@smallbook' size; or on A4 or A5 size paper ('@afourpaper',
'@afivepaper').  See @smallbook, and A4 Paper.

   Details are in the following sections.

18.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>.

18.2 Format with 'texi2dvi'
===========================

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.

   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 (see PDF Output), 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 'makeinfo' instead of the TeX implementation
(see Macro Details).  Each implementation has its own limitations
and advantages.  If this option is used, no line in the source file may
begin with the string '@c _texi2dvi' or the string '@c (_texi2dvi)'.

   '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' (or 'pdfetex') 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.  (These
days, 'pdftex' and 'pdfetex' are exactly the same, but we still run
'pdfetex' to cater to ancient TeX installations.)

   '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.

18.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.

18.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 'makeinfo', 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.

18.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
(<http://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.

18.4 Print with 'lpr' from Shell
================================

The way to print a DVI file depends on your system installation.  Two
common ones are 'dvips foo.dvi -o' to make a PostScript file first and
then print that, and 'lpr -d foo.dvi' to print a DVI file directly.

   For example, the following commands will (probably) suffice to sort
the indices, format, and print this manual using the 'texi2dvi' shell
script (see Format with texi2dvi).

     texi2dvi texinfo.texi
     dvips texinfo.dvi -o
     lpr texinfo.ps

   Depending on the 'lpr' setup on your machine, you might be able to
combine the last two steps into 'lpr -d texinfo.dvi'.

   You can also generate a PDF file by running 'texi2pdf' instead of
'texi2dvi'; a PDF is often directly printable.  Or you can generate a
PCL file by using 'dvilj' instead of 'dvips', if you have a printer that
prefers that format.

   'lpr' is a standard program on Unix systems, but it is usually absent
on MS-DOS/MS-Windows.  If so, just create a PostScript or PDF or PCL
file, whatever is most convenient, and print that in the usual way for
your machine (e.g., by sending to the appropriate port, usually 'PRN').

18.5 Printing From an Emacs Shell
=================================

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)).  In this shell, you can
format and print the document.  See Format and Print Hardcopy,
for details.

   You can switch to and from the shell buffer while 'tex' is running
and do other editing.  If you are formatting a long document on a slow
machine, this can be very convenient.

   For example, you can use 'texi2dvi' from an Emacs shell.  Here is one
way to use 'texi2pdf' to format and print 'Using and Porting GNU CC'
from a shell within Emacs:

     texi2pdf gcc.texi
     lpr gcc.pdf

   See the next section for more information about formatting and
printing in Texinfo mode.

18.6 Formatting and Printing in Texinfo Mode
============================================

Texinfo mode provides several predefined key commands for TeX formatting
and printing.  These include commands for sorting indices, looking at
the printer queue, killing the formatting job, and recentering the
display of the buffer in which the operations occur.

'C-c C-t C-b'
'M-x texinfo-tex-buffer'
     Run 'texi2dvi' on the current buffer.

'C-c C-t C-r'
'M-x texinfo-tex-region'
     Run TeX on the current region.

'C-c C-t C-i'
'M-x texinfo-texindex'
     Sort the indices of a Texinfo file formatted with
     'texinfo-tex-region'.

'C-c C-t C-p'
'M-x texinfo-tex-print'
     Print a DVI file that was made with 'texinfo-tex-region' or
     'texinfo-tex-buffer'.

'C-c C-t C-q'
'M-x tex-show-print-queue'
     Show the print queue.

'C-c C-t C-d'
'M-x texinfo-delete-from-print-queue'
     Delete a job from the print queue; you will be prompted for the job
     number shown by a preceding 'C-c C-t C-q' command
     ('texinfo-show-tex-print-queue').

'C-c C-t C-k'
'M-x tex-kill-job'
     Kill the currently running TeX job started by either
     'texinfo-tex-region' or 'texinfo-tex-buffer', or any other process
     running in the Texinfo shell buffer.

'C-c C-t C-x'
'M-x texinfo-quit-job'
     Quit a TeX formatting job that has stopped because of an error by
     sending an <x> to it.  When you do this, TeX preserves a record of
     what it did in a '.log' file.

'C-c C-t C-l'
'M-x tex-recenter-output-buffer'
     Redisplay the shell buffer in which the TeX printing and formatting
     commands are run to show its most recent output.

   Thus, the usual sequence of commands for formatting a buffer is as
follows (with comments to the right):

     C-c C-t C-b             Run 'texi2dvi' on the buffer.
     C-c C-t C-p             Print the DVI file.
     C-c C-t C-q             Display the printer queue.

   The Texinfo mode TeX formatting commands start a subshell in Emacs
called the '*tex-shell*'.  The 'texinfo-tex-command',
'texinfo-texindex-command', and 'tex-dvi-print-command' commands are all
run in this shell.

   You can watch the commands operate in the '*tex-shell*' buffer, and
you can switch to and from and use the '*tex-shell*' buffer as you would
any other shell buffer.

   The formatting and print commands depend on the values of several
variables.  The default values are:

         Variable                              Default value

     texinfo-texi2dvi-command                  "texi2dvi"
     texinfo-tex-command                       "tex"
     texinfo-texindex-command                  "texindex"
     texinfo-delete-from-print-queue-command   "lprm"
     texinfo-tex-trailer                       "@bye"
     tex-start-of-header                       "%**start"
     tex-end-of-header                         "%**end"
     tex-dvi-print-command                     "lpr -d"
     tex-show-queue-command                    "lpq"

   You can change the values of these variables with the 'M-x
set-variable' command (see Examining and Setting Variables (emacs)),
or with your '.emacs' initialization file (see
Init File (emacs)).

   Beginning with version 20, GNU Emacs offers a user-friendly
interface, called "Customize", for changing values of user-definable
variables.  See Easy Customization Interface (emacs),
for more details about this.  The Texinfo variables can
be found in the 'Development/Docs/Texinfo' group, once you invoke the
'M-x customize' command.

18.7 Using the Local Variables List
===================================

Yet another way to apply the TeX formatting command to a Texinfo file is
to put that command in a "local variables list" at the end of the
Texinfo file.  You can then specify the 'tex' or 'texi2dvi' commands as
a 'compile-command' and have Emacs run it by typing 'M-x compile'.  This
creates a special shell called the '*compilation*' buffer in which Emacs
runs the compile command.  For example, at the end of the 'gdb.texi'
file, after the '@bye', you could put the following:

     Local Variables:
     compile-command: "texi2dvi gdb.texi"
     End:

This technique is most often used by programmers who also compile
programs this way; see Compilation (emacs).

18.8 TeX Formatting Requirements Summary
========================================

Every Texinfo file that is to be input to TeX must begin with a '\input'
command:

     \input texinfo

This instructs TeX to load the macros it needs to process a Texinfo
file.

   Every Texinfo file must end with a line that terminates TeX's
processing and forces out unfinished pages:

     @bye

   Strictly speaking, these two lines are all a Texinfo file needs to be
processed successfully by TeX.

   Usually, however, the beginning includes a '@settitle' command to
define the title of the printed manual, a title page, a copyright page,
permissions, and a table of contents.  Besides '@bye', the end of a file
usually includes indices.  (Not to mention that most manuals contain a
body of text as well.)

   For more information, see:

   * @settitle.
   * @setchapternewpage.
   * Headings.
   * Titlepage & Copyright Page.
   * Printing Indices & Menus.
   * Contents.

18.9 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:

     <http://ftp.gnu.org/gnu/texinfo/texinfo.tex>
     <http://ftpmirror.gnu.org/texinfo/texinfo.tex>

   The latest development version is available from the Texinfo source
repository:

     <http://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.)

18.10 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 '@titlepage' command:

     @finalout

18.11 PDF Output
================

The simplest way to generate PDF output from Texinfo source is to run
the convenience script 'texi2pdf' (or 'pdftexi2dvi'); this executes the
'texi2dvi' script with the '--pdf' option (see Format with texi2dvi).
If for some reason you want to process the document by
hand, you can run the 'pdftex' program instead of plain 'tex'.  That is,
run 'pdftex foo.texi' instead of 'tex foo.texi'.

   "PDF" stands for 'Portable Document Format'.  It was invented by
Adobe Systems some years ago for document interchange, based on their
PostScript language.  Related links:

   * GNU GV, a Ghostscript-based PDF reader
     (http://www.gnu.org/software/gv/).  (It can also preview PostScript
     documents.)

   * 'xpdf', a freely available standalone PDF reader
     (http://www.foolabs.com/xpdf/) for the X window system.

   * PDF at Wikipedia
     (https://en.wikipedia.org/wiki/Portable_Document_Format).

   At present, Texinfo does not provide '@ifpdf' or '@pdf' commands as
for the other output formats, since PDF documents contain many internal
low-level offsets and cross-references that would be hard or impossible
to specify at the Texinfo source level.

   PDF files require dedicated software to be displayed, unlike the
plain ASCII formats (Info, HTML) that Texinfo supports.  They also tend
to be much larger than the DVI files output by TeX by default.
Nevertheless, a PDF file does define an actual typeset document in a
self-contained file, notably including all the fonts that are used, so
it has its place.

19 'texi2any': The Generic 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'),

plain text (with '--plaintext'),

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, like the main program, and anything which can be specified on
the command line can also be specified within a initialization file.

19.1 Invoking 'texi2any'/'makeinfo' from a Shell
================================================

To process a Texinfo file, invoke 'texi2any' or 'makeinfo' (the two
names are synonyms for the same program; we'll use the names
interchangeably) 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.texinfo

   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.texinfo' in which lines are filled to only 68
columns:

     texi2any --fill-column=68 bison.texinfo

   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 W3C 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'.

'--disable-encoding'
'--enable-encoding'
     By default, or with '--enable-encoding', output accented and
     special characters in Info and plain text output based on
     '@documentencoding'.  With '--disable-encoding', 7-bit ASCII
     transliterations are output.  See @documentencoding, and
     Inserting Accents.

'--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).

'--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).

     When the footnote style is 'separate', 'makeinfo' makes a new node
     containing the footnotes found in the current node.  When the
     footnote style is 'end', 'makeinfo' 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 Texinfo source node, and
     the split output is written into a subdirectory based on the name
     of the top-level Info 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 only the current directory.  If DIR is not given, the
     current directory is appended.  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'
'--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.

'--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 '@setfilename' (see @setfilename).  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 indexed item or item in the table of
     contents, the name of the index (or table of contents) in which it
     occurs, and the term which was indexed or entered.  The items are
     in the natural sorting order for the given element.  This dump can
     be useful for post-processors.

'--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 'makeinfo' 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, '@setfilename'
     is ignored, and 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.

'--no-ifdocbook'
'--no-ifhtml'
'--no-ifinfo'
'--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.

'--no-node-files'
'--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-number-footnotes'
'--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.

'--no-number-sections'
'--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.

'--no-validate'
'--no-pointer-validate'
     Suppress the pointer-validation phase of 'makeinfo'--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, 'makeinfo' 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).

'--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 @setfilename.

     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, 'makeinfo -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,
     'makeinfo -o bar --html foo.texi' will write 'bar/index.html',
     among other files.

'--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'.  If PATH
     is not given, the current directory is prepended.  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, '@setfilename' is ignored and the output goes to
     standard output by default; 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.)

'--transliterate-file-names'
     Enable transliteration of 8-bit characters in node names for the
     purpose of file name creation.  See HTML Xref 8-bit Character Expansion.

'-U VAR'
     Cause VAR to be undefined.  This is equivalent to '@clear VAR' in
     the Texinfo file (see @set @clear @value).

'--verbose'
     Cause 'makeinfo' to display messages saying what it is doing.
     Normally, 'makeinfo' 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).

19.2 Environment Variables Recognized by 'texi2any'
===================================================

'makeinfo' 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  html  info  pdf  plaintext  ps  xml

   If not set or otherwise specified, Info output is the default.

   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 Customization Variables and Options.

   You can control 'texi2any''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.

'debug'
     Try to load extension modules, printing many messages while doing
     so.

'omit'
     Do not use extension modules.

   Set 'TEXINFO_XS_PARSER' to '0' to disable the use of the native code
implementation of the parser module.  This is the part of 'texi2any'
that converts Texinfo input into an internal tree format used for
further processing into output formats.  This may be useful for working
around bugs or incompatibilities between the native code implementation
and the implementation in pure Perl code.

19.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 @a4paper --pdf foo.texi

is equivalent to running

     texi2dvi -t @a4paper --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 Other Customization Variables).
As you might guess, the default is 'texi2dvi'.

   'texi2any' itself does not generate any normal output when it invokes
'texi2dvi', only diagnostic messages.

19.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, and 'TEXINFO_OUTPUT_FORMAT' allows specifying
     the output format.

   * Those associated with customizing the HTML output.

   * Other ad hoc variables.

   Customization variables may set 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.

19.4.1 Customization Variables for @-Commands
---------------------------------------------

Each of the following @-commands has an associated customization
variable with the same name (minus the leading '@'):

     @allowcodebreaks       @clickstyle        @codequotebacktick
     @codequoteundirected   @deftypefnnewline  @documentdescription
     @documentencoding      @documentlanguage  @exampleindent
     @firstparagraphindent  @footnotestyle     @frenchspacing
     @kbdinputstyle         @novalidate        @paragraphindent
     @setfilename           @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.

19.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'
'--internal-links'                   'INTERNAL_LINKS'
'--macro-expand'                     'MACRO_EXPAND'
'--headers'                          'HEADERS', 'FORMAT_MENU'
'--no-warn'                          'NO_WARN'
'--no-validate'                      'novalidate'
'--number-footnotes'                 'NUMBER_FOOTNOTES'
'--number-sections'                  'NUMBER_SECTIONS'
'--node-files'                       'NODE_FILES'
'--output'                           'OUTFILE', 'SUBDIR'
'--paragraph-indent'                 'paragraphindent'
'--silent'                           'SILENT'
'--split'                            'SPLIT'
'--split-size'                       'SPLIT_SIZE'
'--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.

   In addition, the customization variable 'TEXINFO_OUTPUT_FORMAT'
allows specifying what 'makeinfo' outputs, either one of the usual
output formats that can be specified with options, or various other
forms:

'docbook'
'dvi'
'dvipdf'
'html'
'info'
'pdf'
'plaintext'
'ps'
'xml'
     These correspond to the command-line options (and
     'TEXINFO_OUTPUT_FORMAT' environment variable values) of the same
     name.  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 TEXINPUT_OUTPUT_FORMAT=textcontent "$@"

19.4.3 HTML Customization Variables
-----------------------------------

This table gives the customization variables which apply to HTML output
only.  A few other customization variables apply to both HTML and other
output formats; see Other Customization Variables.

'AVOID_MENU_REDUNDANCY'
     If set, and the menu entry and menu description are the same, then
     do not print the menu description; default false.

'AFTER_BODY_OPEN'
     If set, the corresponding text will appear at the beginning of each
     HTML file; default unset.

'AFTER_ABOUT'
     For HTML, when an About-element is output.  If set, the
     corresponding text will appear at the end of the About element;
     default unset.

'AFTER_OVERVIEW'
'AFTER_TOC_LINES'
     If set, the corresponding text is output after the short table of
     contents for 'AFTER_OVERVIEW' and after the table of contents for
     'AFTER_TOC_LINES'; otherwise, a default string is used.  At the
     time of writing, a '</div>' element is closed.

     In general, you should set 'BEFORE_OVERVIEW' if 'AFTER_OVERVIEW' is
     set, and you should set 'BEFORE_TOC_LINES' if 'AFTER_TOC_LINES' is
     set.

'BASEFILENAME_LENGTH'
     The maximum length of a base file name; default 245.  Changing this
     would make cross-manual references to such long node names invalid
     (see HTML Xref Link Basics).

'BEFORE_OVERVIEW'
'BEFORE_TOC_LINES'
     If set, the corresponding text is output before the short table of
     contents for 'BEFORE_OVERVIEW' and before the table of contents for
     'BEFORE_TOC_LINES', otherwise a default string is used.  At the
     time of writing, a '<div ...>' element is opened.

     In general you should set 'AFTER_OVERVIEW' if 'BEFORE_OVERVIEW' is
     set, and you should set 'AFTER_TOC_LINES' if 'BEFORE_TOC_LINES' is
     set.

'BIG_RULE'
     Rule used after and before the top element and before special
     elements, but not for footers and headers; default '<hr>'.

'BODYTEXT'
     The text appearing in '<body>'.  By default, sets the HTML 'lang'
     attribute to the document language (see @documentlanguage).

'CASE_INSENSITIVE_FILENAMES'
     Construct output file names as if the filesystem were case
     insensitive (see HTML Splitting); default false.

'CHAPTER_HEADER_LEVEL'
     Header formatting level used for chapter level sectioning commands;
     default '2'.

'CHECK_HTMLXREF'
     Check that manuals which are the target of external
     cross-references (see Four and Five Arguments) are present in
     'htmlxref.cnf' (see HTML Xref Configuration); default false.

'COMPLEX_FORMAT_IN_TABLE'
     If set, use tables for indentation of complex formats; default
     false.

'CONTENTS_OUTPUT_LOCATION'
     If set to 'after_top', output the contents at the end of the '@top'
     section.  If set to 'inline', output the contents where the
     '@contents' and similar @-commands are located.  If set to
     'separate_element' output the contents in separate elements, either
     at the end of the document if not split, or in a separate file.  If
     set to 'after_title' the tables of contents are output after the
     title; default 'after_top'.

'COPIABLE_ANCHORS'
     If set, output copiable anchors for the definition commands (see
     Definition Commands) and table commands (see Two-column Tables)
     where an index entry is defined.  An anchor appears as a
     '¶' sign that appears when you hover the mouse pointer over the
     heading text.

'CSS_LINES'
     CSS output, automatically determined by default (see HTML CSS).

'DATE_IN_HEADER'
     Put the document generation date in the header; off by default.

'DEF_TABLE'
     If set, a '<table>' construction for '@deffn' and similar
     @-commands is used (looking more like the TeX output), instead of
     definition lists; default false.

'DEFAULT_RULE'
     Rule used between element, except before and after the top element,
     and before special elements, and for footers and headers; default
     '<hr>'.

'DO_ABOUT'
     If set to 0 never do an About special element; if set to 1 always
     do an About special element; default 0.

'EXTERNAL_DIR'
     Base directory for external manuals; default none.  It is better to
     use the general external cross-reference mechanism (see HTML Xref Configuration)
     than this variable.

'EXTRA_HEAD'
     Additional text appearing within '<head>'; default unset.

'FOOTNOTE_END_HEADER_LEVEL'
     Header formatting level used for the footnotes header with the
     'end' footnotestyle; default '4'.  See Footnote Styles.

'FOOTNOTE_SEPARATE_HEADER_LEVEL'
     Header formatting level used for the footnotes header with the
     'separate' footnotestyle; default '4'.  See Footnote Styles.

'FRAMES'
     If set, a file describing the frame layout is generated, together
     with a file with the short table of contents; default false.

'FRAMESET_DOCTYPE'
     Same as DOCTYPE, but for the file containing the frame description.

'HEADER_IN_TABLE'
     Use tables for header formatting rather than a simple '<div>'
     element; default false.

'HTML_MATH'
     Method to use to render '@math'.  This can be unset, set to
     'mathjax' (see MathJax Customization Variables), set to 'l2h',
     which has the same effect as setting 'L2H' (see latex2html Customization Variables),
     or set to 't2h', which uses 'tex4ht'.

'ICONS'
     Use icons for the navigation panel; default false.

'IMAGE_LINK_PREFIX'
     If set, the associated value is prepended to the image file links;
     default unset.

'INDEX_ENTRY_COLON'
     Symbol used between the index entry and the associated node or
     section; default ':'.

'INFO_JS_DIR'
     (Experimental.)  Add a JavaScript browsing interface to the manual.
     The value of the variable is the directory to place the code for
     this interface, so you would run the program as e.g. 'texi2any
     --html -c INFO_JS_DIR=js MANUAL.texi' to place files in a 'js'
     directory under the output.  This provides some of the
     functionality of the Info browsers in a web browser, such as
     keyboard navigation and index lookup.  This only works with
     non-split HTML output.

     The interface should provide an acceptable fallback in
     functionality if JavaScript or web browser features are not
     available.  However, please be cautious when using this option, in
     case you do make your documentation harder to access for some of
     your users.

'INLINE_CSS_STYLE'
     Put CSS directly in HTML elements rather than at the beginning of
     the output; default false.

'JS_WEBLABELS'
'JS_WEBLABELS_FILE'
     Specify how to use a "JavaScript license web labels" page to give
     licensing information and source code for any JavaScript used in
     the HTML files for the manual.  (See
     <https://www.gnu.org/licenses/javascript-labels.html>).

     With the value 'generate' (the default), generate a labels page at
     'JS_WEBLABELS_FILE', and link to it in the HTML output files.  Only
     do this if actually referencing JavaScript files (either with
     'HTML_MATH' set to 'mathjax', or when using the experimental JS
     browsing interface when 'INFO_JS_DIR' is set).  With this setting,
     'JS_WEBLABELS_FILE' must be a relative file name.

     With the value 'reference', link to the labels file given by
     'JS_WEBLABELS_FILE' in the output, and do not generate a labels
     file.  This setting is useful if you separately maintain a single
     labels file for a larger website that includes your manual.

     With 'omit', neither generate nor link to a labels file.

'KEEP_TOP_EXTERNAL_REF'
     If set, do not ignore 'Top' as the first argument for an external
     ref to a manual, as is done by default.  See Referring to a Manual as a Whole.

'MAX_HEADER_LEVEL'
     Maximum header formatting level used (higher header formatting
     level numbers correspond to lower sectioning levels); default '4'.

'MENU_ENTRY_COLON'
     Symbol used between the menu entry and the description; default
     ':'.

'MENU_SYMBOL'
     Symbol used in front of menu entries when node names are used for
     menu entries formatting; default '&bull;'.

'MONOLITHIC'
     Output only one file including the table of contents.  Set by
     default, but only relevant when the output is not split.

'NO_CSS'
     Do not use CSS; default false.  See HTML CSS.

'PRE_ABOUT'
     Used when an About element is output.  If set to a text string,
     this text will appear at the beginning of the About element.  If
     set to a reference on a subroutine, the result of the subroutine
     call will appear at the beginning of the About element.  If not set
     (the default), default text is used.

'PRE_BODY_CLOSE'
     If set, the given text will appear at the footer of each HTML file;
     default unset.

'PROGRAM_NAME_IN_FOOTER'
     If set, output the program name and miscellaneous related
     information in the page footers; default false.

'SECTION_NAME_IN_TITLE'
     If set, when output is split, use the argument of the chapter
     structuring command (e.g., '@chapter' or '@section') in the
     '<title>' instead of the argument to '@node'.

'SHOW_TITLE'
     If set, output the title at the beginning of the document; default
     true.

'SIMPLE_MENU'
     If set, use a simple preformatted style for the menu, instead of
     breaking down the different parts of the menu; default false.
     See Menu Parts.

'TOC_LINKS'
     If set, links from headings to toc entries are created; default
     false.

'TOP_FILE'
     This file name may be used for the top-level file.  The extension
     is set appropriately, if necessary.  This is used to override the
     default, and is, in general, only taken into account when output is
     split, and for HTML.

'TOP_NODE_FILE_TARGET'
     File name used for the Top node in cross-references; default is
     'index.html'.

'TOP_NODE_UP_URL'
     A url used for Top node up references; the default is 'undef', in
     that case no Top node Up reference is generated.  For more about
     the Top node pointers, see First Node.  For overriding the Up
     pointer name in case 'TOP_NODE_UP_URL' is set and for other
     formats, see 'TOP_NODE_UP' in Other Customization Variables.

'USE_ACCESSKEY'
     Use 'accesskey' in cross-references; default true.

'USE_ISO'
     Use entities for doubled single-quote characters (see Inserting Quotation Marks),
     and '---' and '--' (see Conventions);
     default true.

'USE_LINKS'
     Generate '<link>' elements in the HTML '<head>' output; default
     true.

'USE_NODE_DIRECTIONS'
     If true, use nodes to determine where next, up and prev link to in
     node headers.  If false, use sections.  If undefined, use
     'USE_NODES' value.  Default is undefined.  Note that this setting
     does not determine the link string only where the links points to,
     see xrefautomaticsectiontitle for the link
     string customization.  If nodes and sections are systematically
     associated, this customization has no practical effect.

'USE_REL_REV'
     Use 'rel' in cross-references; default true.

'VERTICAL_HEAD_NAVIGATION'
     If set, a vertical navigation panel is used; default false.

'WORDS_IN_PAGE'
     When output is split by nodes, specifies the approximate minimum
     page length at which a navigation panel is placed at the bottom of
     a page.  To avoid ever having the navigation buttons at the bottom
     of a page, set this to a sufficiently large number.  The default is
     300.

'XREF_USE_FLOAT_LABEL'
     If set, for the float name in cross-references, use the float label
     instead of the type followed by the float number (see @float).
     The default is off.

'XREF_USE_NODE_NAME_ARG'
     Only relevant for cross-reference commands with no cross reference
     name (second argument).  If set to 1, use the node name (first)
     argument in cross-reference @-commands for the text displayed as
     the hyperlink.  If set to 0, use the node name if 'USE_NODES' is
     set, otherwise the section name.  If set to 'undef', use the first
     argument in preformatted environments, otherwise use the node name
     or section name depending on 'USE_NODES'.  The default is 'undef'.

19.4.4 MathJax Customization Variables
--------------------------------------

This table lists the customization variables which can be used when
MathJax is being used, which will be the case when 'HTML_MATH' is set to
'mathjax'.

'MATHJAX_SCRIPT'
     URL of the MathJax component file (e.g. 'tex-svg.js') you are
     using.  'texi2any' provides a default value for this variable, but
     you are encouraged to host this file yourself on your website so
     that you are not dependent on others' hosting.

'MATHJAX_SOURCE'
     A URL of the full source code in its preferred form for
     modification, or instructions for obtaining such source code, for
     the component file named by 'MATHJAX_SCRIPT'.  'Preferred form for
     modification' means that this should not be in a 'minified' form.
     Used in the license labels page (see HTML Customization Variables,
     under 'JS_WEBLABELS').

     Again, 'texi2any' provides a default value for this variable, but
     you are encouraged to host the source code for MathJax and its
     dependencies yourself.  This is in order to make the source code
     available reliably, and to reduce you and your users' dependence on
     others' distribution systems.

19.4.5 'latex2html' Customization Variables
-------------------------------------------

This table lists the customization variables which can be used when
'latex2html' is being used.

'L2H'
     For HTML.  If set, 'latex2html' is used to convert '@math' and
     '@tex' sections; default false.  Best used with '--iftex'.

'L2H_CLEAN'
     (Relevant only if 'L2H' is set.)  If set, the intermediate files
     generated in relation with 'latex2html' are removed; default true.

'L2H_FILE'
     (Relevant only if 'L2H' is set.)  If set, the given file is used as
     'latex2html''s init file; default unset.

'L2H_HTML_VERSION'
     (Relevant only if 'L2H' is set.)  The HTML version used in the
     'latex2html' call; default unset.

'L2H_L2H'
     (Relevant only if 'L2H' is set.)  The program invoked as
     'latex2html'; default is 'latex2html'.

'L2H_SKIP'
     (Relevant only if 'L2H' is set.)  If set to a true value, the
     actual call to 'latex2html' is skipped; previously generated
     content is reused instead.  If set to 0, the cache is not used at
     all.  If set to 'undef', the cache is used for as many TeX
     fragments as possible and for any remaining the command is run.
     The default is 'undef'.

'L2H_TMP'
     (Relevant only if 'L2H' is set.)  Set the directory used for
     temporary files.  None of the file name components in this
     directory name may start with '.'; otherwise, 'latex2html' will
     fail (because of 'dvips').  The default is the empty string, which
     means the current directory.

19.4.6 Other Customization Variables
------------------------------------

This table gives the remaining customization variables, which apply to
multiple formats, or affect global behavior, or otherwise don't fit into
the categories of the previous sections.

'CHECK_NORMAL_MENU_STRUCTURE'
     Warn if the nodes pointers (either explicitly or automatically set)
     are not consistent with the order of node menu entries.

'CLOSE_QUOTE_SYMBOL'
     When a closing quote is needed, use this character; default
     '&rsquo;' in HTML, '&#8217;' in DocBook.  The default for Info is
     the same as 'OPEN_QUOTE_SYMBOL' (see below).

'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).

'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 Texinfo XML.

'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 standard error; default false.

'ENABLE_ENCODING_USE_ENTITY'
     For HTML, XML.  If '--enable-encoding' is set, and there is an
     entity corresponding with the letter or the symbol being output,
     prefer the entity.  Set by default for HTML, but not XML.

'EXTERNAL_CROSSREF_SPLIT'
     For cross-references to other manuals, this determines if the other
     manual is considered to be split or monolithic.  By default, it is
     set based on the value of 'SPLIT'.  See HTML Xref, and
     HTML Xref Configuration.

'EXTENSION'
     The extension added to the output file name.  The default is
     different for each output format.

'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.  If set to 'nomenu',
     do not output menus.

     This variable is set to 'nomenu' when generating DocBook, or when
     '--no-headers' is specified.

'IGNORE_BEFORE_SETFILENAME'
     If set, begin outputting at '@setfilename', if '@setfilename' is
     present; default true.

'IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME'
     If set, spaces are ignored after an @-command that takes braces.
     Default true, matching the TeX behavior.

'INDEX_SPECIAL_CHARS_WARNING'
     If set, warn about ':' in index entry, as it leads to invalid
     entries in index menus in output Info files.  For Info and
     plaintext only.

'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.  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;
     default true.  Do not warn about index entries, since parsing
     problems there don't prevent navigation; readers can still
     relatively easily find their way to the node in question.

'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.

'NO_USE_SETFILENAME'
     If set, do not use '@setfilename' to set the document name;
     instead, base the output document name only on the input file name.
     The default is false.

'NODE_NAME_IN_INDEX'
     If set, use node names in index entries, otherwise prefer section
     names; default true.

'NODE_NAME_IN_MENU'
     If set, use node names in menu entries, otherwise prefer section
     names; default true.

'OPEN_QUOTE_SYMBOL'
     When an opening quote is needed, e.g., for '@samp' output, use the
     specified character; default '&lsquo;' for HTML, '&#8216;' for
     DocBook.  For Info, the default depends on the enabled document
     encoding (see @documentencoding); if no document encoding is
     set, or the encoding is US-ASCII, etc., ''' is used.  This
     character usually appears as an undirected single quote on modern
     systems.  If the document encoding is Unicode, the Info output uses
     a Unicode left quote.

'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.  If no input encoding is specified, the default
     output encoding name may be set by the output format.  In
     particular, the XML-based formats use 'utf-8' for
     'OUTPUT_ENCODING_NAME' if the encoding is not otherwise specified.
     See @documentencoding.

'OVERVIEW_LINK_TO_TOC'
     If set, the cross-references in the Overview link to the
     corresponding Table of Contents entries; default true.

'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 @setfilename).  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 true, some variables which are normally dynamically
     generated anew for each run (date, program name, version) are set
     to fixed and given values.  This is useful to compare the output to
     a reference file, as is done for the tests.  The default is false.

'TEXI2DVI'
     Name of the command used to produce PostScript, PDF, and DVI;
     default 'texi2dvi'.  See texi2any Printed Output.

'TEXI2HTML'
     Generate HTML and try to be as compatible as possible with
     'texi2html'; 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'.

'TEXTCONTENT_COMMENT'
     For stripped text content output (i.e., when
     'TEXINFO_OUTPUT_FORMAT' is set to 'textcontent').  If set, also
     output comments.  Default false.

'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.

'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.

     The only one executed by default is
     'move_index_entries_after_items' for HTML and DocBook output.
     Here's an example of updating the master menu in a document:

          makeinfo \
            -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.

     'simple_menu'
          Mostly the same as 'SIMPLE_MENU': use a simple preformatted
          style for the menu.  It differs from setting 'SIMPLE_MENU' in
          that 'SIMPLE_MENU' only has an effect in HTML output.

'USE_NODES'
     Preferentially use nodes to decide where elements are separated.
     If set to false, preferentially use sectioning to decide where
     elements are separated.  The default is true.

'USE_NUMERIC_ENTITY'
     For HTML and XML.  If set, use numeric entities instead of ASCII
     characters when there is no named entity.  By default, set to true
     for HTML.

'USE_UP_NODE_FOR_ELEMENT_UP'
     Fill in up sectioning direction with node direction when there is
     no sectioning up direction.  In practice this can only happen when
     there is no @top section.  Not set by default.

'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_TITLEPAGE_FOR_TITLE'
     Use the full '@titlepage' as the title, not a simple title string;
     default false.

'USE_UNIDECODE'
     If set to false, do not use the 'Text::Unidecode' Perl module to
     transliterate more characters; default true.

19.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 is used for those strings (see
gettext).  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
'gettext' (the choice can be made at build-time).

   The Gettext domain 'texinfo_document' is used for the strings.
Translated strings are written as Texinfo, and may include @-commands.
In translated strings, the varying parts of the string are not usually
denoted by '%s' and the like, but by '{arg_name}'.  (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}

   These Perl-style brace format strings are used for two reasons:
first, changing the order of 'printf' arguments is only available since
Perl 5.8.0; second, and more importantly, the order of arguments is
unpredictable, since @-command expansion may lead to different orders
depending on the output format.

   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'.  If that does not exist, and the encoding is
     not 'us-ascii', then 'us-ascii' is tried.

     The idea is that if there is a 'us-ascii' encoding, it means that
     all the characters in the charset may be expressed as @-commands.
     For example, there is a 'fr.us-ascii' locale that can accommodate
     any encoding, since all the Latin 1 characters have associated
     @-commands.  On the other hand, Japanese has only a translation
     'ja.utf-8', since there are no @-commands for Japanese characters.

  2. Next, the string is expanded as Texinfo, and converted.  The
     arguments are substituted; for example, '{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 having translations available in different encodings
for encodings which can be covered by @-commands, and also specifying
how the formatting for some commands is done, independently of the
output format--yet still be language-dependent.  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.

19.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'.

   Although ordinarily this documentation in the Texinfo manual would be
the best place to look, in this case we have documented all the options
and examples in the 'pod2texi' program itself, since it may be useful
outside of the rest of Texinfo.  Thus, please see the output of
'pod2texi --help', the version on the web at
<http://www.gnu.org/software/texinfo/manual/pod2texi.html>, etc.

   For an example of using 'pod2texi' to make Texinfo out of the Perl
documentation itself, see 'contrib/perldoc-all'
(http://svn.savannah.gnu.org/viewvc/trunk/contrib/perldoc-all/?root=texinfo)
in the Texinfo source distribution.

19.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
(available as 'util/texi2html' in the Texinfo source):

     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.

   * Translated strings cannot be customized; we hope to introduce this
     feature in 'texi2any' in the future.

   Aside from the last, 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'              'SHORTEXTN'
'--prefix'                 'PREFIX'
'--short-ref'              'SHORT_REF'
'--idx-sum'                'IDX_SUMMARY'
'--def-table'              'DEF_TABLE'
'--ignore-preamble-text'   'IGNORE_PREAMBLE_TEXT'
'--html-xref-prefix'       'EXTERNAL_DIR'
'--l2h'                    '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'                 'FRAMES'
'--menu'                   'FORMAT_MENU'
'--debug'                  'DEBUG'
'--doctype'                'DOCTYPE'
'--frameset-doctype'       'FRAMESET_DOCTYPE'
'--test'                   'TEST'

   Finally, any 'texi2html' users seeking more detailed information can
check the draft file 'doc/texi2oldapi.texi' in the Texinfo source
repository.  It consists mainly of very rough notes, but may still be
useful to some.

20 Creating and Installing Info Files
*************************************

This chapter describes how to create and install Info files.  See Info Files,
for general information about the file format itself.

20.1 Creating an Info File
==========================

'makeinfo' is a program that converts a Texinfo file into an Info file,
HTML file, or plain text.  'texinfo-format-region' and
'texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to
Info.

   For information on installing the Info file in the Info system, see
Installing an Info File.

20.1.1 'makeinfo' Advantages
----------------------------

The 'makeinfo' utility creates an Info file from a Texinfo source
providing better error messages than either of the Emacs formatting
commands.  We recommend it.  The 'makeinfo' program is independent of
Emacs.  You can run 'makeinfo' in any of three ways: from an operating
system shell, from a shell inside Emacs, or by typing the 'C-c C-m C-r'
or the 'C-c C-m C-b' command in Texinfo mode in Emacs.

   The 'texinfo-format-region' and the 'texinfo-format-buffer' commands
may be useful if you cannot run 'makeinfo'.

20.1.2 Running 'makeinfo' Within Emacs
--------------------------------------

You can run 'makeinfo' in GNU Emacs Texinfo mode by using either the
'makeinfo-region' or the 'makeinfo-buffer' commands.  In Texinfo mode,
the commands are bound to 'C-c C-m C-r' and 'C-c C-m C-b' by default.

'C-c C-m C-r'
'M-x makeinfo-region'
     Format the current region for Info.

'C-c C-m C-b'
'M-x makeinfo-buffer'
     Format the current buffer for Info.

   When you invoke 'makeinfo-region' the output goes to a temporary
buffer.  When you invoke 'makeinfo-buffer' output goes to the file set
with '@setfilename' (see @setfilename).

   The Emacs 'makeinfo-region' and 'makeinfo-buffer' commands run the
'makeinfo' program in a temporary shell buffer.  If 'makeinfo' finds any
errors, Emacs displays the error messages in the temporary buffer.

   You can parse the error messages by typing 'C-x `' ('next-error').
This causes Emacs to go to and position the cursor on the line in the
Texinfo source that 'makeinfo' thinks caused the error.  See Running 'make' or Compilers Generally (emacs),
for more information
about using the 'next-error' command.

   In addition, you can kill the shell in which the 'makeinfo' command
is running or make the shell buffer display its most recent output.

'C-c C-m C-k'
'M-x makeinfo-kill-job'
     Kill the current running 'makeinfo' job (from 'makeinfo-region' or
     'makeinfo-buffer').

'C-c C-m C-l'
'M-x makeinfo-recenter-output-buffer'
     Redisplay the 'makeinfo' shell buffer to display its most recent
     output.

(Note that the parallel commands for killing and recentering a TeX job
are 'C-c C-t C-k' and 'C-c C-t C-l'.  See Texinfo Mode Printing.)

   You can specify options for 'makeinfo' by setting the
'makeinfo-options' variable with either the 'M-x customize' or the 'M-x
set-variable' command, or by setting the variable in your '.emacs'
initialization file.

   For example, you could write the following in your '.emacs' file:

     (setq makeinfo-options
          "--paragraph-indent=0 --no-split
           --fill-column=70 --verbose")

For more information, see
Easy Customization Interface (emacs),
Examining and Setting Variables (emacs),
Init File (emacs), and
makeinfo Options.

20.1.3 The 'texinfo-format...' Commands
---------------------------------------

In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
file with the 'texinfo-format-region' command.  This formats the current
region and displays the formatted text in a temporary buffer called
'*Info Region*'.

   Similarly, you can format a buffer with the 'texinfo-format-buffer'
command.  This command creates a new buffer and generates the Info file
in it.  Typing 'C-x C-s' will save the Info file under the name
specified by the '@setfilename' line which must be near the beginning of
the Texinfo file.

'C-c C-e C-r'
'texinfo-format-region'
     Format the current region for Info.

'C-c C-e C-b'
'texinfo-format-buffer'
     Format the current buffer for Info.

   The 'texinfo-format-region' and 'texinfo-format-buffer' commands
provide you with some error checking, and other functions can provide
you with further help in finding formatting errors.  These procedures
are described in an appendix; see Catching Mistakes.  However,
the 'makeinfo' program provides better error checking (see makeinfo in Emacs).

   A peculiarity of the 'texinfo-format-buffer' and
'texinfo-format-region' commands is that they do not indent (nor fill)
paragraphs that contain '@w' or '@*' commands.

20.1.4 Batch Formatting
-----------------------

You can format Texinfo files for Info using 'batch-texinfo-format' and
Emacs batch mode.  You can run Emacs in batch mode from any shell,
including a shell inside of Emacs.  (see Initial Options (emacs).)

   Here is a shell command to format all the files that end in
'.texinfo' in the current directory:

     emacs -batch -funcall batch-texinfo-format *.texinfo

Emacs processes all the files listed on the command line, even if an
error occurs while attempting to format some of them.

   Run 'batch-texinfo-format' only with Emacs in batch mode as shown; it
is not interactive.  It kills the batch mode Emacs on completion.

   'batch-texinfo-format' is convenient if you lack 'makeinfo' and want
to format several Texinfo files at once.  When you use Batch mode, you
create a new Emacs process.  This frees your current Emacs, so you can
continue working in it.  (When you run 'texinfo-format-region' or
'texinfo-format-buffer', you cannot use that Emacs for anything else
until the command finishes.)

20.1.5 Tag Files and Split Files
--------------------------------

If a Texinfo file has more than 30,000 bytes, 'texinfo-format-buffer'
automatically creates a tag table for its Info file; 'makeinfo' always
creates a tag table.  With a "tag table", Info can jump to new nodes
more quickly than it can otherwise.

   In addition, if the Texinfo file contains more than about 300,000
bytes, 'texinfo-format-buffer' and 'makeinfo' split the large Info file
into shorter "indirect" subfiles of about 300,000 bytes each.  Big files
are split into smaller files so that Emacs does not need to make a large
buffer to hold the whole of a large Info file; instead, Emacs allocates
just enough memory for the small, split-off file that is needed at the
time.  This way, Emacs avoids wasting memory when you run Info.  (Before
splitting was implemented, Info files were always kept short and
"include files" were designed as a way to create a single, large printed
manual out of the smaller Info files.  See Include Files, for more
information.  Include files are still used for very large documents,
such as 'The Emacs Lisp Reference Manual', in which each chapter is a
separate file.)

   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 file name specified by the '@setfilename'
command.  The shortened version of the original file continues to have
the name specified by '@setfilename'.

   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 'makeinfo' 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 and how to validate the structure of the nodes, see Using Info-validate.

20.2 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.)

20.2.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'.

20.2.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.

20.2.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"))))

20.2.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 '@direntry' to specify the menu entries to add
to the Info directory file, and use '@dircategory' to specify which part
of the Info directory to put it in.  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.

   When choosing a category name for the '@dircategory' command, we
recommend consulting the Free Software Directory
(http://www.gnu.org/directory).  If your program is not listed there, or
listed incorrectly or incompletely, please report the situation to the
directory maintainers (<http://directory.fsf.org>) so that the category
names can be kept in sync.

   Here are a few examples (see the 'util/dir-example' file in the
Texinfo distribution for large sample 'dir' file):

     Emacs
     Localization
     Printing
     Software development
     Software libraries
     Text creation and manipulation

   Each 'Invoking' node for every program installed should have a
corresponding '@direntry'.  This lets users easily find the
documentation for the different programs they can run, as with the
traditional 'man' system.

20.2.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.

20.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 it is not very good?

     'info' has had improvements over time, so perhaps give it another
     go.  It 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.  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.  Additionally, in printed output
     there is no such thing as a plain link, as the page number of the
     target would have to be printed somewhere.

     If you really want a plain link in HTML output without affecting
     other output formats, you could create a macro with conditional
     definitions for each output format.

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.

21 Generating HTML
******************

'makeinfo' 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.

   'makeinfo' has many user-definable customization variables with which
you can influence the HTML output.  See Customization Variables.

   'makeinfo' can also produce output in XML and DocBook formats, but we
do not as yet describe these in detail.  See Output Formats, for a
brief overview of all the output formats.

21.1 HTML Translation
=====================

First, the HTML generated by 'makeinfo' is standard HTML 4.  When first
written, it also tried to be compatible with earlier standards (e.g.,
HTML 2.0, RFC-1866).

   Please report output from an error-free run of 'makeinfo' which has
practical browser portability problems as a bug (see Reporting Bugs).

   Some known exceptions to HTML 3.2 (using '--init-file=html32.pm'
produced strict HTML 3.2 output, but this has not been tested lately;
see Invoking texi2any):

  1. HTML 3.2 tables are generated for the '@multitable' command (see
     Multi-column Tables), but they should degrade reasonably in
     browsers without table support.

  2. The HTML 4 'id' attribute is used.

  3. The HTML 4 'lang' attribute on the '<html>' attribute is used.

  4. Entities that are not in the HTML 3.2 standard are also used.

  5. CSS is used (see HTML CSS).

  6. Some HTML 4 elements are used: 'span', 'thead', 'abbr', 'acronym'.

   To achieve maximum portability and accessibility among browsers (both
graphical and text-based), systems, and users, the HTML output is
intentionally quite plain and generic.  It has always been our goal for
users to be able to customize the output to their wishes via CSS (see
HTML CSS) or other means (see Customization Variables).  If you
cannot accomplish a reasonable customization, feel free to report that.

   However, we do not wish to depart from our basic goal of widest
readability for the core output.  For example, using fancy CSS may make
it possible for the HTML output to more closely resemble the TeX output
in some details, but this result is not even close to being worth the
ensuing difficulties.

   It is also intentionally not our goal, and not even 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.

   To repeat what was said at the top: please report output from an
error-free run of 'makeinfo' which has _practical_ browser portability
problems as a bug (see Reporting Bugs).

   A few other general points about the HTML output follow.

   *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 can support
Info-like navigation with browsers like Lynx and Emacs W3 which
implement this HTML 1.0 feature.

   *Footnotes:* for HTML, when the footnote style is 'end', or if the
output is not split, footnotes are put at the end of the output.  If the
footnote style is set to 'separate', and the output is split, they are
placed in a separate file.  See Footnote Styles.

   *Raw HTML*: 'makeinfo' 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.

21.2 HTML Splitting
===================

When splitting output at nodes (which is the default), 'makeinfo' 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 'makeinfo' 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 Invoking texi2any).  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, with the name chosen as follows:

  1. 'makeinfo' first tries the subdirectory with the base name from
     '@setfilename' (that is, any extension is removed).  For example,
     HTML output for '@setfilename gcc.info' would be written into a
     subdirectory named 'gcc/'.

  2. If that directory cannot be created for any reason, then 'makeinfo'
     tries appending '.html' to the directory name.  For example, output
     for '@setfilename texinfo' would be written to 'texinfo.html/'.

  3. If the 'NAME.html' directory can't be created either, 'makeinfo'
     gives up.

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'
(with any '.info' extension is replaced with '.html'), '--output' (the
argument is used literally), or based on the input file name as a last
resort (see @setfilename).

21.3 HTML CSS
=============

Cascading Style Sheets (CSS for short) is an Internet standard for
influencing the display of HTML documents: see
<http://www.w3.org/Style/CSS/>.

   By default, 'makeinfo' includes a few simple CSS commands to better
implement the appearance of some Texinfo environments.  Here is one of
them, as an example:

     pre.display { font-family:inherit }

   A full explanation of CSS is (far) beyond this manual; please see the
reference above.  In brief, however, the above tells the web browser to
use the same font as the main document for '@display'.  By default, the
HTML '<pre>' command uses a monospaced font.

   You can influence the CSS in the HTML output with two 'makeinfo'
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.  You may find the file
'texi2html/examples/texinfo-bright-colors.css' useful for visualizing
the CSS elements in Texinfo output.

   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 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 'makeinfo' handles them.

   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.  (Technical exception: a '@charset' directive may precede
the '@import''s.  This does not alter 'makeinfo''s behavior, it just
copies the '@charset' if present.)  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";

   As far as 'makeinfo' is concerned, the crucial characters are the '@'
at the beginning and the semicolon terminating the directive.  When
reading the CSS file, it simply copies any such '@'-directive into the
output, as follows:

   * If FILE contains only normal CSS declarations, it is included after
     'makeinfo''s 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 'makeinfo''s default CSS is included.
     If you need to override 'makeinfo''s defaults 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 'makeinfo''s defaults, and
     lastly the inline CSS from FILE.

   * Any @-directive other than '@import' and '@charset' is treated as a
     CSS declaration, meaning 'makeinfo' includes its default CSS and
     then the rest of the file.

   If the CSS file is malformed or erroneous, 'makeinfo''s output is
unspecified.  'makeinfo' does not try to interpret the meaning of the
CSS file in any way; it just looks for the special '@' and ';'
characters and blindly copies the text into the output.  Comments in the
CSS file may or may not be included in the output.

   In addition to the possibilities offered by CSS, 'makeinfo' has many
user-definable customization variables with which you can influence the
HTML output.  See Customization Variables.

21.4 HTML Cross-references
==========================

Cross-references between Texinfo manuals in HTML format become, in the
end, a standard HTML '<a>' link, but the details are unfortunately
complex.  This section describes the algorithm used in detail, 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.

21.4.1 HTML Cross-reference Link Basics
---------------------------------------

For our purposes, an HTML link consists of four components: a host name,
a directory part, a file part, and a target part.  We always assume the
'http' protocol.  For example:

     http://HOST/DIR/FILE.html#TARGET

   The information to construct a link comes from the node name and
manual name in the cross-reference command in the Texinfo source (see
Cross References), and from "external information" (see HTML Xref Configuration).

   We now consider each part in turn.

   The HOST is hardwired to be the local host.  This could either be the
literal string 'localhost', or, according to the rules for HTML links,
the 'http://localhost/' could be omitted entirely.

   The DIR and FILE parts are more complicated, and depend on the
relative split/mono nature of both the manual being processed and the
manual that the cross-reference refers to.  The underlying idea is that
there is one directory for Texinfo manuals in HTML, and a given MANUAL
is either available as a monolithic file 'MANUAL.html', or a split
subdirectory 'MANUAL/*.html'.  Here are the cases:

   * If the present manual is split, and the referent manual is also
     split, the directory is '../REFERENT/' and the file is the expanded
     node name (described later).

   * If the present manual is split, and the referent manual is mono,
     the directory is '../' and the file is 'REFERENT.html'.

   * If the present manual is mono, and the referent manual is split,
     the directory is 'REFERENT/' and the file is the expanded node
     name.

   * If the present manual is mono, and the referent manual is also
     mono, the directory is './' (or just the empty string), and the
     file is 'REFERENT.html'.

   Another rule, that only holds for file names, is that base file names
are truncated to 245 characters, to allow for an extension to be
appended and still comply with the 255-character limit which is common
to many filesystems.  Although technically this can be changed with the
'BASEFILENAME_LENGTH' customization variable (see Other Customization Variables),
doing so would make cross-manual references to such nodes
invalid.

   Any directory part in the file name argument of the source cross
reference command is ignored.  Thus, '@xref{,,,../foo}' and
'@xref{,,,foo}' both use 'foo' as the manual name.  This is because any
such attempted hardwiring of the directory is very unlikely to be useful
for both Info and HTML output.

   Finally, the TARGET part is always the expanded node name.

   Whether the present manual is split or mono is determined by user
option; 'makeinfo' defaults to split, with the '--no-split' option
overriding this.

   Whether the referent manual is split or mono, however, is another bit
of the external information (see HTML Xref Configuration).  By
default, 'makeinfo' uses the same form of the referent manual as the
present manual.

   Thus, there can be a mismatch between the format of the referent
manual that the generating software assumes, and the format it's
actually present in.  See HTML Xref Mismatch.

21.4.2 HTML Cross-reference Node Name Expansion
-----------------------------------------------

As mentioned in the previous section, the key part of the HTML cross
reference algorithm is the conversion of node names in the Texinfo
source into strings suitable for XHTML identifiers and file names.  The
restrictions are similar for each: plain ASCII letters, numbers, and the
'-' and '_' characters are all that can be used.  (Although HTML anchors
can contain most characters, XHTML is more restrictive.)

   Cross-references in Texinfo can refer either to nodes or anchors
(see @anchor).  However, anchors are treated identically to nodes in
this context, so we'll continue to say "node" names for simplicity.

   A special exception: the Top node (see The Top Node) is always
mapped to the file 'index.html', to match web server software.  However,
the HTML _target_ is 'Top'.  Thus (in the split case):

     @xref{Top,,, emacs, The GNU Emacs Manual}.
     => <a href="emacs/index.html#Top">

  1. The standard ASCII letters (a-z and A-Z) are not modified.  All
     other characters may be changed as specified below.

  2. The standard ASCII numbers (0-9) are not modified except when a
     number is the first character of the node name.  In that case, see
     below.

  3. Multiple consecutive space, tab and newline characters are
     transformed into just one space.  (It's not possible to have
     newlines in node names with the current implementation, but we
     specify it anyway, just in case.)

  4. Leading and trailing spaces are removed.

  5. After the above has been applied, each remaining space character is
     converted into a '-' character.

  6. Other ASCII 7-bit characters are transformed into '_00XX', where XX
     is the ASCII character code in (lowercase) hexadecimal.  This
     includes '_', which is mapped to '_005f'.

  7. If the node name does not begin with a letter, the literal string
     'g_t' is prefixed to the result.  (Due to the rules above, that
     string can never occur otherwise; it is an arbitrary choice,
     standing for "GNU Texinfo".)  This is necessary because XHTML
     requires that identifiers begin with a letter.

   For example:

     @node A  node --- with _'%
     => A-node-_002d_002d_002d-with-_005f_0027_0025

   Example translations of common characters:

   * '_' => '_005f'
   * '-' => '_002d'
   * 'A node' => 'A-node'

   On case-folding computer systems, nodes differing only by case will
be mapped to the same file.  In particular, as mentioned above, Top
always maps to the file 'index.html'.  Thus, on a case-folding system,
Top and a node named 'Index' will both be written to 'index.html'.
Fortunately, the targets serve to distinguish these cases, since HTML
target names are always case-sensitive, independent of operating system.

21.4.3 HTML Cross-reference Command Expansion
---------------------------------------------

Node names may contain @-commands (see Node Line Requirements).
This section describes how they are handled.

   First, comments are removed.

   Next, any '@value' commands (see @set @value) and macro
invocations (see Invoking Macros) are fully expanded.

   Then, for the following commands, the command name and braces are
removed, and the text of the argument is recursively transformed:

     @asis @b @cite @code @command @dfn @dmn @dotless
     @emph @env @file @i @indicateurl @kbd @key
     @samp @sansserif @sc @slanted @strong @sub @sup
     @t @U @var @verb @w

For '@sc', any letters are capitalized.

   In addition, the following commands are replaced by constant text, as
shown below.  If any of these commands have non-empty arguments, as in
'@TeX{bad}', it is an error, and the result is unspecified.  In this
table, '(space)' means a space character and '(nothing)' means the empty
string.  The notation 'U+HHHH' means Unicode code point HHHH (in hex, as
usual).

   There are further transformations of many of these expansions to
yield the final file or other target name, such as space characters to
'-', etc., according to the other rules.

'@(newline)'           (space)
'@(space)'             (space)
'@(tab)'               (space)
'@!'                   '!'
'@*'                   (space)
'@-'                   (nothing)
'@.'                   '.'
'@:'                   (nothing)
'@?'                   '?'
'@@'                   '@'
'@{'                   '{'
'@}'                   '}'
'@LaTeX'               'LaTeX'
'@TeX'                 'TeX'
'@arrow'               U+2192
'@bullet'              U+2022
'@comma'               ','
'@copyright'           U+00A9
'@dots'                U+2026
'@enddots'             '...'
'@equiv'               U+2261
'@error'               'error-->'
'@euro'                U+20AC
'@exclamdown'          U+00A1
'@expansion'           U+21A6
'@geq'                 U+2265
'@leq'                 U+2264
'@minus'               U+2212
'@ordf'                U+00AA
'@ordm'                U+00BA
'@point'               U+2605
'@pounds'              U+00A3
'@print'               U+22A3
'@questiondown'        U+00BF
'@registeredsymbol'    U+00AE
'@result'              U+21D2
'@textdegree'          U+00B0
'@tie'                 (space)

   Quotation mark @-commands ('@quotedblright{}' and the like), are
likewise replaced by their Unicode values.  Normal quotation
_characters_ (e.g., ASCII ' and ') are not altered.  See Inserting Quotation Marks.

   Any '@acronym', '@abbr', '@email', and '@image' commands are replaced
by their first argument.  (For these commands, all subsequent arguments
are optional, and ignored here.)  See @acronym, and @email,
and Images.

   Accents are handled according to the next section.

   Any other command is an error, and the result is unspecified.

21.4.4 HTML Cross-reference 8-bit Character Expansion
-----------------------------------------------------

Usually, characters other than plain 7-bit ASCII are transformed into
the corresponding Unicode code point(s) in Normalization Form C, which
uses precomposed characters where available.  (This is the normalization
form recommended by the W3C and other bodies.)  This holds when that
code point is '0xffff' or less, as it almost always is.

   These will then be further transformed by the rules above into the
string '_HHHH', where HHHH is the code point in hex.

   For example, combining this rule and the previous section:

     @node @b{A} @TeX{} @u{B} @point{}@enddots{}
     => A-TeX-B_0306-_2605_002e_002e_002e

   Notice: 1) '@enddots' expands to three periods which in turn expands
to three '_002e''s; 2) '@u{B}' is a 'B' with a breve accent, which does
not exist as a pre-accented Unicode character, therefore expands to
'B_0306' (B with combining breve).

   When the Unicode code point is above '0xffff', the transformation is
'__XXXXXX', that is, two leading underscores followed by six hex digits.
Since Unicode has declared that their highest code point is '0x10ffff',
this is sufficient.  (We felt it was better to define this extra escape
than to always use six hex digits, since the first two would nearly
always be zeros.)

   This method works fine if the node name consists mostly of ASCII
characters and contains only few 8-bit ones.  But if the document is
written in a language whose script is not based on the Latin alphabet
(for example, Ukrainian), it will create file names consisting almost
entirely of '_XXXX' notations, which is inconvenient and all but
unreadable.  To handle such cases, 'makeinfo' offers the
'--transliterate-file-names' command line option.  This option enables
"transliteration" of node names into ASCII characters for the purposes
of file name creation and referencing.  The transliteration is based on
phonetic principles, which makes the generated file names more easily
understandable.

   For the definition of Unicode Normalization Form C, see Unicode
report UAX#15, <http://www.unicode.org/reports/tr15/>.  Many related
documents and implementations are available elsewhere on the web.

21.4.5 HTML Cross-reference Mismatch
------------------------------------

As mentioned earlier (see HTML Xref Link Basics), the generating
software may need to guess whether a given manual being cross-referenced
is available in split or monolithic form--and, inevitably, it might
guess wrong.  However, when the _referent_ manual is generated, it is
possible to handle at least some mismatches.

   In the case where we assume the referent is split, but it is actually
available in mono, the only recourse would be to generate a 'manual/'
subdirectory full of HTML files which redirect back to the monolithic
'manual.html'.  Since this is essentially the same as a split manual in
the first place, it's not very appealing.

   On the other hand, in the case where we assume the referent is mono,
but it is actually available in split, it is possible to use JavaScript
to redirect from the putatively monolithic 'manual.html' to the
different 'manual/node.html' files.  Here's an example:

     function redirect() {
       switch (location.hash) {
         case "#Node1":
           location.replace("manual/Node1.html#Node1"); break;
         case "#Node2" :
           location.replace("manual/Node2.html#Node2"); break;
         ...
         default:;
       }
     }

   Then, in the '<body>' tag of 'manual.html':

     <body onLoad="redirect();">

   Once again, this is something the software which generated the
_referent_ manual has to do in advance, it's not something the software
generating the cross-reference in the present manual can control.

21.4.6 HTML Cross-reference Configuration: 'htmlxref.cnf'
---------------------------------------------------------

'makeinfo' reads a file named 'htmlxref.cnf' to gather information for
cross-references to other manuals in HTML output.  It is looked for in
the following directories:

'./'
     (the current directory)

'./.texinfo/'
     (under the current directory)

'~/.texinfo/'
     (where '~' is the current user's home directory)

'SYSCONFDIR/texinfo/'
     (where SYSCONFDIR is the system configuration directory specified
     at compile-time, e.g., '/usr/local/etc')

'DATADIR/texinfo/'
     (likewise specified at compile time, e.g., '/usr/local/share')

   All files found are used, with earlier entries overriding later ones.
The Texinfo distribution includes a default file which handles many GNU
manuals; it is installed in the last of the above directories, i.e.,
'DATADIR/texinfo/htmlxref.cnf'.

   The file is line-oriented.  Lines consisting only of whitespace are
ignored.  Comments are indicated with a '#' at the beginning of a line,
optionally preceded by whitespace.  Since '#' can occur in urls (like
almost any character), it does not otherwise start a comment.

   Each non-blank non-comment line must be either a "variable
assignment" or "manual information".

   A variable assignment line looks like this:

     VARNAME = VARVALUE

   Whitespace around the '=' is optional and ignored.  The VARNAME
should consist of letters; case is significant.  The VARVALUE is an
arbitrary string, continuing to the end of the line.  Variables are then
referenced with '${VARNAME}'; variable references can occur in the
VARVALUE.

   A manual information line looks like this:

     MANUAL KEYWORD URLPREFIX

with MANUAL the short identifier for a manual, KEYWORD being one of:
'mono', 'node', 'section', 'chapter', and URLPREFIX described below.
Variable references can occur only in the URLPREFIX.  For example (used
in the canonical 'htmlxref.cnf'):

     G = http://www.gnu.org
     GS = ${G}/software
     hello mono    ${GS}/hello/manual/hello.html
     hello chapter ${GS}/hello/manual/html_chapter/
     hello section ${GS}/hello/manual/html_section/
     hello node    ${GS}/hello/manual/html_node/

   If the keyword is 'mono', URLPREFIX gives the host, directory, and
file name for MANUAL as one monolithic file.

   If the keyword is 'node', 'section', or 'chapter', URLPREFIX gives
the host and directory for MANUAL split into nodes, sections, or
chapters, respectively.

   When available, 'makeinfo' will use the "corresponding" value for
cross-references between manuals.  That is, when generating monolithic
output ('--no-split'), the 'mono' url will be used, when generating
output that is split by node, the 'node' url will be used, etc.
However, if a manual is not available in that form, anything that is
available can be used.  Here is the search order for each style:

     node    => node,    section, chapter, mono
     section => section, chapter, node,    mono
     chapter => chapter, section, node,    mono
     mono    => mono,    chapter, section, node

   These section- and chapter-level cross-manual references can succeed
only when the target manual was created using '--node-files'; this is
the default for split output.

   If you have additions or corrections to the 'htmlxref.cnf'
distributed with Texinfo, please email <bug-texinfo@gnu.org> as usual.
You can get the latest version from
<http://ftpmirror.gnu.org/texinfo/htmlxref.cnf>.

21.5 '@documentdescription': Summary Text
=========================================

When producing HTML output for a document, 'makeinfo' writes a '<meta>'
element 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.">

   '@documentdescription' must be specified before the first node of the
document.

Appendix A @-Command Details
****************************

Here are the details of @-commands: information about their syntax, a
list of commands, and information about where commands can appear.

A.1 @-Command Syntax
====================

Texinfo has the following types of @-command:

1. Brace commands
     These commands start with @ followed by a letter or a word,
     followed by an argument within braces.  For example, the command
     '@dfn' indicates the introductory or defining use of a term; it is
     used as follows: 'In Texinfo, @@-commands are @dfn{mark-up}
     commands.'

2. Line commands
     These commands occupy an entire line.  The line starts with @,
     followed by the name of the command (a word); for example,
     '@center' or '@cindex'.  If no argument is needed, the word is
     followed by the end of the line.  If there is an argument, it is
     separated from the command name by a space.  Braces are not used.

3. Block commands
     These commands are written at the start of a line, with general
     text on following lines, terminated by a matching '@end' command on
     a line of its own.  For example, '@example', then the lines of a
     coding example, then '@end example'.  Some of these block commands
     take arguments as line commands do; for example, '@enumerate A'
     opening an environment terminated by '@end enumerate'.  Here 'A' is
     the argument.

4. Symbol insertion commands with no arguments
     These commands start with @ followed by a word followed by a left
     and right- brace.  These commands insert special symbols in the
     document; they do not take arguments.  Some examples: '@dots{}' =>
     '...', '@equiv{}' => '==', '@TeX{}' => 'TeX', and '@bullet{}' =>
     '*'.

5. Non-alphabetic commands
     The names of commands in all of the above categories consist of
     alphabetic characters, almost entirely in lower-case.  Unlike
     those, the non-alphabetic commands consist of an @ followed by a
     punctuation mark or other character that is not part of the Latin
     alphabet.  Non-alphabetic commands are almost always part of text
     within a paragraph.  The non-alphabetic commands include '@@',
     '@{', '@}', '@.', '@SPACE', and most of the accent commands.

6. Miscellaneous commands
     There are a handful of commands that don't fit into any of the
     above categories; for example, the obsolete command '@refill',
     which is always used at the end of a paragraph immediately
     following the final period or other punctuation character.
     '@refill' takes no argument and does not require braces.  Likewise,
     '@tab' used in a '@multitable' block does not take arguments, and
     is not followed by braces.

   Thus, the alphabetic commands fall into classes that have different
argument syntaxes.  You cannot tell to which class a command belongs by
the appearance of its name, but you can tell by the command's meaning:
if the command stands for a glyph, it is in class 4 and does not require
an argument; if it makes sense to use the command among other text as
part of a paragraph, the command is in class 1 and must be followed by
an argument in braces.  The non-alphabetic commands, such as '@:', are
exceptions to the rule; they do not need braces.

   The purpose of having different syntax for commands is to make
Texinfo files easier to read, and also to help the GNU Emacs paragraph
and filling commands work properly.

A.2 @-Command List
==================

Here is an alphabetical list of the @-commands in Texinfo.  Square
brackets, [ ], indicate optional arguments; an ellipsis, '...',
indicates repeated text.

'@WHITESPACE'
     An '@' followed by a space, tab, or newline produces a normal,
     stretchable, interword space.  See Multiple Spaces.

'@!'
     Produce an exclamation point that ends a sentence (usually after an
     end-of-sentence capital letter).  See Ending a Sentence.

'@"'
'@''
     Generate an umlaut or acute accent, respectively, over the next
     character, as in ö and ó.  See Inserting Accents.

'@&'
'@ampchar{}'
     Generate an ampersand.  See Inserting an Ampersand.

'@*'
     Force a line break.  See Line Breaks.

'@,{C}'
     Generate a cedilla accent under C, as in ç.  See Inserting Accents.

'@-'
     Insert a discretionary hyphenation point.  See @- @hyphenation.

'@.'
     Produce a period that ends a sentence (usually after an
     end-of-sentence capital letter).  See Ending a Sentence.

'@/'
     Produces no output, but allows a line break.  See Line Breaks.

'@:'
     Tell TeX to refrain from inserting extra whitespace after an
     immediately preceding period, question mark, exclamation mark, or
     colon, as TeX normally would.  See Not Ending a Sentence.

'@='
     Generate a macron (bar) accent over the next character, as in ō.
     See Inserting Accents.

'@?'
     Produce a question mark that ends a sentence (usually after an
     end-of-sentence capital letter).  See Ending a Sentence.

'@@'
'@atchar{}'
     Insert an at sign, '@'.  See Inserting an Atsign.

'@\'
'@backslashchar{}'
     Insert a backslash, '\'; '@backslashchar{}' works anywhere, while
     '@\' works only inside '@math'.  See Inserting a Backslash, and
     Inserting Math.

'@^'
'@`'
     Generate a circumflex (hat) or grave accent, respectively, over the
     next character, as in ô and è.  See Inserting Accents.

'@{'
'@lbracechar{}'
     Insert a left brace, '{'.  See Inserting Braces.

'@}'
'@rbracechar{}'
     Insert a right brace, '}'.  See Inserting Braces.

'@~'
     Generate a tilde accent over the next character, as in Ñ. See
     Inserting Accents.

'@AA{}'
'@aa{}'
     Generate the uppercase and lowercase Scandinavian A-ring letters,
     respectively: Å, å.  See Inserting Accents.

'@abbr{ABBREVIATION}'
     Indicate a general abbreviation, such as 'Comput.'.  See @abbr.

'@acronym{ACRONYM}'
     Indicate an acronym in all capital letters, such as 'NASA'. See
     @acronym.

'@AE{}'
'@ae{}'
     Generate the uppercase and lowercase AE ligatures, respectively: Æ,
     æ.  See Inserting Accents.

'@afivepaper'
     Change page dimensions for the A5 paper size.  See A4 Paper.

'@afourlatex'
'@afourpaper'
'@afourwide'
     Change page dimensions for the A4 paper size.  See A4 Paper.

'@alias NEW=EXISTING'
     Make the command '@NEW' a synonym for the existing command
     '@EXISTING'.  See @alias.

'@allowcodebreaks TRUE-FALSE'
     Control breaking at '-' and '_' in TeX.  See @allowcodebreaks.

'@anchor{NAME}'
     Define NAME as the current location for use as a cross-reference
     target.  See @anchor.

'@appendix TITLE'
     Begin an appendix.  The title appears in the table of contents.  In
     Info, the title is underlined with asterisks.  See @unnumbered @appendix.

'@appendixsec TITLE'
'@appendixsection TITLE'
     Begin an appendix section within an appendix.  The section title
     appears in the table of contents.  In Info, the title is underlined
     with equal signs.  '@appendixsection' is a longer spelling of the
     '@appendixsec' command.  See @unnumberedsec @appendixsec @heading.

'@appendixsubsec TITLE'
     Begin an appendix subsection.  The title appears in the table of
     contents.  In Info, the title is underlined with hyphens.  See
     @unnumberedsubsec @appendixsubsec @subheading.

'@appendixsubsubsec TITLE'
     Begin an appendix subsubsection.  The title appears in the table of
     contents.  In Info, the title is underlined with periods.  See
     @subsubsection.

'@arrow{}'
     Generate a right arrow glyph: '->'.  Used by default for '@click'.
     See Click Sequences.

'@asis'
     Used following '@table', '@ftable', and '@vtable' to print the
     table's first column without highlighting ("as is").  See
     @asis.

'@author AUTHOR'
     Typeset AUTHOR flushleft and underline it.  See @title @subtitle @author.

'@b{TEXT}'
     Set TEXT in a bold font.  No effect in Info.  See Fonts.

'@bullet{}'
     Generate a large round dot, * ('*' in Info).  Often used with
     '@table'.  See @bullet.

'@bsixpaper'
     Change page dimensions for the B6 paper size.  See A4 Paper.

'@bye'
     Stop formatting a file.  The formatters do not see anything in the
     input file following '@bye'.  See Ending a File.

'@c COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in any output.  A synonym for '@comment'.  'DEL' also starts a
     comment.  See Comments.

'@caption'
     Define the full caption for a '@float'.  See @caption @shortcaption.

'@cartouche'
     Highlight an example or quotation by drawing a box with rounded
     corners around it.  Pair with '@end cartouche'.  No effect in Info.
     See @cartouche.

'@center LINE-OF-TEXT'
     Center the line of text following the command.  See @titlefont @center @sp.

'@centerchap LINE-OF-TEXT'
     Like '@chapter', but centers the chapter title.  See @chapter.

'@chapheading TITLE'
     Print an unnumbered chapter-like heading, but omit from the table
     of contents.  In Info, the title is underlined with asterisks.
     See @majorheading @chapheading.

'@chapter TITLE'
     Begin a numbered chapter.  The chapter title appears in the table
     of contents.  In Info, the title is underlined with asterisks.
     See @chapter.

'@cindex ENTRY'
     Add ENTRY to the index of concepts.  See Defining the Entries of an Index.

'@cite{REFERENCE}'
     Highlight the name of a book or other reference that has no
     companion Info file.  See @cite.

'@clear FLAG'
     Unset FLAG, preventing the Texinfo formatting commands from
     formatting text between subsequent pairs of '@ifset FLAG' and '@end
     ifset' commands, and preventing '@value{FLAG}' from expanding to
     the value to which FLAG is set.  See @set @clear @value.

'@click{}'
     Represent a single "click" in a GUI.  Used within '@clicksequence'.
     See Click Sequences.

'@clicksequence{ACTION @click{} ACTION}'
     Represent a sequence of clicks in a GUI.  See Click Sequences.

'@clickstyle @CMD'
     Execute @CMD for each '@click'; the default is '@arrow'.  The usual
     following empty braces on @CMD are omitted.  See Click Sequences.

'@code{SAMPLE-CODE}'
     Indicate an expression, a syntactically complete token of a
     program, or a program name.  Unquoted in Info output.  See
     @code.

'@codequotebacktick ON-OFF'
'@codequoteundirected ON-OFF'
     Control output of '`' and ''' in code examples.  See Inserting Quote Characters.

'@comma{}'
     Insert a comma ',' character; only needed when a literal comma
     would be taken as an argument separator.  See Inserting a Comma.

'@command{COMMAND-NAME}'
     Indicate a command name, such as 'ls'.  See @command.

'@comment COMMENT'
     Begin a comment in Texinfo.  The rest of the line does not appear
     in any output.  A synonym for '@c'.  See Comments.

'@contents'
     Print a complete table of contents.  Has no effect in Info, which
     uses menus instead.  See Generating a Table of Contents.

'@copying'
     Specify copyright holders and copying conditions for the document.
     Pair with '@end copying'.  See @copying.

'@copyright{}'
     Generate the copyright symbol (C).  See @copyright.

'@defcodeindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in an
     '@code' font.  See Defining New Indices.

'@defcv CATEGORY CLASS NAME'
'@defcvx CATEGORY CLASS NAME'
     Format a description for a variable associated with a class in
     object-oriented programming.  Takes three arguments: the category
     of thing being defined, the class to which it belongs, and its
     name.  See Definition Commands.

'@deffn CATEGORY NAME ARGUMENTS...'
'@deffnx CATEGORY NAME ARGUMENTS...'
     Format a description for a function, interactive command, or
     similar entity that may take arguments.  '@deffn' takes as
     arguments the category of entity being described, the name of this
     particular entity, and its arguments, if any.  See Definition Commands.

'@defindex INDEX-NAME'
     Define a new index and its indexing command.  Print entries in a
     roman font.  See Defining New Indices.

'@definfoenclose NEWCMD, BEFORE, AFTER'
     Must be used within '@ifinfo'; create a new command '@NEWCMD' for
     Info that marks text by enclosing it in strings that precede and
     follow the text.  See @definfoenclose.

'@defivar CLASS INSTANCE-VARIABLE-NAME'
'@defivarx CLASS INSTANCE-VARIABLE-NAME'
     Format a description for an instance variable in object-oriented
     programming.  The command is equivalent to '@defcv {Instance
     Variable} ...'.  See Definition Commands.

'@defmac MACRONAME ARGUMENTS...'
'@defmacx MACRONAME ARGUMENTS...'
     Format a description for a macro; equivalent to '@deffn Macro ...'.
     See Definition Commands.

'@defmethod CLASS METHOD-NAME ARGUMENTS...'
'@defmethodx CLASS METHOD-NAME ARGUMENTS...'
     Format a description for a method in object-oriented programming;
     equivalent to '@defop Method ...'.  See Definition Commands.

'@defop CATEGORY CLASS NAME ARGUMENTS...'
'@defopx CATEGORY CLASS NAME ARGUMENTS...'
     Format a description for an operation in object-oriented
     programming.  '@defop' takes as arguments the name of the category
     of operation, the name of the operation's class, the name of the
     operation, and its arguments, if any.  See Definition Commands,
     and Abstract Objects.

'@defopt OPTION-NAME'
'@defoptx OPTION-NAME'
     Format a description for a user option; equivalent to '@defvr {User
     Option} ...'.  See Definition Commands.

'@defspec SPECIAL-FORM-NAME ARGUMENTS...'
'@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
     Format a description for a special form; equivalent to '@deffn
     {Special Form} ...'.  See Definition Commands.

'@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
'@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
     Format a description for a data type; its arguments are the
     category, the name of the type (e.g., 'int') , and then the names
     of attributes of objects of that type.  See Definition Commands,
     and Data Types.

'@deftypecv CATEGORY CLASS DATA-TYPE NAME'
'@deftypecvx CATEGORY CLASS DATA-TYPE NAME'
     Format a description for a typed class variable in object-oriented
     programming.  See Definition Commands, and Abstract Objects.

'@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
'@deftypefnx CATEGORY DATA-TYPE NAME ARGUMENTS...'
     Format a description for a function or similar entity that may take
     arguments and that is typed.  '@deftypefn' takes as arguments the
     category of entity being described, the type, the name of the
     entity, and its arguments, if any.  See Definition Commands.

'@deftypefnnewline ON-OFF'
     Specifies whether return types for '@deftypefn' and similar are
     printed on lines by themselves; default is off.  See Functions in Typed Languages.

'@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
'@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
     Format a description for a function in a typed language.  The
     command is equivalent to '@deftypefn Function ...'.  See
     Definition Commands.

'@deftypeivar CLASS DATA-TYPE VARIABLE-NAME'
'@deftypeivarx CLASS DATA-TYPE VARIABLE-NAME'
     Format a description for a typed instance variable in
     object-oriented programming.  See Definition Commands, and
     Abstract Objects.

'@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
'@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
     Format a description for a typed method in object-oriented
     programming.  See Definition Commands.

'@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
'@deftypeopx CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...'
     Format a description for a typed operation in object-oriented
     programming.  See Definition Commands, and Abstract Objects.

'@deftypevar DATA-TYPE VARIABLE-NAME'
'@deftypevarx DATA-TYPE VARIABLE-NAME'
     Format a description for a variable in a typed language.  The
     command is equivalent to '@deftypevr Variable ...'.  See
     Definition Commands.

'@deftypevr CATEGORY DATA-TYPE NAME'
'@deftypevrx CATEGORY DATA-TYPE NAME'
     Format a description for something like a variable in a typed
     language--an entity that records a value.  Takes as arguments the
     category of entity being described, the type, and the name of the
     entity.  See Definition Commands.

'@defun FUNCTION-NAME ARGUMENTS...'
'@defunx FUNCTION-NAME ARGUMENTS...'
     Format a description for a function; equivalent to '@deffn Function
     ...'.  See Definition Commands.

'@defvar VARIABLE-NAME'
'@defvarx VARIABLE-NAME'
     Format a description for a variable; equivalent to '@defvr Variable
     ...'.  See Definition Commands.

'@defvr CATEGORY NAME'
'@defvrx CATEGORY NAME'
     Format a description for any kind of variable.  '@defvr' takes as
     arguments the category of the entity and the name of the entity.
     See Definition Commands.

'@detailmenu'
     Mark the (optional) detailed node listing in a master menu.  See
     Master Menu Parts.

'@dfn{TERM}'
     Indicate the introductory or defining use of a term.  See @dfn.

'@DH{}'
'@dh{}'
     Generate the uppercase and lowercase Icelandic letter eth,
     respectively: Ð, ð.  See Inserting Accents.

'@dircategory DIRPART'
     Specify a part of the Info directory menu where this file's entry
     should go.  See Installing Dir Entries.

'@direntry'
     Begin the Info directory menu entry for this file.  Pair with '@end
     direntry'.  See Installing Dir Entries.

'@display'
     Begin a kind of example.  Like '@example' (indent text, do not
     fill), but do not select a new font.  Pair with '@end display'.
     See @display.

'@displaymath'
     Format a block of math in "display" format.  See Inserting Math.

'@dmn{DIMENSION}'
     Format a unit of measure, as in 12pt.  Causes TeX to insert a thin
     space before DIMENSION.  No effect in Info.  See @dmn.

'@docbook'
     Enter DocBook completely.  Pair with '@end docbook'.  See Raw Formatter Commands.

'@documentdescription'
     Set the document description text, included in the HTML output.
     Pair with '@end documentdescription'.  See
     @documentdescription.

'@documentencoding ENC'
     Declare the input encoding to be ENC.  See @documentencoding.

'@documentlanguage CC'
     Declare the document language as the two-character ISO-639
     abbreviation CC.  See @documentlanguage.

'@dotaccent{C}'
     Generate a dot accent over the character C, as in ȯ.  See
     Inserting Accents.

'@dotless{I-OR-J}'
     Generate dotless i ('ı') and dotless j ('j').  See Inserting Accents.

'@dots{}'
     Generate an ellipsis, '...'.  See @dots.

'@email{ADDRESS[, DISPLAYED-TEXT]}'
     Indicate an electronic mail address.  See @email.

'@emph{TEXT}'
     Emphasize TEXT, by using _italics_ where possible, and enclosing in
     asterisks in Info.  See Emphasizing Text.

'@end ENVIRONMENT'
     Ends ENVIRONMENT, as in '@end example'.  See @-commands.

'@enddots{}'
     Generate an end-of-sentence ellipsis, like this: ...  See
     @dots.

'@enumerate [NUMBER-OR-LETTER]'
     Begin a numbered list, using '@item' for each entry.  Optionally,
     start list with NUMBER-OR-LETTER.  Pair with '@end enumerate'.
     See @enumerate.

'@env{ENVIRONMENT-VARIABLE}'
     Indicate an environment variable name, such as 'PATH'.  See
     @env.

'@equiv{}'
     Indicate to the reader the exact equivalence of two forms with a
     glyph: '=='.  See @equiv.

'@error{}'
     Indicate to the reader with a glyph that the following text is an
     error message: 'error->'.  See @error.

'@errormsg{MSG}'
     Report MSG as an error to standard error, and exit unsuccessfully.
     Texinfo commands within MSG are expanded to plain text.  See
     Conditionals, and External Macro Processors.

'@euro{}'
     Generate the Euro currency sign.  See @euro.

'@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for even-numbered (left-hand)
     pages.  See How to Make Your Own Headings.

'@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for every page.  Not relevant
     to Info.  See How to Make Your Own Headings.

'@example'
     Begin an example.  Indent text, do not fill, and select fixed-width
     font.  Pair with '@end example'.  See @example.

'@exampleindent INDENT'
     Indent example-like environments by INDENT number of spaces
     (perhaps 0).  See @exampleindent.

'@exclamdown{}'
     Generate an upside-down exclamation point.  See Inserting Accents.

'@exdent LINE-OF-TEXT'
     Remove any indentation a line might have.  See @exdent.

'@expansion{}'
     Indicate the result of a macro expansion to the reader with a
     special glyph: '==>'.  See @expansion.

'@file{FILENAME}'
     Highlight the name of a file, buffer, node, directory, etc.  See
     @file.

'@finalout'
     Prevent TeX from printing large black warning rectangles beside
     over-wide lines.  See Overfull hboxes.

'@findex ENTRY'
     Add ENTRY to the index of functions.  See Defining the Entries of an Index.

'@firstparagraphindent WORD'
     Control indentation of the first paragraph after section headers
     according to WORD, one of 'none' or 'insert'.  See
     @firstparagraphindent.

'@float'
     Environment to define floating material.  Pair with '@end float'.
     See Floats.

'@flushleft'
'@flushright'
     Do not fill text; left (right) justify every line while leaving the
     right (left) end ragged.  Leave font as is.  Pair with '@end
     flushleft' ('@end flushright').  See @flushleft @flushright.

'@fonttextsize 10-11'
     Change the size of the main body font in the TeX output.  See
     Fonts.

'@footnote{TEXT-OF-FOOTNOTE}'
     Enter a footnote.  Footnote text is printed at the bottom of the
     page by TeX; Info may format in either 'End' node or 'Separate'
     node style.  See Footnotes.

'@footnotestyle STYLE'
     Specify an Info file's footnote style, either 'end' for the end
     node style or 'separate' for the separate node style.  See
     Footnotes.

'@format'
     Begin a kind of example.  Like '@display', but do not indent.  Pair
     with '@end format'.  See @example.

'@frenchspacing ON-OFF'
     Control spacing after punctuation.  See @frenchspacing.

'@ftable FORMATTING-COMMAND'
     Begin a two-column table, using '@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of functions.  Pair with '@end ftable'.  The same as
     '@table', except for indexing.  See @ftable @vtable.

'@geq{}'
     Generate a greater-than-or-equal sign, '≥'.  See @geq @leq.

'@group'
     Disallow page breaks within following text.  Pair with '@end
     group'.  Ignored in Info.  See @group.

'@guillemetleft{}'
'@guillemetright{}'
'@guillemotleft{}'
'@guillemotright{}'
'@guilsinglleft{}'
'@guilsinglright{}'
     Double and single angle quotation marks: « » ‹ ›.  '@guillemotleft'
     and '@guillemotright' are synonyms for '@guillemetleft' and
     '@guillemetright'.  See Inserting Quotation Marks.

'@H{C}'
     Generate the long Hungarian umlaut accent over C, as in ő.

'@hashchar{}'
     Insert a hash '#' character; only needed when a literal hash would
     introduce '#line' directive.  See Inserting a Hashsign, and
     External Macro Processors.

'@heading TITLE'
     Print an unnumbered section-like heading, but omit from the table
     of contents.  In Info, the title is underlined with equal signs.
     See @unnumberedsec @appendixsec @heading.

'@headings ON-OFF-SINGLE-DOUBLE'
     Turn page headings on or off, and/or specify single-sided or
     double-sided page headings for printing.  See @headings.

'@headitem'
     Begin a heading row in a multitable.  See Multitable Rows.

'@headitemfont{TEXT}'
     Set TEXT in the font used for multitable heading rows; mostly
     useful in multitable templates.  See Multitable Rows.

'@html'
     Enter HTML completely.  Pair with '@end html'.  See Raw Formatter Commands.

'@hyphenation{HY-PHEN-A-TED WORDS}'
     Explicitly define hyphenation points.  See @- @hyphenation.

'@i{TEXT}'
     Set TEXT in an italic font.  No effect in Info.  See Fonts.

'@ifclear TXIVAR'
     If the Texinfo variable TXIVAR is not set, format the following
     text.  Pair with '@end ifclear'.  See @set @clear @value.

'@ifcommanddefined TXICMD'
'@ifcommandnotdefined TXICMD'
     If the Texinfo code '@TXICMD' is (not) defined, format the follow
     text.  Pair with the corresponding '@end ifcommand...'.  See
     Testing for Texinfo Commands.

'@ifdocbook'
'@ifhtml'
'@ifinfo'
     Begin text that will appear only in the given output format.
     '@ifinfo' output appears in both Info and (for historical
     compatibility) plain text output.  Pair with '@end ifdocbook' resp.
     '@end ifhtml' resp. '@end ifinfo'.  See Conditionals.

'@ifnotdocbook'
'@ifnothtml'
'@ifnotplaintext'
'@ifnottex'
'@ifnotxml'
     Begin text to be ignored in one output format but not the others.
     '@ifnothtml' text is omitted from HTML output, etc.  Pair with the
     corresponding '@end ifnotFORMAT'.  See Conditionals.

'@ifnotinfo'
     Begin text to appear in output other than Info and (for historical
     compatibility) plain text.  Pair with '@end ifnotinfo'.  See
     Conditionals.

'@ifplaintext'
     Begin text that will appear only in the plain text output.  Pair
     with '@end ifplaintext'.  See Conditionals.

'@ifset TXIVAR'
     If the Texinfo variable TXIVAR is set, format the following text.
     Pair with '@end ifset'.  See @set @clear @value.

'@iftex'
     Begin text to appear only in the TeX output.  Pair with '@end
     iftex'.  See Conditionally Visible Text.

'@ifxml'
     Begin text that will appear only in the XML output.  Pair with
     '@end ifxml'.  See Conditionals.

'@ignore'
     Begin text that will not appear in any output.  Pair with '@end
     ignore'.  See Comments and Ignored Text.

'@image{FILENAME, [WIDTH], [HEIGHT], [ALT], [EXT]}'
     Include graphics image in external FILENAME scaled to the given
     WIDTH and/or HEIGHT, using ALT text and looking for 'FILENAME.EXT'
     in HTML.  See Images.

'@include FILENAME'
     Read the contents of Texinfo source file FILENAME.  See Include Files.

'@indent'
     Insert paragraph indentation.  See @indent.

'@indentedblock'
     Indent a block of arbitrary text on the left.  Pair with '@end
     indentedblock'.  See @indentedblock.

'@indicateurl{INDICATEURL}'
     Indicate text that is a uniform resource locator for the World Wide
     Web.  See @indicateurl.

'@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
     Make a cross-reference to an Info file for which there is no
     printed manual.  See @inforef.

'@inlinefmt{FMT, TEXT}'
     Insert TEXT only if the output format is FMT.  See Inline Conditionals.

'@inlinefmtifelse{FMT, TEXT, ELSE-TEXT}'
     Insert TEXT if the output format is FMT, else ELSE-TEXT.

'@inlineifclear{VAR, TEXT}'
'@inlineifset{VAR, TEXT}'
     Insert TEXT only if the Texinfo variable VAR is (not) set.

'@inlineraw{FMT, RAW-TEXT}'
     Insert TEXT as in a raw conditional, only if the output format is
     FMT.

'\input MACRO-DEFINITIONS-FILE'
     Use the specified macro definitions file.  This command is used
     only in the first line of a Texinfo file to cause TeX to make use
     of the 'texinfo' macro definitions file.  The '\' in '\input' is
     used instead of an '@' because TeX does not recognize '@' until
     after it has read the definitions file.  See Texinfo File Header.

'@insertcopying'
     Insert the text previously defined with the '@copying' environment.
     See @insertcopying.

'@item'
     Indicate the beginning of a marked paragraph for '@itemize' and
     '@enumerate'; indicate the beginning of the text of a first column
     entry for '@table', '@ftable', and '@vtable'.  See Lists and Tables.

'@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
     Begin an unordered list: indented paragraphs with a mark, such as
     '@bullet', inside the left margin at the beginning of each item.
     Pair with '@end itemize'.  See @itemize.

'@itemx'
     Like '@item' but do not generate extra vertical space above the
     item text.  Thus, when several items have the same description, use
     '@item' for the first and '@itemx' for the others.  See @itemx.

'@kbd{KEYBOARD-CHARACTERS}'
     Indicate characters of input to be typed by users.  See @kbd.

'@kbdinputstyle STYLE'
     Specify when '@kbd' should use a font distinct from '@code'
     according to STYLE: 'code', 'distinct', 'example'.  See @kbd.

'@key{KEY-NAME}'
     Indicate the name of a key on a keyboard.  See @key.

'@kindex ENTRY'
     Add ENTRY to the index of keys.  See Defining the Entries of an Index.

'@L{}'
'@l{}'
     Generate the uppercase and lowercase Polish suppressed-L letters,
     respectively: Ł, ł.

'@LaTeX{}'
     Generate the LaTeX logo.  See @TeX @LaTeX.

'@leq{}'
     Generate a less-than-or-equal sign, '≤'.  See @geq @leq.

'@lisp'
     Begin an example of Lisp code.  Indent text, do not fill, and
     select fixed-width font.  Pair with '@end lisp'.  See @lisp.

'@listoffloats'
     Produce a table-of-contents-like listing of '@float's.  See
     @listoffloats.

'@lowersections'
     Change subsequent chapters to sections, sections to subsections,
     and so on.  See '@raisesections' and '@lowersections'.

'@macro MACRONAME {PARAMS}'
     Define a new Texinfo command '@MACRONAME{PARAMS}'.  Pair with '@end
     macro'.  See Defining Macros.

'@majorheading TITLE'
     Print an unnumbered chapter-like heading, but omit from the table
     of contents.  This generates more vertical whitespace before the
     heading than the '@chapheading' command.  See @majorheading @chapheading.

'@math{MATHEMATICAL-EXPRESSION}'
     Format a mathematical expression.  See Inserting Math.

'@menu'
     Mark the beginning of a menu of nodes.  No effect in a printed
     manual.  Pair with '@end menu'.  See Menus.

'@minus{}'
     Generate a minus sign, '-'.  See @minus.

'@multitable COLUMN-WIDTH-SPEC'
     Begin a multi-column table.  Begin each row with '@item' or
     '@headitem', and separate columns with '@tab'.  Pair with '@end
     multitable'.  See Multitable Column Widths.

'@need N'
     Start a new page in a printed manual if fewer than N mils
     (thousandths of an inch) remain on the current page.  See
     @need.

'@node NAME, NEXT, PREVIOUS, UP'
     Begin a new node.  See Writing a Node.

'@noindent'
     Prevent text from being indented as if it were a new paragraph.
     See @noindent.

'@novalidate'
     Suppress validation of node references and omit creation of
     auxiliary files with TeX.  Use before any sectioning or
     cross-reference commands.  See Pointer Validation.

'@O{}'
'@o{}'
     Generate the uppercase and lowercase O-with-slash letters,
     respectively: Ø, ø.

'@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
'@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
     Specify page footings resp. headings for odd-numbered (right-hand)
     pages.  See How to Make Your Own Headings.

'@OE{}'
'@oe{}'
     Generate the uppercase and lowercase OE ligatures, respectively: Œ,
     œ.  See Inserting Accents.

'@ogonek{C}'
     Generate an ogonek diacritic under the next character, as in ą.
     See Inserting Accents.

'@option{OPTION-NAME}'
     Indicate a command-line option, such as '-l' or '--help'.  See
     @option.

'@ordf{}'
'@ordm{}'
     Generate the feminine and masculine Spanish ordinals, respectively:
     ª, º.  See Inserting Accents.

'@page'
     Start a new page in a printed manual.  No effect in Info.  See
     @page.

'@pagesizes [WIDTH][, HEIGHT]'
     Change page dimensions.  See pagesizes.

'@paragraphindent INDENT'
     Indent paragraphs by INDENT number of spaces (perhaps 0); preserve
     source file indentation if INDENT is 'asis'.  See
     @paragraphindent.

'@part TITLE'
     Begin a group of chapters or appendixes; included in the tables of
     contents and produces a page of its own in printed output.  See
     @part.

'@pindex ENTRY'
     Add ENTRY to the index of programs.  See Defining the Entries of an Index.

'@point{}'
     Indicate the position of point in a buffer to the reader with a
     glyph: '-!-'.  See @point.

'@pounds{}'
     Generate the pounds sterling currency sign.  See @pounds.

'@print{}'
     Indicate printed output to the reader with a glyph: '-|'.  See
     @print.

'@printindex INDEX-NAME'
     Generate the alphabetized index for INDEX-NAME (using two columns
     in a printed manual).  See Printing Indices & Menus.

'@pxref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with a lowercase 'see' in a printed
     manual.  Use within parentheses only.  Only the first argument is
     mandatory.  See @pxref.

'@questiondown{}'
     Generate an upside-down question mark.  See Inserting Accents.

'@quotation'
     Narrow the margins to indicate text that is quoted from another
     work.  Takes optional argument specifying prefix text, e.g., an
     author name.  Pair with '@end quotation'.  See @quotation.

'@quotedblleft{}'
'@quotedblright{}'
'@quoteleft{}'
'@quoteright{}'
'@quotedblbase{}'
'@quotesinglbase{}'
     Produce various quotation marks: “ ” ‘ ’ „ ‚.  See Inserting Quotation Marks.

'@r{TEXT}'
     Set TEXT in the regular roman font.  No effect in Info.  See
     Fonts.

'@raggedright'
     Fill text; left justify every line while leaving the right end
     ragged.  Leave font as is.  Pair with '@end raggedright'.  No
     effect in Info.  See @raggedright.

'@raisesections'
     Change subsequent sections to chapters, subsections to sections,
     and so on.  See Raise/lower sections.

'@ref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a plain reference that does not start with any special text.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  See @ref.

'@registeredsymbol{}'
     Generate the legal symbol (R).  See @registeredsymbol.

'@result{}'
     Indicate the result of an expression to the reader with a special
     glyph: '=>'.  See @result.

'@ringaccent{C}'
     Generate a ring accent over the next character, as in o̊.  See
     Inserting Accents.

'@samp{TEXT}'
     Indicate a literal example of a sequence of characters, in general.
     Quoted in Info output.  See @samp.

'@sansserif{TEXT}'
     Set TEXT in a sans serif font if possible.  No effect in Info.
     See Fonts.

'@sc{TEXT}'
     Set TEXT in a small caps font in printed output, and uppercase in
     Info.  See Smallcaps.

'@section TITLE'
     Begin a section within a chapter.  The section title appears in the
     table of contents.  In Info, the title is underlined with equal
     signs.  Within '@chapter' and '@appendix', the section title is
     numbered; within '@unnumbered', the section is unnumbered.  See
     @section.

'@set TXIVAR [STRING]'
     Define the Texinfo variable TXIVAR, optionally to the value STRING.
     See @set @clear @value.

'@setchapternewpage ON-OFF-ODD'
     Specify whether chapters start on new pages, and if so, whether on
     odd-numbered (right-hand) new pages.  See @setchapternewpage.

'@setfilename INFO-FILE-NAME'
     Provide a name to be used for the output files.  This command is
     ignored for TeX formatting.  See @setfilename.

'@settitle TITLE'
     Specify the title for page headers in a printed manual, and the
     default document title for HTML '<head>'.  See @settitle.

'@shortcaption'
     Define the short caption for a '@float'.  See @caption @shortcaption.

'@shortcontents'
     Print a short table of contents, with chapter-level entries only.
     Not relevant to Info, which uses menus rather than tables of
     contents.  See Generating a Table of Contents.

'@shorttitlepage TITLE'
     Generate a minimal title page.  See @titlepage.

'@slanted{TEXT}'
     Set TEXT in a slanted font if possible.  No effect in Info.  See
     Fonts.

'@smallbook'
     Cause TeX to produce a printed manual in a 7 by 9.25 inch format
     rather than the regular 8.5 by 11 inch format.  See @smallbook.
     Also, see small.

'@smalldisplay'
     Begin a kind of example.  Like '@display', but use a smaller font
     size where possible.  Pair with '@end smalldisplay'.  See
     small.

'@smallexample'
     Begin an example.  Like '@example', but use a smaller font size
     where possible.  Pair with '@end smallexample'.  See small.

'@smallformat'
     Begin a kind of example.  Like '@format', but use a smaller font
     size where possible.  Pair with '@end smallformat'.  See small.

'@smallindentedblock'
     Like '@indentedblock', but use a smaller font size where possible.
     Pair with '@end smallindentedblock'.  See small.

'@smalllisp'
     Begin an example of Lisp code.  Same as '@smallexample'.  Pair with
     '@end smalllisp'.  See small.

'@smallquotation'
     Like '@quotation', but use a smaller font size where possible.
     Pair with '@end smallquotation'.  See small.

'@sortas {KEY}'
     Used in the arguments to index commands to give a string by which
     the index entry should be sorted.  See Indexing Commands.

'@sp N'
     Skip N blank lines.  See @sp.

'@ss{}'
     Generate the German sharp-S es-zet letter, ß.  See Inserting Accents.

'@strong {TEXT}'
     Emphasize TEXT more strongly than '@emph', by using *boldface*
     where possible; enclosed in asterisks in Info.  See Emphasizing Text.

'@sub {TEXT}'
     Set TEXT as a subscript.  See Inserting Subscripts and Superscripts.

'@subheading TITLE'
     Print an unnumbered subsection-like heading, but omit from the
     table of contents of a printed manual.  In Info, the title is
     underlined with hyphens.  See @unnumberedsubsec @appendixsubsec @subheading.

'@subsection TITLE'
     Begin a subsection within a section.  The subsection title appears
     in the table of contents.  In Info, the title is underlined with
     hyphens.  Same context-dependent numbering as '@section'.  See
     @subsection.

'@subsubheading TITLE'
     Print an unnumbered subsubsection-like heading, but omit from the
     table of contents of a printed manual.  In Info, the title is
     underlined with periods.  See @subsubsection.

'@subsubsection TITLE'
     Begin a subsubsection within a subsection.  The subsubsection title
     appears in the table of contents.  In Info, the title is underlined
     with periods.  Same context-dependent numbering as '@section'.
     See @subsubsection.

'@subtitle TITLE'
     In a printed manual, set a subtitle in a normal sized font flush to
     the right-hand side of the page.  Not relevant to Info, which does
     not have title pages.  See @title @subtitle @author.

'@summarycontents'
     Print a short table of contents.  Synonym for '@shortcontents'.
     See Generating a Table of Contents.

'@sup {TEXT}'
     Set TEXT as a superscript.  See Inserting Subscripts and Superscripts.

'@syncodeindex FROM-INDEX TO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument, formatting the entries from the first index
     with '@code'.  See Combining Indices.

'@synindex FROM-INDEX TO-INDEX'
     Merge the index named in the first argument into the index named in
     the second argument.  Do not change the font of FROM-INDEX entries.
     See Combining Indices.

'@t{TEXT}'
     Set TEXT in a fixed-width, typewriter-like font.  No effect in
     Info.  See Fonts.

'@tab'
     Separate columns in a row of a multitable.  See Multitable Rows.

'@table FORMATTING-COMMAND'
     Begin a two-column table (description list), using '@item' for each
     entry.  Write each first column entry on the same line as '@item'.
     First column entries are printed in the font resulting from
     FORMATTING-COMMAND.  Pair with '@end table'.  See Making a Two-column Table.
     Also see @ftable @vtable,
     and @itemx.

'@TeX{}'
     Generate the TeX logo.  See @TeX @LaTeX.

'@tex'
     Enter TeX completely.  Pair with '@end tex'.  See Raw Formatter Commands.

'@textdegree{}'
     Generate the degree symbol.  See @textdegree.

'@thischapter'
'@thischaptername'
'@thischapternum'
'@thisfile'
'@thispage'
'@thistitle'
     Only allowed in a heading or footing.  Stands for, respectively,
     the number and name of the current chapter (in the format 'Chapter
     1: Title'), the current chapter name only, the current chapter
     number only, the file name, the current page number, and the title
     of the document, respectively.  See How to Make Your Own Headings.

'@TH{}'
'@th{}'
     Generate the uppercase and lowercase Icelandic letter thorn,
     respectively: Þ, þ.  See Inserting Accents.

'@tie{}'
     Generate a normal interword space at which a line break is not
     allowed.  See @tie.

'@tieaccent{CC}'
     Generate a tie-after accent over the next two characters CC, as in
     'oo͡'.  See Inserting Accents.

'@tindex ENTRY'
     Add ENTRY to the index of data types.  See Defining the Entries of an Index.

'@title TITLE'
     In a printed manual, set a title flush to the left-hand side of the
     page in a larger than normal font and underline it with a black
     rule.  Not relevant to Info, which does not have title pages.
     See @title @subtitle @author.

'@titlefont{TEXT}'
     In a printed manual, print TEXT in a larger than normal font.
     See @titlefont @center @sp.

'@titlepage'
     Begin the title page.  Write the command on a line of its own,
     paired with '@end titlepage'.  Nothing between '@titlepage' and
     '@end titlepage' appears in Info.  See @titlepage.

'@today{}'
     Insert the current date, in '1 Jan 1900' style.  See How to Make Your Own Headings.

'@top TITLE'
     Mark the topmost '@node' in the file, which must be defined on the
     line immediately preceding the '@top' command.  The title is
     formatted as a chapter-level heading.  In TeX and
     'texinfo-format-buffer', the '@top' command is merely a synonym for
     '@unnumbered'.

'@U{HEX}'
     Output a representation of Unicode character U+HEX.  See
     Inserting Unicode.

'@u{C}'
'@ubaraccent{C}'
'@udotaccent{C}'
     Generate a breve, underbar, or underdot accent, respectively, over
     or under the character C, as in ŏ, o̲, ọ.  See Inserting Accents.

'@unmacro MACRONAME'
     Undefine the macro '@MACRONAME' if it has been defined.  See
     Defining Macros.

'@unnumbered TITLE'
     Begin a chapter that appears without chapter numbers of any kind.
     The title appears in the table of contents.  In Info, the title is
     underlined with asterisks.  See @unnumbered @appendix.

'@unnumberedsec TITLE'
     Begin a section that appears without section numbers of any kind.
     The title appears in the table of contents of a printed manual.  In
     Info, the title is underlined with equal signs.  See
     @unnumberedsec @appendixsec @heading.

'@unnumberedsubsec TITLE'
     Begin an unnumbered subsection.  The title appears in the table of
     contents.  In Info, the title is underlined with hyphens.  See
     @unnumberedsubsec @appendixsubsec @subheading.

'@unnumberedsubsubsec TITLE'
     Begin an unnumbered subsubsection.  The title appears in the table
     of contents.  In Info, the title is underlined with periods.  See
     @subsubsection.

'@uref{URL[, DISPLAYED-TEXT][, REPLACEMENT}'
'@url{URL[, DISPLAYED-TEXT][, REPLACEMENT}'
     Define a cross-reference to an external uniform resource locator,
     e.g., for the World Wide Web.  See @url.

'@urefbreakstyle STYLE'
     Specify how '@uref'/'@url' should break at special characters:
     'after', 'before', 'none'.  See @url.

'@v{C}'
     Generate check accent over the character C, as in ǒ.  See
     Inserting Accents.

'@value{TXIVAR}'
     Insert the value, if any, of the Texinfo variable TXIVAR,
     previously defined by '@set'.  See @set @clear @value.

'@var{METASYNTACTIC-VARIABLE}'
     Highlight a metasyntactic variable, which is something that stands
     for another piece of text.  See @var.

'@verb{DELIM LITERAL DELIM}'
     Output LITERAL, delimited by the single character DELIM, exactly as
     is (in the fixed-width font), including any whitespace or Texinfo
     special characters.  See @verb.

'@verbatim'
     Output the text of the environment exactly as is (in the
     fixed-width font).  Pair with '@end verbatim'.  See @verbatim.

'@verbatiminclude FILENAME'
     Output the contents of FILENAME exactly as is (in the fixed-width
     font).  See @verbatiminclude.

'@vindex ENTRY'
     Add ENTRY to the index of variables.  See Defining the Entries of an Index.

'@vskip AMOUNT'
     In a printed manual, insert whitespace so as to push text on the
     remainder of the page towards the bottom of the page.  Used in
     formatting the copyright page with the argument '0pt plus 1filll'.
     (Note spelling of 'filll'.)  '@vskip' may be used only in contexts
     ignored for Info.  See Copyright.

'@vtable FORMATTING-COMMAND'
     Begin a two-column table, using '@item' for each entry.
     Automatically enter each of the items in the first column into the
     index of variables.  Pair with '@end vtable'.  The same as
     '@table', except for indexing.  See @ftable @vtable.

'@w{TEXT}'
     Disallow line breaks within TEXT.  See @w.

'@xml'
     Enter XML completely.  Pair with '@end xml'.  See Raw Formatter Commands.

'@xref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [MANUAL]}'
     Make a reference that starts with 'See' in a printed manual.
     Follow command with a punctuation mark.  Only the first argument is
     mandatory.  See @xref.

'@xrefautomaticsectiontitle ON-OFF'
     By default, use the section title instead of the node name in cross
     references, including in node headers in HTML. See Three Arguments.