This manual is for GNU Texinfo (version 7.2, 20 December 2024), a
documentation system that can produce both online information and a
printed manual from a single source using semantic markup.

   Copyright © 1988-2024 Free Software Foundation, Inc.

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

21.7.5 HTML Cross-reference Configuration: ‘htmlxref.cnf’
---------------------------------------------------------

For other manuals published on the World Wide Web to be able to have
correct cross-references to your manual, the HOST and DIR parts of the
cross-reference need to be known by Texinfo converters when they produce
HTML for those other manuals.  Similarly, for your manual in HTML format
to have correct cross-references to other manuals, ‘texi2any’ needs to
know how to construct the URLs for other manuals.

   ‘texi2any’ 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, based on the XDG Base Directory
Specification
(https://specifications.freedesktop.org/basedir-spec/latest/) with
defaults based on installation directories:

‘./’
     (the current directory)

‘leading input file path directory’
     If there is a leading directory and it is not the current
     directory.  For example, if the input file is
     ‘some/dir/mymanual.texi’, ‘htmlxref.cnf’ is searched for in
     ‘some/dir’.

‘./.texinfo/’
     (under the current directory)

‘XDG_CONFIG_HOME/texinfo’
     (with ‘XDG_CONFIG_HOME’ an environment variable)

‘~/.config/texinfo/’
     (where ‘~’ is the current user's home directory, only if
     ‘XDG_CONFIG_HOME’ is not set)

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

‘XDG_CONFIG_DIRS/texinfo’
     (for each directory in the ‘:’ delimited ‘XDG_CONFIG_DIRS’
     environment variable)

‘DATADIR/texinfo/’
     (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 ‘DATADIR/texinfo/htmlxref.cnf’, one of the
last of the above directories.

   You can use a local ‘htmlxref.cnf’ to complete or correct the default
file from the Texinfo distribution.  This could be useful to correct
outdated data, or even to generate cross-references to local files for
some manuals.

   The ‘HTMLXREF_MODE’ customization variable can be set to modify how
the files are found.  For instance, if set to ‘none’, no external
information is used.  ‘HTMLXREF_FILE’ sets the file name to something
else than ‘htmlxref.cnf’.  See HTML Xref Configuration Customization.

   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 ‘texi2any’ is generating a link to another Texinfo manual, it
will prefer to use a line for the manual with the same splitting option
as the current output.  That is, when generating monolithic output
(‘--no-split’), a ‘mono’ URL will be preferred; when generating output
that is split by node, a ‘node’ URL will be preferred, etc.

   If no information line with the preferred splitting option is present
for a given manual, then other lines for that manual can be used if
present.  Here is the full search order for each splitting option:

     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.

   At present, the ‘htmlxref.cnf’ file distributed with GNU Texinfo
serves as the main resource to locate Texinfo HTML manuals in the World
Wide Web.  Since it is installed in a location used by ‘texi2any’,
information on HTML manuals found in this file will be used for
cross-references by default.

   If you have additions or corrections to the ‘htmlxref.cnf’
distributed with Texinfo, please email <bug-texinfo@gnu.org> as usual.
If you publish a Texinfo HTML manual on the World Wide Web, having an
up-to-date location listed in ‘htmlxref.cnf’ should ensure that all HTML
manuals generated by ‘texi2any’ use this location for cross-references
automatically.  You can get the latest version from
<http://ftpmirror.gnu.org/texinfo/htmlxref.cnf>.

21.8 HTML Output Customization
==============================

You can use many user-definable customization variables to influence the
HTML output.  See HTML Customization Variables List for the full
list.  The possibilities offered by the customization variables, ranging
from overall document structure and HTML language variant to formatting
of specific constructs, should cover most needs not already satisfied by
CSS customization (see HTML CSS).

   If you ever need more control, you may be able to achieve this
through the use of initialization files, which are described in a
separate manual (see texi2any_api).

   If the ‘TEXI2HTML’ customization variable is set, the generated HTML
is as compatible as possible with ‘texi2html’ (see texi2html).  The
effect of this variable is quite unusual, as it does not directly modify
the output, but sets a lot of other customization variables, including
some that may only be set in initialization files and are described in
the separate manual on ‘texi2any’ Output Customization.  Unset in the
default case.

21.8.1 HTML Output Structure Customization
------------------------------------------

You can use customization variables to control the output of document
titles and tables of contents or other similar parts of documents.
Other variables have an effect on how ‘texi2any’ views the structure of
a document and how output is split into output files.

   If ‘SHOW_TITLE’ is ‘undef’, the default, no title is output at the
start of the output.  If you set this variable, by default the full
‘@titlepage’ is used for the title; unset ‘USE_TITLEPAGE_FOR_TITLE’ to
get a simple title string.

   By default, the HTML output is tailored for online viewing, with the
Top node being output as a top-level starting point for the reader.  You
can set ‘NO_TOP_NODE_OUTPUT’ to remove the Top node, which results in
output that may be more similar to the format of a printed book.  By
default, setting ‘NO_TOP_NODE_OUTPUT’ also outputs a title at the
beginning of the document, although you can override this by setting
‘SHOW_TITLE’ to 0.

   In each node, by default a list is output of subordinate sections for
navigation.  This corresponds to the ‘FORMAT_MENU’ variable being set to
‘sectiontoc’.  To use menus instead to navigate in the document (as in
Info format; see Menus), set ‘FORMAT_MENU’ to ‘menu’.  If you do not
want either menus or subordinate sections list for navigation to be
output, set ‘FORMAT_MENU’ to ‘nomenu’.

   By default, the table of contents for the entire document is output
at the end of the ‘@top’ section, to have the main location for
navigation in the whole document early on.  This corresponds to the
‘CONTENTS_OUTPUT_LOCATION’ variable set to ‘after_top’.

   You can have the table of contents output after the title (if
‘SHOW_TITLE’ is set) by setting ‘CONTENTS_OUTPUT_LOCATION’ to
‘after_title’.  To output the table of contents at the end of the
document or to a separate file, if output is split, set
‘CONTENTS_OUTPUT_LOCATION’ to ‘separate_element’.  You can also set
‘CONTENTS_OUTPUT_LOCATION’ to ‘inline’: in this case, the the tables of
contents are output where the corresponding @-command, for example
‘@contents’, is used.

   You may find it useful to set ‘CONTENTS_OUTPUT_LOCATION’ when
‘FORMAT_MENU’ is set to ‘menu’ in order to use menus for navigation.  In
this case, there should already be a master menu in the ‘@top’ section
(see Master Menu Parts), and so the reader of your manual may not
need a table of contents at the same location.

   By default, each node is output in a separate file.  You can change
this with the ‘--split’ command-line option, which is equivalent to
setting the ‘SPLIT’ variable.  ‘SPLIT’ can take the values ‘chapter’,
‘section’, or ‘node’, or be set to an empty string to indicate non-split
output.  See Splitting Output.

   Elementary units called “output units” are used for output, with each
output file containing the content for one or more output units,
depending on the value of ‘SPLIT’.  Output units contain the content
associated with a node or a sectioning command.  In typical Texinfo
document sources, a node command is almost always associated with an
immediately following sectioning command.

   The customization variable ‘USE_NODES’ determines whether the node or
the sectioning command is considered to be the main command.  By
default, nodes are used as the main component for the separation of
output units.  You can set ‘USE_NODES’ to false to preferentially use
sectioning to decide where output units are separated.  When sections
are the main components of output units, "isolated" nodes not directly
associated with a sectioning command are associated with the following
sectioning command, while sectioning commands without nodes constitute
output units.  Conversely, when nodes are the main components of output
units, isolated sections not associated with nodes are associated with
the previous node, and isolated nodes are output units.

   By default, the ‘USE_NODES’ setting also affects whether next, up and
prev links in node headers link to nodes or sections, with nodes used if
true, and sections used if false.  You can override this using the
‘USE_NODE_DIRECTIONS’ variable (default value 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.

   You can add a special “About” element explaining how to navigate by
setting ‘DO_ABOUT’, set to 0 in the default case (no About element).  If
‘PROGRAM_NAME_IN_ABOUT’ is also set, output the program name and
miscellaneous related information in the About special element; default
false.

   In the case of non-split output, by default only one file is output
which contains any About elements (with ‘DO_ABOUT’) and tables of
contents elements (with ‘CONTENTS_OUTPUT_LOCATION’ set to
‘separate_element’).  If you prefer such special elements to be
separate, set ‘MONOLITHIC’ to 0 to output special elements to separate
files.

   In Texinfo code, a ‘@node’ command is usually followed by a
sectioning command, providing a heading for the node.  By default, a
node with no following sectioning command, but followed by a command
like ‘@heading’, has its heading provided by the heading command.  This
avoids having both the node name and the heading command as headings.
To have the node name used as heading in that case, set
‘USE_NEXT_HEADING_FOR_LONE_NODE’ to 0.

21.8.2 File Names and Links Customization for HTML
--------------------------------------------------

There are customization variables to control output file names, and to
customize hyperlinks output within output files.

   You can specify the output file names with more control than merely
the command line option ‘--output’ (see Invoking texi2any).  The
‘PREFIX’ customization variable overrides the base name of the file
given by ‘@setfilename’ or the file name and should not contain any
directory components.  To alter intermediate directories, use the
‘SUBDIR’ customization variable.  Finally, you may also override the
extension with the customization variable ‘EXTENSION’.  This variable
should be ‘undef’ if no extension is to be added.  If you set
‘CASE_INSENSITIVE_FILENAMES’, file names are constructed as if the
filesystem were case insensitive.  In that case, one file name is used
for all files differing only by case.

   Furthermore, the customization variable ‘TOP_FILE’ overrides the
output file name for the top element.  This is, in general, only taken
into account when output is split.

   If ‘USE_ACCESSKEY’ is set, the default, the ‘accesskey’ attribute is
used to provide keyboard shortcuts on some navigation hyperlinks.  ‘n’
is used for links to the next node or section, ‘p’ for links to the
previous node or section, and ‘u’ for up direction links.  Similarly, if
the ‘USE_REL_REV’ customization variable is set, the default, the ‘rel’
attribute is used in navigation to define the relationship between the
current page and the linked resource.  For example, the ‘contents’ ‘rel’
attribute is set for a link to the table of contents, the ‘next’ ‘rel’
attribute is set for a link to the next node or section.

   There are customization variables that are specific to particular
types of link:

_Cross-reference command links_
     If the second argument of a cross-reference command is set, it is
     displayed as hyperlink text (see Two Arguments).  Otherwise the
     ‘XREF_USE_NODE_NAME_ARG’ customization variable is used to
     determine the hyperlink text.  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’.

_Links to floats_
     If you set ‘XREF_USE_FLOAT_LABEL’ (default is off), the float label
     is used instead of the type followed by the float number (see
     @float).

_Links to nodes or sections for index entries_
     In ‘@printindex’ formatting, two links are output: a link to the
     index entry, and a link to the root @-command containing the index
     entry.  The ‘NODE_NAME_IN_INDEX’ customization variable specifies
     whether the node or section should be used for the link to the root
     @-command.  If true, use node names in index entries, otherwise use
     section names.  If undefined, use the ‘USE_NODES’ value to
     determine which root @-command to prefer.  Default is undefined.

_Menu links_
     Node names are used in menu entries links by default.  Set
     ‘NODE_NAME_IN_MENU’ to false to use section names instead.

_Table of contents links_
     If a main Table of contents and a Short table of contents are both
     present, the cross-references in the Short table of contents link
     to the corresponding Table of Contents entries in the default case.
     Set ‘SHORT_TOC_LINK_TO_TOC’ to 0 to link to the sectioning commands
     instead.

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

_Top node Up direction link_
     By default no Up reference is generated for the Top node.  You can
     set ‘IGNORE_REF_TO_TOP_NODE_UP’ so that any references to the Top
     Up node (by default, ‘(dir)’) appearing in other cross-references
     are also ignored.  ‘IGNORE_REF_TO_TOP_NODE_UP’ is not set in the
     default case.  (see TOP_NODE_UP.)

     If the manual is referred to in a web page together with other
     manuals, it may be relevant to link to that page.  Set
     ‘TOP_NODE_UP_URL’ to the URL used for Top node up references.  If
     ‘TOP_NODE_UP_URL’ is set, the value of ‘TOP_NODE_UP’ is used for
     the hyperlink text, with ‘(dir)’ as default.  ‘TOP_NODE_UP’ can be
     used in attribute, so should not contain any element.

     For example, in the GNU project <http://www.gnu.org/manual/>
     collects links to most GNU manuals; therefore ‘TOP_NODE_UP_URL’ is
     best specified as ‘/manual/’ if the manual will be installed on
     ‘www.gnu.org’.

     See First Node for more about the Top node pointers.

_images links_
     If ‘IMAGE_LINK_PREFIX’ is set, the associated value is prepended to
     the image file links; default unset.  This could be useful if image
     files are in a specific subdirectory.

   Cross-references between HTML manuals are specified precisely (see
HTML Xref).  Customization of manual locations is provided through the
‘htmlxref.cnf’ file (see HTML Xref Configuration).

   Default directories and file names are used for cross-reference
target manuals not found through HTML Xref Configuration (see HTML Xref Link Basics).
By default, a warning is given for each external
manual not in the HTML Xref configuration files.  If you do not want
warnings about such manuals, you should set ‘CHECK_HTMLXREF’ to ‘0’.
This could be relevant, for example, if you know that manuals are
installed locally.

   You can use customization variables to specify the HTML Xref
Configuration more precisely.  By default, the file name used for HTML
Xref configuration is searched for in directories, and all the files
found are used.  You can set the ‘HTMLXREF_MODE’ customization variable
to modify how cross-references to other manuals information is
determined.  If ‘HTMLXREF_MODE’ is set to ‘file’, the file name is
directly used as the source of information.  If ‘HTMLXREF_MODE’ is set
to ‘none’ no information is used.  The default case is obtained with
‘HTMLXREF_MODE’ not defined or set to any other value.  The
‘HTMLXREF_FILE’ customization variable sets the file used for HTML Xref
configuration to another value than the default, ‘htmlxref.cnf’.  If
‘HTMLXREF_FILE’ contains directories, it is loaded if found, but is not
searched for in directories.  By default, the distant manual is
considered to be split or monolithic based on the splitting of the
manual being output.  You can set it explicitly, instead, by setting
‘EXTERNAL_CROSSREF_SPLIT’.

   There are also customization variables that modify various other
aspects of cross-references:

   • You can set the file name used for the Top node in cross-references
     by setting the ‘TOP_NODE_FILE_TARGET’ customization variable value;
     default is ‘index.html’.

   • You specify a base directory for external manuals with
     ‘EXTERNAL_DIR’; in the default case, there is none.

   • Similarly, you set the file extension for cross-references to other
     manuals with ‘EXTERNAL_CROSSREF_EXTENSION’, which, if unset, is
     based on ‘EXTENSION’.  You can change the maximum length of a base
     file name by setting ‘BASEFILENAME_LENGTH’; by default, the base
     file names are truncated to 245 characters (see HTML Xref Link Basics).

However, in general use of these will make cross-manual references
"invalid" in the sense that the generated URL will not link to the
external manual, unless this manual was itself also produced using the
corresponding customization.  It is therefore, in general, better to use
HTML Xref Configuration only.

21.8.3 Customization of Navigation and Headers
----------------------------------------------

Headers and footers with a navigation panel are output in the default
case.  If you use ‘--no-headers’, or if the customization variable
‘HEADERS’ is unset, the navigation panel is only inserted at the
beginning of split files.

   By default, ‘<link>’ elements are generated in the HTML ‘<head>’ to
specify relationships between the HTML page and other resources, for
example the Top node, the next node or the table of contents.  Unset
‘USE_LINKS’ to avoid those elements.

   The ‘<title>’ and the document description in ‘<head>’ are based on
‘@settitle’ (see @settitle).  If the manual is split, the node name
is also added to this HTML title.  Set ‘SECTION_NAME_IN_TITLE’ to use
the argument of the associated chapter structuring command instead of
the node name.

   By default, if an input encoding is set (typically through
‘@documentencoding’), this information is used to set the output
encoding name, otherwise the output encoding is based on the default
encoding.  A ‘<meta>’ tag is output, in the ‘<head>’ section of the
HTML, to specify the output encoding.  See @documentencoding.  To
set the output encoding explicitly, set ‘OUTPUT_ENCODING_NAME’.  The
specified encoding should be a normalized charset name usable in HTML,
typically one of the preferred IANA encoding names.

   When output is split at nodes (see HTML Splitting), the
‘WORDS_IN_PAGE’ customization variable value specifies the approximate
minimum page length at which a navigation panel is placed at the bottom
of a page.

   The appearance of the navigation panel is affected by the following
customization variables, all false in the default case:

‘DATE_IN_HEADER’
     Put the document generation date in the header.

‘HEADER_IN_TABLE’
     Use tables for header formatting rather than a simple ‘<div>’.

‘ICONS’
     Use icons for the navigation panel.

‘PROGRAM_NAME_IN_FOOTER’
     If set, output the program name and miscellaneous related
     information in the page footers.

‘VERTICAL_HEAD_NAVIGATION’
     If set, a vertical navigation panel is used.

   Setting ‘ICONS’ is necessary but not sufficient to get icons for
direction buttons, since no button image is specified in the default
case.  In addition, you need to set the ‘ACTIVE_ICONS’ and
‘PASSIVE_ICONS’ customization variables.  You can only do this using an
initialization file (see Invoking texi2any).  See
texi2any_api.

21.8.4 HTML Features Customization
----------------------------------

By default HTML is generated, but you can set ‘USE_XML_SYNTAX’ in order
to generate XML compatible code.  The main difference is that ‘/>’
instead of ‘>’ ends tags such as ‘<img>’ or ‘<link>’ that do not have a
closing tag (such tags create so-called “void elements”).

   To set the “DOCTYPE”, set the ‘DOCTYPE’ customization variable.  The
default is the simple DTD-less DOCTYPE used for HTML5.

   You can set an XML compatible file beginning instead:
     texi2any --html my_manual.texi -c USE_XML_SYNTAX \
        -c DOCTYPE='<?xml version="1.0" encoding="UTF-8"?>
     <!DOCTYPE html>'

   You could also set the DOCTYPE to HTML 4.01 Transitional:
     texi2any --html my_manual.texi -c DOCTYPE=\
     '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
       "http://www.w3.org/TR/html4/loose.dtd">'

   By default, entities are used for doubled single-quote characters
(see Inserting Quotation Marks), and ‘---’ and ‘--’ (see
Conventions).  Set ‘USE_ISO’ to ‘0’ in the unlikely case that you want
a simpler output.  By default textual entities are used when possible.
Set ‘USE_NUMERIC_ENTITY’ to use numeric entities only.  Set
‘OUTPUT_CHARACTERS’ to output accented characters based on the output
encoding instead of entities.

   By default a custom attribute, as allowed by the standard, is used to
provide the target manual name in cross-references.  If it is not
desirable, for example to generate strict XHTML, you can set
‘NO_CUSTOM_HTML_ATTRIBUTE’ to prevent custom attributes being output.

   Copiable links are output for link targets for the definition
commands (see Definition Commands), table commands (see Two-column Tables)
where an index entry is defined and headings.  A link appears
as a '¶' sign that appears when you hover the mouse pointer over the
heading text.  Unset ‘COPIABLE_LINKS’ to prevent copiable links output.

21.8.5 Customization of Inserted HTML Code
------------------------------------------

There are variables to set the HTML code inserted at various points in
the output.

   Opening quote and closing quotes needed, e.g. for ‘@samp’ output, are
set to:

‘&lsquo;’ and ‘&rsquo;’
     By default, with ‘OPEN_QUOTE_SYMBOL’ and ‘CLOSE_QUOTE_SYMBOL’
     undefined.

‘&#8216;’ and ‘&#8217;’
     If you set ‘USE_NUMERIC_ENTITY’.

An opening and closing quote character
     If you set ‘OUTPUT_CHARACTERS’ and the output encoding includes
     that character.

‘OPEN_QUOTE_SYMBOL’ and ‘CLOSE_QUOTE_SYMBOL’
     If you set those customization variables.

   To change the HTML code for breaks (horizontal rule) inserted in
various contexts, set ‘DEFAULT_RULE’, which is used for most horizontal
separators output in the resulting HTML, and set ‘BIG_RULE’ for the
wider separator sometimes used.

   You can set ‘HTML_ROOT_ELEMENT_ATTRIBUTES’ to add attributes to the
‘<html>’ element.  You can define the variable ‘EXTRA_HEAD’ to add text
within the ‘<head>’ HTML element.  Similarly, the value of
‘AFTER_BODY_OPEN’ is added just after ‘<body>’ is output.  These
variables are empty by default.

   You can set the attributes of the ‘<body>’ element by defining the
customization variable ‘BODY_ELEMENT_ATTRIBUTES’.  By default, the
‘lang’ attribute is set to the document language (see
@documentlanguage).

   You can define the variable ‘PRE_BODY_CLOSE’ to add text just before
the HTML ‘</body>’ element.  Nothing is added by default.

   Similarly, the following variables allow for some useful control of
the formatting of the table of contents and the short table of contents:

‘BEFORE_TOC_LINES’
     Inserted before the table of contents text.

‘AFTER_TOC_LINES’
     Inserted after the table of contents text.

‘BEFORE_SHORT_TOC_LINES’
     Inserted before the short table of contents text.

‘AFTER_SHORT_TOC_LINES’
     Inserted after the short table of contents text.

   At the time of writing, the default values of these variables are set
to opening and closing tags for a ‘<div>’ element enclosing the tables
of contents.

21.8.6 HTML Customization of Specific Output
--------------------------------------------

The output of specific constructs is customizable.

   In HTML, heading levels translate to ‘<hN>’ elements where N is the
heading level.  The following header levels are customizable:

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

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

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

   You may modify the appearance of various constructs by setting:

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

‘INDENTED_BLOCK_COMMANDS_IN_TABLE’
     If set, use tables for indentation of indented block commands;
     default false.

‘INDEX_ENTRY_COLON’
     Symbol used between the index entry and the associated node or
     section; default is an empty string.

‘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 is undefined and set to ‘&bull;’
     if ‘USE_NUMERIC_ENTITY’ is not set, and to ‘&#8217;’ if set.

‘NUMBER_FOOTNOTES’
‘NO_NUMBER_FOOTNOTE_SYMBOL’
     By default footnotes are numbered.  With ‘--no-number-footnotes’ or
     if ‘NUMBER_FOOTNOTES’ is set to 0, a ‘*’ is used instead, or the
     ‘NO_NUMBER_FOOTNOTE_SYMBOL’ customization variable value, if set.

21.8.7 HTML Customization for Math
----------------------------------

You can select various methods to render math in HTML (see Inserting Math).
This is controlled by the ‘HTML_MATH’ customization variable.
By default, the customization variable is unset and the HTML output is
only emphasized.  You may select other options in order to display
properly formatted mathematics.  For some of these options, if you set
‘--iftex’, ‘@tex’ sections are converted to HTML, and if you set
‘--iflatex’ ‘@latex’ sections are converted to HTML.

‘l2h’
     Use the ‘latex2html’ program to produce image files for
     mathematical material.

     ‘latex2html’ will process LaTeX math in math commands, including
     TeX math compatible with LaTeX.  ‘latex2html’ is used to translate
     ‘@tex’ and ‘@latex’ sections to HTML if the corresponding sections
     are not ignored.  Note that ‘latex2html’ can only process LaTeX,
     including when processing ‘@tex’ sections.

     Processing with ‘latex2html’ should leave files in the output
     directory, with ‘-l2h’ in their name, in particular a cache file to
     avoid redoing translation HTML if already done.

     See latex2html Customization Variables.

‘mathjax’
     Inserts references in the output files to MathJax scripts to format
     mathematics.  The MathJax option requires JavaScript to be enabled
     in the browser to work.

     MathJax handles LaTeX math, including commonly used TeX math
     compatible with LaTeX.  Some specific constructs (for example some
     uses of ‘\text’) are not supported, but this should not be a
     practical issue.

     If math commands are actually processed, a JavaScript license web
     label is generated for MathJax scripts (see JavaScript license web labels).

     See MathJax Customization Variables.

‘t4h’
     Use the ‘tex4ht’ program to produce HTML for mathematical material.

     ‘tex4ht’ will process LaTeX math in math commands, including TeX
     math compatible with LaTeX.  ‘tex4ht’ is used to translate ‘@tex’
     and ‘@latex’ sections to HTML if the sections are not ignored.  The
     ‘@tex’ sections are processed in TeX mode, while the ‘@latex’
     sections are processed as LaTeX.

     Processing with ‘tex4ht’ should leave files in the output
     directory, with ‘_tex4ht’ in their name.

     See tex4ht Customization Variables.

   By default, with ‘CONVERT_TO_LATEX_IN_MATH’ undefined, setting
‘HTML_MATH’ also sets ‘CONVERT_TO_LATEX_IN_MATH’.  In that case Texinfo
@-commands inside ‘@math’ and ‘@displaymath’ are converted to LaTeX,
before converting the ‘@math’ or ‘@displaymath’ to HTML.

21.8.7.1 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_CONFIGURATION’
     Data to add to the global ‘MathJax’ configuration object.  Specify
     as a comma-separated list of ‘COMPONENT: { NAME: VALUE, ... }’
     pairs.

     For example, you could set ‘MATHJAX_CONFIGURATION’ to

          options: { enableMenu: false },
          loader: {
              load: [\'[tex]/physics\'],
              versionWarnings: false
          },
          tex: {
            packages: {\'[+]\': [\'physics\']}
          }

     to disable the MathJax right-click menu, and to load the MathJax
     ‘physics’ extension.  (See Configuring MathJax
     (https://docs.mathjax.org/en/latest/options/index.html) in the
     MathJax documentation.)

     If you override any of the defaults for this configuration output
     by ‘texi2any’ you should make sure that your new settings align
     with the HTML output produced by ‘texi2any’.

‘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 JavaScript license web labels).

     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.

21.8.7.2 ‘latex2html’ Customization Variables
.............................................

This table lists the customization variables which can be used when
‘latex2html’ is being used to convert ‘@math’, ‘@displaymath’, ‘@latex’
and ‘@tex’ sections for HTML.  These customization variables are
relevant only if ‘HTML_MATH’ is set to ‘l2h’.

   To actually convert ‘@tex’ sections, ‘--iftex’ should be used, and to
actually convert ‘@latex’ sections, ‘--iflatex’ should be used.

‘L2H_CLEAN’
     If set, the intermediate files generated in relation with
     ‘latex2html’ are removed; default true.

‘L2H_FILE’
     If set, the given file is used as ‘latex2html’'s init file; default
     unset.

‘L2H_HTML_VERSION’
     The HTML version used in the ‘latex2html’ call; default unset.

‘L2H_L2H’
     The program invoked as ‘latex2html’; default is ‘latex2html’.

‘L2H_SKIP’
     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’
     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.

21.8.7.3 ‘tex4ht’ Customization Variables
.........................................

This table lists the customization variables which can be used when
‘tex4ht’ is being used to convert ‘@math’, ‘@displaymath’, ‘@tex’ and
‘@latex’ sections for HTML.  These customization variables are relevant
only if ‘HTML_MATH’ is set to ‘t4h’.

   To actually convert ‘@tex’ sections, ‘--iftex’ should be used, and to
actually convert ‘@latex’ sections, ‘--iflatex’ should be used.

‘T4H_LATEX_CONVERSION’
     If set, the conversion type used for ‘@latex’ sections.
     Possibilities are ‘latex’, ‘tex’ and ‘texi’.  Set to ‘latex’ if not
     defined.

‘T4H_MATH_CONVERSION’
     If set, the conversion type used for ‘@math’ and ‘@displymath’.
     Possibilities are ‘latex’, ‘tex’ and ‘texi’.  Set to ‘tex’ if not
     defined.

‘T4H_TEX_CONVERSION’
     If set, the conversion type used for ‘@tex’ sections.
     Possibilities are ‘latex’, ‘tex’ and ‘texi’.  Set to ‘tex’ if not
     defined.

21.8.8 JavaScript Interface and Licenses
----------------------------------------

You can add an experimental JavaScript browsing interface to the HTML
output by setting ‘INFO_JS_DIR’ value to the name of a directory in
which to place the code for this interface.  For example, ‘texi2any
--html -c INFO_JS_DIR=js MANUAL.texi’ places files in a ‘js’ directory
under the output.  This interface 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.

   By default, a “JavaScript license web labels page” is set up to give
licensing information and source code for any JavaScript used by the
HTML output (see <https://www.gnu.org/licenses/javascript-labels.html>).
To avoid generating a JavaScript license web labels page, set
‘JS_WEBLABELS’ to ‘omit’.  With ‘JS_WEBLABELS’ set to ‘generate’, the
default, generate a labels page at ‘JS_WEBLABELS_FILE’,
‘js_licenses.html’ in the default case, and link to it in the HTML
output files.  With ‘JS_WEBLABELS’ set to ‘reference’, link to the
labels file given by ‘JS_WEBLABELS_FILE’ in the output, and do not
generate a labels file.  This last setting is useful if you separately
maintain a single labels file for a larger website that includes your
manual.

   Labels files can be generated if ‘INFO_JS_DIR’ is set, or if
‘HTML_MATH’ is set to ‘mathjax’ (see MathJax scripts).

21.8.9 HTML Customization Variables List
----------------------------------------

This table lists the customization variables which apply to HTML output.

‘AFTER_BODY_OPEN’
     Text added at the beginning of each HTML file; default unset.

‘AFTER_SHORT_TOC_LINES’
‘AFTER_TOC_LINES’
     Text output after the short table of contents for
     ‘AFTER_SHORT_TOC_LINES’ and after the table of contents for
     ‘AFTER_TOC_LINES’ if set; otherwise, a default string is used.  At
     the time of writing, a ‘</div>’ element is closed.

     In general, you should set ‘BEFORE_SHORT_TOC_LINES’ if
     ‘AFTER_SHORT_TOC_LINES’ 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_SHORT_TOC_LINES’
‘BEFORE_TOC_LINES’
     If set, text output before the short table of contents for
     ‘BEFORE_SHORT_TOC_LINES’ 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_SHORT_TOC_LINES’ if
     ‘BEFORE_SHORT_TOC_LINES’ 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>’.

‘BODY_ELEMENT_ATTRIBUTES’
     The ‘<body>’ attributes text.  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 true.

‘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’.

‘CONVERT_TO_LATEX_IN_MATH’
     If set, try to convert any Texinfo @-commands inside ‘@math’ and
     ‘@displaymath’ to LaTeX, before converting the ‘@math’ or
     ‘@displaymath’ to HTML. Default ‘undef’.  If undefined, set if
     ‘HTML_MATH’ is set.

‘COPIABLE_LINKS’
     If set, output copiable links for the definition commands (see
     Definition Commands), table commands (see Two-column Tables)
     where an index entry is defined and headings.  A link appears as a
     '¶' sign that appears when you hover the mouse pointer over the
     heading text.

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

‘EPUB_CREATE_CONTAINER_FILE’
     If set to 0, do not generate the EPUB output file.  Default is set
     to 1.

‘EPUB_KEEP_CONTAINER_FOLDER’
     If set, keep the directory containing the directories and files
     needed for EPUB.  The EPUB output file is a ZIP archive of this
     directory.  Default is not defined.  Set if not defined and ‘TEST’
     or ‘DEBUG’ is set.  See EPUB Output File and Directory.

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

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

‘EXTERNAL_CROSSREF_EXTENSION’
     File extension for cross-references to other manuals.  If unset,
     based on ‘EXTENSION’.

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

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

‘HIGHLIGHT_SYNTAX’
     If set, ‘@example’ blocks with language information as first
     argument are highlighted in the HTML output.  It is also possible
     to specify a default for the language with
     ‘HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE’.  Syntax highlighting requires
     an external program to generate the highlighted HTML. The
     ‘HIGHLIGHT_SYNTAX’ value allows to select a specific program.  The
     possibilities are ‘highlight’, ‘pygments’, any other value standing
     for ‘source-highlight’ (see Syntax Highlighting).

‘HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE’
     The default language used for syntax highlighting when there is no
     language information.

‘HTML_MATH’
     Method to use to render ‘@math’ (see HTML Customization for Math).
     This can be unset, set to ‘mathjax’ (see MathJax Customization Variables),
     set to ‘l2h’, which uses ‘latex2html’
     (see latex2html Customization Variables), or set to ‘t4h’,
     which uses ‘tex4ht’ (see tex4ht Customization Variables).  By
     default, setting ‘HTML_MATH’ also sets ‘CONVERT_TO_LATEX_IN_MATH’.

‘HTML_ROOT_ELEMENT_ATTRIBUTES’
     Use that string for the ‘<html>’ HTML document root element.
     Default undefined.

‘HTMLXREF_FILE’
     Set the file name used for cross-references to other manuals.  If
     not defined, ‘htmlxref.cnf’ is used (see HTML Xref Configuration).
     Not defined in the default case.  If ‘TEST’ is
     set, ‘HTMLXREF_MODE’ is set to the default and ‘HTMLXREF_FILE’ is
     not defined, information on cross-references to other manuals is
     not used.

     If ‘HTMLXREF_MODE’ is set to ‘file’ the file name is directly used
     as the source of information, otherwise the file name is searched
     for in directories, and all the files found are used (see HTML Xref Configuration).

‘HTMLXREF_MODE’
     How cross-references to other manuals information is determined.
     If set to ‘none’, no information is used.  If set to ‘file’, the
     information is determined from a file path, ‘htmlxref.cnf’ in the
     default case, or the value of ‘HTMLXREF_FILE’.  If not defined (the
     default) or set to any other value, search in directories and use
     all the files (see HTML Xref Configuration).

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

‘INDENTED_BLOCK_COMMANDS_IN_TABLE’
     If set, use tables for indentation of indented block commands;
     default false.

‘INDEX_ENTRY_COLON’
     Symbol used between the index entry and the associated node or
     section; default is an empty string.

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

‘IGNORE_REF_TO_TOP_NODE_UP’
     Ignore references to ‘TOP_NODE_UP’, the up node for the Top node.

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

‘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 is undefined and set to ‘&bull;’
     if ‘USE_NUMERIC_ENTITY’ is not set, and to ‘&#8217;’ if set.

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

‘NO_CUSTOM_HTML_ATTRIBUTE’
     Do not output HTML with custom attributes in elements; default
     false.

‘NO_NUMBER_FOOTNOTE_SYMBOL’
     Symbol used for footnotes if ‘NUMBER_FOOTNOTES’ is false.  Default
     is ‘*’.

‘NODE_NAME_IN_INDEX’
     If true, use node names in index entries, otherwise prefer section
     names.  If undefined, use ‘USE_NODES’ value in HTML. Default is
     undefined.

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

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

‘PROGRAM_NAME_IN_ABOUT’
     Used when an About element is output.  If set, output the program
     name and miscellaneous related information in About special
     element; default false.

‘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’.

‘SHORT_TOC_LINK_TO_TOC’
     If set, the cross-references in the Short table of contents links
     to the corresponding Table of Contents entries, if a Table of
     Contents is output; default true.

‘SHOW_BUILTIN_CSS_RULES’
     Output the built-in default CSS rules on the standard output and
     exit.

‘SHOW_TITLE’
     If set, output the title at the beginning of the document; default
     ‘undef’.  If set to ‘undef’, setting ‘NO_TOP_NODE_OUTPUT’ also sets
     ‘SHOW_TITLE’ for HTML.

‘TEXI2HTML’
     Generate HTML and try to be as compatible as possible with
     ‘texi2html’; default false.

‘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 overriding
     the Up pointer name in case ‘TOP_NODE_UP_URL’ is set and for other
     formats, see ‘TOP_NODE_UP’ in Customization Variables for Multiple Formats.
     See File Names and Links Customization for HTML.
     For more about the Top node pointers, see First Node.

‘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_NEXT_HEADING_FOR_LONE_NODE’
     If set, a node not associated with a sectioning command but
     followed by a leading command not usually associated with a node,
     such as ‘@heading’, before other formatted contents does not have
     its name output as a heading, under the assumption that the command
     found provides the heading.  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.

‘USE_TITLEPAGE_FOR_TITLE’
     Use the full ‘@titlepage’ as the title, not a simple title string;
     default true.  Only relevant if ‘SHOW_TITLE’ is set.

‘USE_XML_SYNTAX’
     Use XML/XHTML compatible syntax.

‘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’.

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 printed output processors to refrain from inserting extra
     whitespace after an immediately preceding period, question mark,
     exclamation mark, or colon.  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 printed output.  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.
     See @unnumbered @appendix.

‘@appendixsec TITLE’
‘@appendixsection TITLE’
     Begin an appendix section within an appendix.  The section title
     appears in the table of contents.  ‘@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.  See @unnumberedsubsec @appendixsubsec @subheading.

‘@appendixsubsubsec TITLE’
     Begin an appendix subsubsection.  The title appears in the table of
     contents.  See @subsubsection.

‘@arrow{}’
     Generate a right arrow glyph: ‘→’.  Used by default for ‘@click’.
     See Click Sequences.

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

‘@author AUTHOR’
     Set a manual author in the title page.  See @title @subtitle @author.
     Set a quotation author in ‘@quotation’.  See
     @quotation.

‘@b{TEXT}’
     Set TEXT in a bold font, if possible.  See Fonts.

‘@bullet{}’
     Generate a large round dot, •, or the closest possible thing to
     one.  Often used with ‘@itemize’.  See @bullet.

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

‘@bye’
     Stop processing a file.  The processors 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, if possible.  Pair with ‘@end cartouche’.  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.  See @majorheading @chapheading.

‘@chapter TITLE’
     Begin a numbered chapter.  The chapter title appears in the table
     of contents.  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.  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 or specify that a table of
     content should be output, for formats that may output a table of
     contents.  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 ©.  See @copyright.

‘@defblock’
     Start a block containing definitions.  Pair with ‘@end defblock’.
     See Generic Definition Commands.

‘@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’
     Create a new command ‘@NEWCMD’ for online formats 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.

‘@defline CATEGORY NAME ARGUMENTS...’
     Use within a ‘@defblock’ environment to give the heading prototype
     line for a symbol being defined.  This command does not create any
     index entries.  See Generic 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.

‘@deftypeline CATEGORY DATA-TYPE NAME ARGUMENTS...’
     Use within a ‘@defblock’ environment to give the heading prototype
     line for a symbol being defined, with data types.  This command
     does not create any index entries.  See Generic Definition Commands.

‘@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 category for the manual.  See Directory Category.

‘@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.  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 ('ȷ').  See Inserting Accents.

‘@dots{}’
     Generate an ellipsis, ‘...’.  See @dots.

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

‘@emph{TEXT}’
     Emphasize TEXT.  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’.  ‘@example’ accepts optional
     arguments, separated by commas.  It is recommended to set the first
     argument to the language of the example code.  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 printed output.  See
     Fonts.

‘@footnote{TEXT-OF-FOOTNOTE}’
     Enter a footnote, for a reference that documents or elucidates the
     primary text.  Footnote text is printed at the bottom of the page
     in printed output.  In other formats, footnote text can be output
     in the same node, in a separate node, or simply be marked as being
     footnote text.  See Footnotes.

‘@footnotestyle STYLE’
     Specify a footnote style, either ‘end’ for the end node style or
     ‘separate’ for the separate style.  In the separate style,
     footnotes are put in a separate node or file.  See Footnote Styles.

‘@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.  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, when possible.  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’
‘@iflatex’
‘@ifplaintext’
‘@ifxml’
     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’...  See Conditionals.

‘@ifnotdocbook’
‘@ifnothtml’
‘@ifnotlatex’
‘@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.

‘@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 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’ in ‘@table’, ‘@ftable’, and ‘@vtable’, 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.

‘@latex’
     Enter LaTeX completely.  Pair with ‘@end latex’.  See Raw Formatter Commands.

‘@leq{}’
     Generate a less-than-or-equal sign, '≤'.  See @geq @leq.

‘@linemacro MACRONAME {PARAMS}’
     Define a new macro which takes rest of the line as an argument, and
     expands to a whole number of complete lines.  See Line Macros.

‘@link{NODENAME, LABEL, MANUAL-NAME}’
     Create a plain link with no visible markup or page reference.
     See @link.

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

‘@microtype ON-OFF’
     Turn microtype on or off.  See Microtypography.

‘@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.  Only the first argument is mandatory.  See
     Writing a Node.

‘@nodedescription NODE-DESCRIPTION’
     Provide a short elaboration of the purpose of a node.  See Node Descriptions.

‘@nodedescriptionblock’
     Used to start a longer node description.  Pair with ‘@end
     nodedescriptionblock’.  See Node Descriptions.

‘@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.  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.  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 index for INDEX-NAME.  See Printing Indices & Menus.

‘@pxref{NODE, [ENTRY], [NODE-TITLE], [INFO-FILE], [PRINTED-MANUAL]}’
     Make a reference to be used within parentheses.  Starts with a
     lowercase 'see' in a printed manual.  The first argument is
     mandatory, except for references to whole manuals.  To refer to
     another manual as a whole, the PRINTED-MANUAL and/or the INFO-FILE
     are the only required arguments.  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.  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, if possible.  See Fonts.

‘@raggedright’
     Fill text; left justify every line while leaving the right end
     ragged.  Leave font as is.  Pair with ‘@end raggedright’.  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], [PRINTED-MANUAL]}’
     Make a plain reference that does not start with any special text.
     Follow command with a punctuation mark.  The first argument is
     mandatory, except for references to whole manuals.  To refer to
     another manual as a whole, the PRINTED-MANUAL and/or the INFO-FILE
     are the only required arguments.  See @ref.

‘@registeredsymbol{}’
     Generate the legal symbol ®.  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.
     See @samp.

‘@sansserif{TEXT}’
     Set TEXT in a sans serif font if possible.  See Fonts.

‘@sc{TEXT}’
     Set TEXT in a small caps font if possible, and uppercase in Info.
     See Smallcaps.

‘@section TITLE’
     Begin a section within a chapter.  The section title appears in the
     table of contents.  Within ‘@chapter’ and ‘@appendix’, the section
     title is numbered; within ‘@unnumbered’, the section is unnumbered.
     See @section.

‘@seealso{INDEX-TEXT}’
     Use in an index entry to refer the reader to another relevant index
     entry.  See Advanced Indexing.

‘@seeentry{INDEX-TEXT}’
     Use in an index entry to redirect the reader to another index
     entry.  See Advanced Indexing.

‘@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. 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,
     or specify that a short table of contents should be output.  For
     formats that may output a short table 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.  See Fonts.

‘@smallbook’
     In printed output, use a 7 by 9.25 inch format rather than the
     regular 8.5 by 11 inch format.  See @smallbook.

‘@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’.  See Emphasizing Text.

‘@sub {TEXT}’
     Set TEXT as a subscript.  See Inserting Subscripts and Superscripts.

‘@subentry’
     Use in an index entry to separate parts of a multi-level entry.
     See Advanced Indexing.

‘@subheading TITLE’
     Print an unnumbered subsection-like heading, but omit from the
     table of contents of a printed manual.  See @unnumberedsubsec @appendixsubsec @subheading.

‘@subsection TITLE’
     Begin a subsection within a section.  The subsection title appears
     in the table of contents.  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.  See @subsubsection.

‘@subsubsection TITLE’
     Begin a subsubsection within a subsection.  The subsubsection title
     appears in the table of contents.  Same context-dependent numbering
     as ‘@section’.  See @subsubsection.

‘@subtitle TITLE’
     Set a subtitle for the title page.  See @title @subtitle @author.

‘@summarycontents’
     Print or specify 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, if possible.
     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’
‘@thissection’
‘@thissectionname’
‘@thissectionnum’
‘@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 number and name of the current section, the
     current section name only, the current section number only, the
     file name, the current page number, and the title of the document.
     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
     'o͡o'.  See Inserting Accents.

‘@tindex ENTRY’
     Add ENTRY to the index of data types.  See Defining the Entries of an Index.

‘@title TITLE’
     Set the title for the title page.  See @title @subtitle @author.

‘@titlefont{TEXT}’
     Print TEXT in a larger than normal font, if possible.  See
     @titlefont @center @sp.

‘@titlepage’
     Begin the title page.  Write the command on a line of its own,
     paired with ‘@end titlepage’.  The title page is not output, in the
     default case, in online formats.  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 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.  See @unnumbered @appendix.

‘@unnumberedsec TITLE’
     Begin a section that appears without section numbers of any kind.
     The title appears in the table of contents.  See @unnumberedsec @appendixsec @heading.

‘@unnumberedsubsec TITLE’
     Begin an unnumbered subsection.  The title appears in the table of
     contents.  See @unnumberedsubsec @appendixsubsec @subheading.

‘@unnumberedsubsubsec TITLE’
     Begin an unnumbered subsubsection.  The title appears in the table
     of contents.  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’.)  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], [PRINTED-MANUAL]}’
     Make a reference that starts with 'See' in a printed manual.
     Follow command with a punctuation mark.  The first argument is
     mandatory, except for references to whole manuals.  To refer to
     another manual as a whole, the PRINTED-MANUAL and/or the INFO-FILE
     are the only required arguments.  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.

A.3 @-Command Contexts
======================

Here we describe approximately which @-commands can be used in which
contexts.  It is not exhaustive or meant to be a complete reference.
Discrepancies between the information here and the Texinfo processors
implementations are most likely to be resolved in favor of the
implementations.

   By “general text” below, we mean anything except sectioning and other
such outer-level document commands, such as ‘@section’, ‘@node’, and
‘@setfilename’.

   ‘@c’, ‘@comment’ and ‘@if ... @end if’ conditional commands may
appear anywhere (except the conditionals must still be on lines by
themselves).  ‘@caption’ and ‘@shortcaption’ may only appear in ‘@float’
but may contain general text.  ‘@footnote’ content likewise.

   @-commands with braces marking text (such as ‘@strong’, ‘@sc’,
‘@asis’) may contain raw formatter commands such as ‘@html’ but no other
block commands (other commands terminated by ‘@end’) and may not be
split across paragraphs, but may otherwise contain general text.

   In addition to the block command restriction, on ‘@center’, ‘@exdent’
and ‘@item’ in ‘@table’ lines, @-commands that makes only sense in a
paragraph are not accepted, such as ‘@indent’.

   In addition to the above, sectioning commands cannot contain
‘@anchor’, ‘@footnote’ or ‘@verb’.

   In addition to the above, remaining commands (‘@node’, ‘@anchor’,
‘@printindex’, ‘@ref’, ‘@math’, ‘@cindex’, ‘@url’, ‘@image’, and so on)
cannot contain cross-reference commands (‘@ref’, ‘@xref’, ‘@pxref’ and
‘@inforef’).

   For precise and complete information, we suggest looking into the
test suite in the sources, which exhaustively tries combinations.

A.4 Obsolete @-Commands
=======================

Here are Texinfo @-commands which are obsolete or have been removed
completely.  This section is for historical purposes.

‘@refill’
     This command used to refill and indent the paragraph after all the
     other processing has been done.  It is no longer needed, since all
     formatters now automatically refill as needed, but you may still
     see it in the source to some manuals, as it does no harm.

‘@setcontentsaftertitlepage’
     In the past, the contents commands were sometimes placed at the end
     of the file, after any indices and just before the ‘@bye’, but we
     no longer recommend this.  This command could be used by a user
     printing a manual, to force the contents to be printed after the
     title page (after the ‘@end titlepage’ line) even if the
     ‘@contents’ command was at the end of the manual.

‘@setshortcontentsaftertitlepage’
     This placed the short table of contents after the ‘@end titlepage’
     command even if the ‘@shortcontents’ command was at the end.

Appendix B Tips and Hints
*************************

Here are some tips for writing Texinfo documentation:

   • Write in the present tense, not in the past or the future.

   • Write actively!  For example, write "We recommend that ..." rather
     than "It is recommended that ...".

   • Use 70 or 72 as your fill column.  Longer lines are hard to read.

   • Include a copyright notice and copying permissions.

   • Design your manual so that it can be read sequentially, as far as
     possible.  People tire of flipping back and forth to find
     information that should be presented to them as they need it.

Index, Index, Index!
....................

Write many index entries, in different ways.  Readers like indices; they
are helpful and convenient.

   Although it is easiest to write index entries as you write the body
of the text, some people prefer to write entries afterwards.  In either
case, write an entry before the paragraph to which it applies.  This
way, an index entry points to the first page of a paragraph that is
split across pages.

   Here are more index-related hints we have found valuable:

   • Write each index entry differently, so each entry refers to a
     different place in the document.

   • Write index entries only where a topic is discussed significantly.
     For example, it is not useful to index "debugging information" in a
     chapter on reporting bugs.  Someone who wants to know about
     debugging information will certainly not find it in that chapter.

   • Consistently capitalize the first word of every concept index
     entry, or else consistently use lowercase.  Terse entries often
     call for lowercase; longer entries for capitalization.  Whichever
     case convention you use, please use one or the other consistently!
     Mixing the two styles looks bad.

   • Always capitalize or use uppercase for those words in an index for
     which this is proper, such as names of countries or acronyms.
     Always use the appropriate case for case-sensitive names, such as
     those in C or Lisp.

   • Write the indexing commands that refer to a whole section
     immediately after the section command, and write the indexing
     commands that refer to a paragraph before that paragraph.

     In the example that follows, a blank line comes after the index
     entry for "Leaping":

          @section The Dog and the Fox
          @cindex Jumping, in general
          @cindex Leaping

          @cindex Dog, lazy, jumped over
          @cindex Lazy dog jumped over
          @cindex Fox, jumps over dog
          @cindex Quick fox jumps over dog
          The quick brown fox jumps over the lazy dog.

     (Note that the example shows entries for the same concept that are
     written in different ways--‘Lazy dog’, and ‘Dog, lazy’--so readers
     can look up the concept in different ways.)

Blank Lines
...........

   • Insert a blank line between a sectioning command and the first
     following sentence or paragraph, or between the indexing commands
     associated with the sectioning command and the first following
     sentence or paragraph, as shown in the tip on indexing.  It makes
     the source easier to read.

   • Always insert a blank line before a ‘@table’ command and after an
     ‘@end table’ command; but never insert a blank line after an
     ‘@table’ command.

     For example,

          Types of fox:

          @table @samp
          @item Quick
          Jump over lazy dogs.

          @item Brown
          Also jump over lazy dogs.
          @end table

          @noindent
          On the other hand, ...

     Insert blank lines before and after ‘@itemize’ ... ‘@end itemize’
     and ‘@enumerate’ ... ‘@end enumerate’ in the same way.

Complete Phrases
................

Complete phrases are easier to read than ...

   • Write entries in an itemized list as complete sentences; or at
     least, as complete phrases.  Incomplete expressions ... awkward ...
     like this.

   • Write the prefatory sentence or phrase for a multi-item list or
     table as a complete expression.  Do not write "You can set:";
     instead, write "You can set these variables:".  The former
     expression sounds cut off.

Editions, Dates and Versions
............................

Include edition numbers, version numbers, and dates in the ‘@copying’
text (for people reading the Texinfo file, and for the legal copyright
in the output files).  Then use ‘@insertcopying’ in the ‘@titlepage’
section for people reading the printed output (see Short Sample).

   It is easiest to handle such version information using ‘@set’ and
‘@value’.  See @value Example, and GNU Sample Texts.

Definition Commands
...................

Definition commands are ‘@deffn’, ‘@defun’, ‘@defmac’, and the like, and
enable you to write descriptions in a uniform format.

   • Write just one definition command for each entity you define with a
     definition command.  The automatic indexing feature creates an
     index entry that leads the reader to the definition.

   • Use ‘@table’ ... ‘@end table’ in an appendix that contains a
     summary of functions, not ‘@deffn’ or other definition commands.

Capitalization
..............

   • Capitalize "Texinfo"; it is a name.  Do not write the ‘x’ or ‘i’ in
     uppercase.

   • Capitalize "Info"; it is a name.

   • Write TeX using the ‘@TeX{}’ command.  Note the uppercase ‘T’ and
     ‘X’.  This command causes the formatters to typeset the name
     according to the wishes of Donald Knuth, who wrote TeX.  (Likewise
     ‘@LaTeX{}’ for LaTeX.)

Spaces
......

Do not use spaces to format a Texinfo file, except inside of ‘@example’
... ‘@end example’ and other literal environments and commands.

   For example, TeX fills the following:

        @kbd{C-x v}
        @kbd{M-x vc-next-action}
           Perform the next logical operation
           on the version-controlled file
           corresponding to the current buffer.

so it looks like this:

     'C-x v' 'M-x vc-next-action' Perform the next logical operation on
     the version-controlled file corresponding to the current buffer.

In this case, the text should be formatted with ‘@table’, ‘@item’, and
‘@itemx’, to create a table.

@code, @samp, @var, and ‘---’
.............................

   • Use ‘@code’ around Lisp symbols, including command names.  For
     example,

          The main function is @code{vc-next-action}, ...

   • Avoid putting letters such as ‘s’ immediately after an ‘@code’.
     Such letters look bad.

   • Use ‘@var’ around meta-variables.  Do not write angle brackets
     around them.

   • Use three hyphens in a row, ‘---’, to indicate a long dash.  The
     Info formatter reduces three hyphens to two; a long dash is typeset
     in other output formats.

Periods Outside of Quotes
.........................

Place periods and other punctuation marks _outside_ of quotations,
unless the punctuation is part of the quotation.  This practice goes
against some publishing conventions in the United States, but enables
the reader to distinguish between the contents of the quotation and the
whole passage.

   For example, you should write the following sentence with the period
outside the end quotation marks:

     Evidently, ‘au’ is an abbreviation for ``author''.

since ‘au’ does _not_ serve as an abbreviation for ‘author.’ (with a
period following the word).

Introducing New Terms
.....................

   • Introduce new terms so that a reader who does not know them can
     understand them from context; or write a definition for the term.

     For example, in the following, the terms "check in", "register" and
     "delta" are all appearing for the first time; the example sentence
     should be rewritten so they are understandable.

          The major function assists you in checking in a file to your
          version control system and registering successive sets of
          changes to it as deltas.

   • Use the ‘@dfn’ command around a word being introduced, to indicate
     that the reader should not expect to know the meaning already, and
     should expect to learn the meaning from this passage.

Program Invocation Nodes
........................

You can invoke programs such as Emacs, GCC, and ‘gawk’ from a shell.
The documentation for each program should contain a section that
describes this.  Unfortunately, if the node names and titles for these
sections are all different, they are difficult for users to find.

   So, there is a convention to name such sections with a phrase
beginning with the word 'Invoking', as in 'Invoking Emacs'; this way,
users can find the section easily.

ANSI C Syntax
.............

When you use ‘@example’ to describe a C function's calling conventions,
use the ANSI C syntax, like this:

     void dld_init (char *@var{path});

And in the subsequent discussion, refer to the argument values by
writing the same argument names, again highlighted with ‘@var’.

   Avoid the obsolete style that looks like this:

     #include <dld.h>

     dld_init (path)
       char *path;

   Also, it is best to avoid writing ‘#include’ above the declaration
just to indicate that the function is declared in a header file.  The
practice may give the misimpression that the ‘#include’ belongs near the
declaration of the function.  Either state explicitly which header file
holds the declaration or, better yet, name the header file used for a
group of functions at the beginning of the section that describes the
functions.

Node Length
...........

Keep nodes (sections) to a reasonable length, whatever reasonable might
be in the given context.  Don't hesitate to break up long nodes into
subnodes and have an extensive tree structure; that's what it's there
for.  Many times, readers will probably try to find a single specific
point in the manual, using search, indexing, or just plain guessing,
rather than reading the whole thing from beginning to end.

   You can use the ‘texi-elements-by-size’ utility to see a list of all
nodes (or sections) in the document, sorted by size (either lines or
words), to find candidates for splitting.  It's in the ‘util/’
subdirectory of the Texinfo sources.

Bad Examples
............

Here are several examples of bad writing to avoid:

   In this example, say, " ... you must ‘@dfn’{check in} the new
version."  That flows better.

     When you are done editing the file, you must perform a ‘@dfn’{check
     in}.

   In the following example, say, "... makes a unified interface such as
VC mode possible."

     SCCS, RCS and other version-control systems all perform similar
     functions in broadly similar ways (it is this resemblance which
     makes a unified control mode like this possible).

   And in this example, you should specify what 'it' refers to:

     If you are working with other people, it assists in coordinating
     everyone's changes so they do not step on each other.

And Finally ...
...............

   • Pronounce TeX as if the ‘X’ were a Greek 'chi', as the last sound
     in the name 'Bach'.  But pronounce Texinfo as in 'speck':
     "teckinfo".

   • Write notes for yourself at the very end of a Texinfo file after
     the ‘@bye’.  None of the processors process text after the ‘@bye’;
     it is as if the text were within ‘@ignore’ ... ‘@end ignore’.

Appendix C Sample Texinfo Files
*******************************

This appendix includes texts to be used in GNU manuals.

C.1 GNU Sample Texts
====================

Following is a sample Texinfo document with the full texts that should
be used (adapted as necessary) in GNU manuals.

   As well as the legal texts, it also serves as a practical example of
how many elements in a GNU system can affect the manual.  If you're not
familiar with all these different elements, don't worry.  They're not
required and a perfectly good manual can be written without them.
They're included here nonetheless because many manuals do (or could)
benefit from them.

   See Short Sample, for a minimal example of a Texinfo file.

   Here are some notes on the example:

   • The ‘version.texi’ in the ‘@include’ command is maintained
     automatically by Automake (see Texinfo (automake)).  It sets the
     ‘VERSION’, ‘UPDATED’ and ‘UPDATED-MONTH’ values used elsewhere.  If
     your distribution doesn't use Automake, but you do use Emacs, you
     may find the ‘time-stamp.el’ package helpful (see Time Stamps (emacs)).

   • The ‘@syncodeindex’ command reflects the recommendation to use only
     one index where possible, to make it easier for readers to look up
     index entries.

   • The ‘@dircategory’ specify a category for the manual.  It is used
     for constructing the Info directory.  See Directory Category,
     which includes a variety of recommended category names.  See
     Installing Dir Entries.

   • The 'Invoking' node is a GNU standard to help users find the basic
     information about command-line usage of a given program.  See
     Manual Structure Details (standards).

   • This sample shows how to includes the FDL in a manual using the
     ‘@include’ command.  The ‘fdl.texi’ file is available in the
     Texinfo and other GNU source distributions.  It is also available
     on the GNU website (at <https://www.gnu.org/licenses/fdl-1.3.html>)
     along with guidance for using it.

   • If the FSF is not the copyright holder, then use the appropriate
     name.

   • For documents that express your personal views, feelings or
     experiences, it is more appropriate to use a license permitting
     only verbatim copying, rather than the FDL.  See Verbatim Copying License.

   Here is the sample document:

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@include version.texi
@settitle GNU Sample @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
which is an example in the Texinfo documentation.

Copyright @copyright{} 2016 Free Software Foundation, Inc.

@quotation
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''.
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* sample: (sample)Invoking sample.
@end direntry

@titlepage
@title GNU Sample
@subtitle for version @value{VERSION}, @value{UPDATED}
@author A.U. Thor (@email{bug-sample@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@node Top
@top GNU Sample

This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).

@menu
* Invoking sample::
* GNU Free Documentation License::
* Index::
@end menu

@node Invoking sample
@chapter Invoking sample

@pindex sample
@cindex invoking @command{sample}

This is a sample manual.  There is no sample program to
invoke, but if there were, you could see its basic usage
and command line options here.

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@node Index
@unnumbered Index

@printindex cp

@bye

C.2 Verbatim Copying License
============================

For software manuals and other documentation, it is critical to use a
license permitting free redistribution and updating, so that when a free
program is changed, the documentation can be updated as well.

   On the other hand, for documents that express your personal views,
feelings or experiences, it is more appropriate to use a license
permitting only verbatim copying.

   Here is a sample text for such a license permitting verbatim copying
only.  This is just the license text itself.  For a complete sample
document, see the previous sections.

@copying
This document is a sample for allowing verbatim copying only.

Copyright @copyright{} 2016 Free Software Foundation, Inc.

@quotation
Permission is granted to make and distribute verbatim copies
of this entire document without royalty provided the
copyright notice and this permission notice are preserved.
@end quotation
@end copying

C.3 All-permissive Copying License
==================================

For software manuals and other documentation, it is important to use a
license permitting free redistribution and updating, so that when a free
program is changed, the documentation can be updated as well.

   On the other hand, for small supporting files, short manuals (under
300 lines long) and rough documentation (README files, INSTALL files,
etc.), the full FDL would be overkill.  They can use a simple
all-permissive license.

   Here is a sample text for such an all-permissive license.  This is
just the license text itself.  For a complete sample document, see the
previous sections.

     Copyright @copyright{} 2016 Free Software Foundation, Inc.

     Copying and distribution of this file, with or without modification,
     are permitted in any medium without royalty provided the copyright
     notice and this notice are preserved.

Appendix D Using Texinfo Mode
*****************************

You may edit a Texinfo file with any text editor you choose.  A Texinfo
file is no different from any other ASCII file.  However, GNU Emacs
comes with a special mode, called Texinfo mode, that provides Emacs
commands and tools to help ease your work.

D.1 Texinfo Mode Overview
=========================

Texinfo mode provides special features for working with Texinfo files.
You can:

   • Insert frequently used @-commands.

   • Automatically create ‘@node’ lines.

   • Show the structure of a Texinfo source file.

   • Automatically create or update the 'Next', 'Previous', and 'Up'
     pointers of a node.

   • Automatically create or update menus.

   • Automatically create a master menu.

   • Format a part or all of a file for Info.

   • Typeset and print part or all of a file.

   Perhaps the two most helpful features are those for inserting
frequently used @-commands and for creating node pointers and menus.

D.2 The Usual GNU Emacs Editing Commands
========================================

In most cases, the usual Text mode commands work the same in Texinfo
mode as they do in Text mode.  Texinfo mode adds new editing commands
and tools to GNU Emacs' general purpose editing features.  The major
difference concerns filling.  In Texinfo mode, the paragraph separation
variable and syntax table are redefined so that Texinfo commands that
should be on lines of their own are not inadvertently included in
paragraphs.  Thus, the ‘M-q’ (‘fill-paragraph’) command will refill a
paragraph but not mix an indexing command on a line adjacent to it into
the paragraph.

   In addition, Texinfo mode sets the ‘page-delimiter’ variable to the
value of ‘texinfo-chapter-level-regexp’; by default, this is a regular
expression matching the commands for chapters and their equivalents,
such as appendices.  With this value for the page delimiter, you can
jump from chapter title to chapter title with the ‘C-x ]’
(‘forward-page’) and ‘C-x [’ (‘backward-page’) commands and narrow to a
chapter with the ‘C-x n p’ (‘narrow-to-page’) command.  (see
Pages (emacs), for details about the page commands.)

   GNU Emacs automatically enters Texinfo mode when you visit a file
with a ‘.texinfo’, ‘.texi’ or ‘.txi’ extension.  Also, Emacs switches to
Texinfo mode when you visit a file that has ‘-*-texinfo-*-’ in its first
line.  If ever you are in another mode and wish to switch to Texinfo
mode, type ‘M-x texinfo-mode’.

   Like all other Emacs features, you can customize or enhance Texinfo
mode as you wish.  In particular, the keybindings are very easy to
change.  The keybindings described here are the default or standard
ones.

D.3 Inserting Frequently Used Commands
======================================

Texinfo mode provides commands to insert various frequently used
@-commands into the buffer.  You can use these commands to save
keystrokes.

   The insert commands are invoked by typing ‘C-c’ twice and then the
first letter of the @-command:

‘C-c C-c c’
‘M-x texinfo-insert-@code’
     Insert ‘@code{}’ and put the cursor between the braces.

‘C-c C-c d’
‘M-x texinfo-insert-@dfn’
     Insert ‘@dfn{}’ and put the cursor between the braces.

‘C-c C-c e’
‘M-x texinfo-insert-@end’
     Insert ‘@end’ and attempt to insert the correct following word,
     such as ‘example’ or ‘table’.  (This command does not handle nested
     lists correctly, but inserts the word appropriate to the
     immediately preceding list.)

‘C-c C-c i’
‘M-x texinfo-insert-@item’
     Insert ‘@item’ and put the cursor at the beginning of the next
     line.

‘C-c C-c k’
‘M-x texinfo-insert-@kbd’
     Insert ‘@kbd{}’ and put the cursor between the braces.

‘C-c C-c n’
‘M-x texinfo-insert-@node’
     Insert ‘@node’ and a comment line listing the sequence for the
     'Next', 'Previous', and 'Up' nodes.  Leave point after the ‘@node’.

‘C-c C-c o’
‘M-x texinfo-insert-@noindent’
     Insert ‘@noindent’ and put the cursor at the beginning of the next
     line.

‘C-c C-c r’
‘M-x texinfo-insert-dwim-@ref’
     This function and binding were added in Emacs 27.1.  Inserts one of
     ‘@pxref{}’, ‘@xref{}’, or ‘@ref{}’ based on the text around point;
     calling it near an unclosed preceding open parenthesis results in
     ‘@pxref{}’, at the beginning of a sentence or at ‘(point-min)’
     yields ‘@xref{}’, any other location (including inside a word),
     will result in ‘@ref{}’.  A numeric argument says how many words
     the braces should surround.  Puts the cursor between the braces.

‘C-c C-c s’
‘M-x texinfo-insert-@samp’
     Insert ‘@samp{}’ and put the cursor between the braces.

‘C-c C-c t’
‘M-x texinfo-insert-@table’
     Insert ‘@table’ followed by a <SPC> and leave the cursor after the
     <SPC>.

‘C-c C-c v’
‘M-x texinfo-insert-@var’
     Insert ‘@var{}’ and put the cursor between the braces.

‘C-c C-c x’
‘M-x texinfo-insert-@example’
     Insert ‘@example’ and put the cursor at the beginning of the next
     line.

‘C-c C-c {’
‘M-x texinfo-insert-braces’
     Insert ‘{}’ and put the cursor between the braces.

‘C-c }’
‘C-c ]’
‘M-x up-list’
     Move from between a pair of braces forward past the closing brace.
     Typing ‘C-c ]’ is easier than typing ‘C-c }’, which is, however,
     more mnemonic; hence the two keybindings.  (Also, you can move out
     from between braces by typing ‘C-f’.)

   To put a command such as ‘@code{...}’ around an _existing_ word,
position the cursor in front of the word and type ‘C-u 1 C-c C-c c’.
This makes it easy to edit existing plain text.  The value of the prefix
argument tells Emacs how many words following point to include between
braces--‘1’ for one word, ‘2’ for two words, and so on.  Use a negative
argument to enclose the previous word or words.  If you do not specify a
prefix argument, Emacs inserts the @-command string and positions the
cursor between the braces.  This feature works only for those @-commands
that operate on a word or words within one line, such as ‘@kbd’ and
‘@var’.

   This set of insert commands was created after analyzing the frequency
with which different @-commands are used in the ‘GNU Emacs Manual’ and
the ‘GDB Manual’.  If you wish to add your own insert commands, you can
bind a keyboard macro to a key, use abbreviations, or extend the code in
‘texinfo.el’.

   ‘C-c C-c C-d’ (‘texinfo-start-menu-description’) is an insert command
that works differently from the other insert commands.  It inserts a
node's section or chapter title in the space for the description in a
menu entry line.  (A menu entry has three parts, the entry name, the
node name, and the description.  Only the node name is required, but a
description helps explain what the node is about.  See The Parts of a Menu.)

   To use ‘texinfo-start-menu-description’, position point in a menu
entry line and type ‘C-c C-c C-d’.  The command looks for and copies the
title that goes with the node name, and inserts the title as a
description; it positions point at the beginning of the inserted text so
you can edit it.  The function does not insert the title if the menu
entry line already contains a description.

   This command is only an aid to writing descriptions; it does not do
the whole job.  You must edit the inserted text since a title tends to
use the same words as a node name but a useful description uses
different words.

D.4 Showing the Sectioning Structure of a File
==============================================

You can show the sectioning structure of a Texinfo file by using the
‘C-c C-s’ command (‘texinfo-show-structure’).  This command lists the
lines that begin with the @-commands for ‘@chapter’, ‘@section’, and the
like.  It constructs what amounts to a table of contents.  These lines
are displayed in another buffer called the ‘*Occur*’ buffer.  In that
buffer, you can position the cursor over one of the lines and use the
‘C-c C-c’ command (‘occur-mode-goto-occurrence’), to jump to the
corresponding spot in the Texinfo file.

‘C-c C-s’
‘M-x texinfo-show-structure’
     Show the ‘@chapter’, ‘@section’, and such lines of a Texinfo file.

‘C-c C-c’
‘M-x occur-mode-goto-occurrence’
     Go to the line in the Texinfo file corresponding to the line under
     the cursor in the ‘*Occur*’ buffer.

   If you call ‘texinfo-show-structure’ with a prefix argument by typing
‘C-u C-c C-s’, it will list not only those lines with the @-commands for
‘@chapter’, ‘@section’, and the like, but also the ‘@node’ lines.  You
can use ‘texinfo-show-structure’ with a prefix argument to check whether
the 'Next', 'Previous', and 'Up' pointers of an ‘@node’ line are
correct.

   Often, when you are working on a manual, you will be interested only
in the structure of the current chapter.  In this case, you can mark off
the region of the buffer that you are interested in by using the ‘C-x n
n’ (‘narrow-to-region’) command and ‘texinfo-show-structure’ will work
on only that region.  To see the whole buffer again, use ‘C-x n w’
(‘widen’).  (see Narrowing (emacs), for more information about the
narrowing commands.)

   In addition to providing the ‘texinfo-show-structure’ command,
Texinfo mode sets the value of the page delimiter variable to match the
chapter-level @-commands.  This enables you to use the ‘C-x ]’
(‘forward-page’) and ‘C-x [’ (‘backward-page’) commands to move forward
and backward by chapter, and to use the ‘C-x n p’ (‘narrow-to-page’)
command to narrow to a chapter.  See Pages (emacs), for more
information about the page commands.

D.4.1 Using ‘texinfo-show-structure’
------------------------------------

It is not always easy to keep track of the nodes, chapters, sections,
and subsections of a Texinfo file.  This is especially true if you are
revising or adding to a Texinfo file that someone else has written.

   In GNU Emacs, in Texinfo mode, the ‘texinfo-show-structure’ command
lists all the lines that begin with the @-commands that specify the
structure: ‘@chapter’, ‘@section’, ‘@appendix’, and so on.  With an
argument (‘C-u’ as prefix argument, if interactive), the command also
shows the ‘@node’ lines.  The ‘texinfo-show-structure’ command is bound
to ‘C-c C-s’ in Texinfo mode, by default.

   The lines are displayed in a buffer called the ‘*Occur*’ buffer,
indented by hierarchical level.  For example, here is a part of what was
produced by running ‘texinfo-show-structure’ on this manual:

     Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
     unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
     in buffer texinfo.texi.
     ...
     4177:@chapter Nodes
     4198:    @heading Two Paths
     4231:    @section Node and Menu Illustration
     4337:    @section The @code{@@node} Command
     4393:        @subheading Choosing Node and Pointer Names
     4417:        @subsection How to Write a @code{@@node} Line
     4469:        @subsection @code{@@node} Line Tips
     ...

   This says that lines 4337, 4393, and 4417 of ‘texinfo.texi’ begin
with the ‘@section’, ‘@subheading’, and ‘@subsection’ commands
respectively.  If you move your cursor into the ‘*Occur*’ window, you
can position the cursor over one of the lines and use the ‘C-c C-c’
command (‘occur-mode-goto-occurrence’), to jump to the corresponding
spot in the Texinfo file.  See Using Occur (emacs),
for more information about ‘occur-mode-goto-occurrence’.

   The first line in the ‘*Occur*’ window describes the “regular
expression” specified by TEXINFO-HEADING-PATTERN.  This regular
expression is the pattern that ‘texinfo-show-structure’ looks for.
See Using Regular Expressions (emacs), for more information.

   When you invoke the ‘texinfo-show-structure’ command, Emacs will
display the structure of the whole buffer.  If you want to see the
structure of just a part of the buffer, of one chapter, for example, use
the ‘C-x n n’ (‘narrow-to-region’) command to mark the region.  (see
Narrowing (emacs).)  This is how the example used above was generated.
(To see the whole buffer again, use ‘C-x n w’ (‘widen’).)

   If you call ‘texinfo-show-structure’ with a prefix argument by typing
‘C-u C-c C-s’, it will list lines beginning with ‘@node’ as well as the
lines beginning with the @-sign commands for ‘@chapter’, ‘@section’, and
the like.

   You can remind yourself of the structure of a Texinfo file by looking
at the list in the ‘*Occur*’ window; and if you have mis-named a node or
left out a section, you can correct the mistake.

D.4.2 Using ‘occur’
-------------------

Sometimes the ‘texinfo-show-structure’ command produces too much
information.  Perhaps you want to remind yourself of the overall
structure of a Texinfo file, and are overwhelmed by the detailed list
produced by ‘texinfo-show-structure’.  In this case, you can use the
‘occur’ command directly.  To do this, type:

     M-x occur

and then, when prompted, type a “regexp”, a regular expression for the
pattern you want to match.  (see Regular Expressions (emacs).)
The ‘occur’ command works from the current location of the cursor in the
buffer to the end of the buffer.  If you want to run ‘occur’ on the
whole buffer, place the cursor at the beginning of the buffer.

   For example, to see all the lines that contain the word ‘@chapter’ in
them, just type ‘@chapter’.  This will produce a list of the chapters.
It will also list all the sentences with ‘@chapter’ in the middle of the
line.

   If you want to see only those lines that start with the word
‘@chapter’, type ‘^@chapter’ when prompted by ‘occur’.  If you want to
see all the lines that end with a word or phrase, end the last word with
a ‘$’; for example, ‘catching mistakes$’.  This can be helpful when you
want to see all the nodes that are part of the same chapter or section
and therefore have the same 'Up' pointer.

   See Using Occur (emacs), for more
information.

D.5 Updating Nodes and Menus
============================

The ‘texi2any’ command will create an Info file for a hierarchically
organized Texinfo file that lacks 'Next', 'Previous' and 'Up' pointers
(see Writing a Node).  Thus, in general, there is no need for
explicit 'Next', 'Previous', and 'Up' pointers.  In this setting, menus
will be added automatically for nodes without an explicit menu.  (see
Generic Translator texi2any, for more information about ‘texi2any’.)

   If you still want explicit pointers, Texinfo mode provides commands
for automatically creating or updating menus and node pointers.  The
commands are called "update" commands because their most frequent use is
for updating a Texinfo file after you have worked on it; but you can use
them to insert the 'Next', 'Previous', and 'Up' pointers into an ‘@node’
line that has none and to create menus in a file that has none.

D.5.1 The Updating Commands
---------------------------

You can use the updating commands to:

   • insert or update the 'Next', 'Previous', and 'Up' pointers of a
     node,

   • insert or update the menu for a section, and

   • create a master menu for a Texinfo source file.

   You can also use the commands to update all the nodes and menus in a
region or in a whole Texinfo file.

   The updating commands work only with conventional Texinfo files,
which are structured hierarchically like books.  In such files, a line
with a structuring command must follow closely after each ‘@node’ line,
except for the 'Top' ‘@node’ line.

   You can write the structuring command on the line that follows
immediately after an ‘@node’ line or else on the line that follows after
a single ‘@comment’ line or a single ‘@ifinfo’ line.  You cannot
interpose more than one line between the ‘@node’ line and the
structuring command line; and you may interpose only a ‘@comment’ line
or an ‘@ifinfo’ line.

   Commands which work on a whole buffer require that the 'Top' node be
followed by a node with a ‘@chapter’ or equivalent-level command.  The
menu updating commands will not create a main or master menu for a
Texinfo file that has only ‘@chapter’-level nodes!  The menu updating
commands only create menus _within_ nodes for lower level nodes.  To
create a menu of chapters, you must provide a 'Top' node.

   The menu updating commands remove menu entries that refer to other
Info files since they do not refer to nodes within the current buffer.
This is a deficiency.  Rather than use menu entries, you can use cross
references to refer to other Info files.  None of the updating commands
affect cross-references.

   Texinfo mode has five updating commands that are used most often: two
are for updating the node pointers or menu of a single node (or a
region); two are for updating every node pointer and menu in a file; and
one, the ‘texinfo-master-menu’ command, is for creating a master menu
for a complete file, and optionally, for updating every node and menu in
the whole Texinfo file.

   The ‘texinfo-master-menu’ command is the primary command:

‘C-c C-u m’
‘M-x texinfo-master-menu’
     Create or update a master menu that includes all the other menus
     (incorporating the descriptions from pre-existing menus, if any).

     With an argument (prefix argument, ‘C-u,’ if interactive), first
     create or update all the nodes and all the regular menus in the
     buffer before constructing the master menu.  (see The Top Node and Master Menu,
     for more about a master menu.)

     For ‘texinfo-master-menu’ to work, the Texinfo file must have a
     'Top' node and at least one subsequent node.

     After extensively editing a Texinfo file, you can type the
     following:

          C-u M-x texinfo-master-menu
     or
          C-u C-c C-u m

     This updates all the nodes and menus completely and all at once.

   The other major updating commands do smaller jobs and are designed
for the person who updates nodes and menus as he or she writes a Texinfo
file.

   The commands are:

‘C-c C-u C-n’
‘M-x texinfo-update-node’
     Insert the 'Next', 'Previous', and 'Up' pointers for the node that
     point is within (i.e., for the ‘@node’ line preceding point).  If
     the ‘@node’ line has pre-existing 'Next', 'Previous', or 'Up'
     pointers in it, the old pointers are removed and new ones inserted.
     With an argument (prefix argument, ‘C-u’, if interactive), this
     command updates all ‘@node’ lines in the region (which is the text
     between point and mark).

‘C-c C-u C-m’
‘M-x texinfo-make-menu’
     Create or update the menu in the node that point is within.  With
     an argument (‘C-u’ as prefix argument, if interactive), the command
     makes or updates menus for the nodes which are either within or a
     part of the region.

     Whenever ‘texinfo-make-menu’ updates an existing menu, the
     descriptions from that menu are incorporated into the new menu.
     This is done by copying descriptions from the existing menu to the
     entries in the new menu that have the same node names.  If the node
     names are different, the descriptions are not copied to the new
     menu.

‘C-c C-u C-e’
‘M-x texinfo-every-node-update’
     Insert or update the 'Next', 'Previous', and 'Up' pointers for
     every node in the buffer.

‘C-c C-u C-a’
‘M-x texinfo-all-menus-update’
     Create or update all the menus in the buffer.  With an argument
     (‘C-u’ as prefix argument, if interactive), first insert or update
     all the node pointers before working on the menus.

     If a master menu exists, the ‘texinfo-all-menus-update’ command
     updates it; but the command does not create a new master menu if
     none already exists.  (Use the ‘texinfo-master-menu’ command for
     that.)

     When working on a document that does not merit a master menu, you
     can type the following:

          C-u C-c C-u C-a
     or
          C-u M-x texinfo-all-menus-update

     This updates all the nodes and menus.

   The ‘texinfo-column-for-description’ variable specifies the column to
which menu descriptions are indented.  By default, the value is 32
although it can be useful to reduce it to as low as 24.  You can set the
variable via customization (see Customization (emacs)) or with the
‘M-x set-variable’ command (see Examining and Setting Variables (emacs)).

   Also, the ‘texinfo-indent-menu-description’ command may be used to
indent existing menu descriptions to a specified column.  Finally, if
you wish, you can use the ‘texinfo-insert-node-lines’ command to insert
missing ‘@node’ lines into a file.  In particular, you can ignore
‘@node’ lines altogether in your first draft and then use the
‘texinfo-insert-node-lines’ command to create ‘@node’ lines for you.
However, we do not recommend this practice.  It is better to name the
node itself at the same time that you write a segment so you can easily
make cross-references.  Useful cross-references are an especially
important feature of a good Texinfo manual.  (see Other Updating Commands,
for more information.)

D.5.2 Updating Requirements
---------------------------

To use the updating commands, you must organize the Texinfo file
hierarchically with chapters, sections, subsections, and the like.  When
you construct the hierarchy of the manual, do not 'jump down' more than
one level at a time: you can follow the 'Top' node with a chapter, but
not with a section; you can follow a chapter with a section, but not
with a subsection.  However, you may 'jump up' any number of levels at
one time--for example, from a subsection to a chapter.

   Each ‘@node’ line, with the exception of the line for the 'Top' node,
must be followed by a line with a structuring command such as
‘@chapter’, ‘@section’, or ‘@unnumberedsubsec’.

   Each ‘@node’ line/structuring-command line combination must look
either like this:

     @node     Comments,  Minimum, Conventions, Overview
     @comment  node-name, next,    previous,    up
     @section Comments

   or like this (without the ‘@comment’ line):

     @node Comments, Minimum, Conventions, Overview
     @section Comments

   or like this (without the explicit node pointers):

     @node Comments
     @section Comments

In this example, 'Comments' is the name of both the node and the
section.  The next node is called 'Minimum' and the previous node is
called 'Conventions'.  The 'Comments' section is within the 'Overview'
node, which is specified by the 'Up' pointer.

   If a file has a 'Top' node, it must be called ‘top’ or ‘Top’ and be
the first node in the file.

   The menu updating commands create a menu of sections within a
chapter, a menu of subsections within a section, and so on.  This means
that you must have a 'Top' node if you want a menu of chapters.

D.5.3 Update Outer File and Include Files
-----------------------------------------

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.

   With ‘C-u’ as a prefix argument, create and insert a master menu in
the outer file.  With a numeric prefix argument, such as ‘C-u 2’, first
update all the menus and all the 'Next', 'Previous', and 'Up' pointers
of all the included files before creating and inserting a master menu in
the outer file.

   In more details:

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

D.5.4 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.

D.5.5 Other Updating Commands
-----------------------------

In addition to the major updating commands, Texinfo mode possesses
several less frequently used updating commands:

‘M-x texinfo-insert-node-lines’
     Insert ‘@node’ lines before the ‘@chapter’, ‘@section’, and other
     sectioning commands wherever they are missing throughout a region
     in a Texinfo file.

     With an argument (‘C-u’ as prefix argument, if interactive), the
     command ‘texinfo-insert-node-lines’ not only inserts ‘@node’ lines
     but also inserts the chapter or section titles as the names of the
     corresponding nodes.  In addition, it inserts the titles as node
     names in pre-existing ‘@node’ lines that lack names.  Since node
     names should be more concise than section or chapter titles, you
     must manually edit node names so inserted.

     For example, the following marks a whole buffer as a region and
     inserts ‘@node’ lines and titles throughout:

          C-x h C-u M-x texinfo-insert-node-lines

     This command inserts titles as node names in ‘@node’ lines; the
     ‘texinfo-start-menu-description’ command (see Inserting Frequently Used Commands)
     inserts titles as
     descriptions in menu entries, a different action.  However, in both
     cases, you need to edit the inserted text.

‘M-x texinfo-indent-menu-description’
     Indent every description in the menu following point to the
     specified column.  You can use this command to give yourself more
     space for descriptions.  With an argument (‘C-u’ as prefix
     argument, if interactive), the ‘texinfo-indent-menu-description’
     command indents every description in every menu in the region.
     However, this command does not indent the second and subsequent
     lines of a multi-line description.

‘M-x texinfo-sequential-node-update’
     Insert the names of the nodes immediately following and preceding
     the current node as the 'Next' or 'Previous' pointers regardless of
     those nodes' hierarchical level.  This means that the 'Next' node
     of a subsection may well be the next chapter.  Sequentially ordered
     nodes are useful for novels and other documents that you read
     through sequentially.  (However, in Info, the ‘g *’ command lets
     you look through the file sequentially, so sequentially ordered
     nodes are not strictly necessary.)  With an argument (prefix
     argument, if interactive), the ‘texinfo-sequential-node-update’
     command sequentially updates all the nodes in the region.

D.6 Formatting for Info
=======================

Texinfo mode provides several commands for formatting part or all of a
Texinfo file for Info.

D.6.1 Running ‘texi2any’/‘makeinfo’ Within Emacs
------------------------------------------------

The ‘texi2any’ program provides better error messages than either of the
Emacs formatting commands.  We recommend it.  The ‘texi2any’ program is
independent of Emacs.

   You can run ‘texi2any’ (or ‘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
‘texi2any’ program in a temporary shell buffer.  If ‘texi2any’ 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 ‘texi2any’ 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 ‘texi2any’ 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 ‘texi2any’ (or ‘makeinfo’) job (from
     ‘makeinfo-region’ or ‘makeinfo-buffer’).

‘C-c C-m C-l’
‘M-x makeinfo-recenter-output-buffer’
     Redisplay the ‘texi2any’ 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 ‘texi2any’ 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
texi2any Options.

D.6.2 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 ‘texi2any’ program provides better error checking (see texi2any 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.

D.7 Formatting and Printing with Emacs
======================================

GNU Emacs can be used for formatting and printing with TeX, from an
Emacs Shell.  Texinfo mode also provides predefined key commands for
formatting and printing.

D.7.1 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.

   Often, when you are writing a document, you want to typeset and print
only part of a file to see what it will look like.  You can use the
‘texinfo-tex-region’ and related commands for this purpose.  Use the
‘texinfo-tex-buffer’ command to format all of a buffer.

   For ‘texinfo-tex-region’ or ‘texinfo-tex-buffer’ to work, the file
_must_ start with a ‘\input texinfo’ line and must include a ‘@settitle’
line.  The file must end with ‘@bye’ on a line by itself.  (When you use
‘texinfo-tex-region’, you must surround the ‘@settitle’ line with
start-of-header and end-of-header lines.)

‘C-c C-t C-b’
‘M-x texinfo-tex-buffer’
     Run ‘texi2dvi’ on the buffer.  In addition to running TeX on the
     buffer, this command automatically creates or updates indices as
     needed.

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

     If @-commands related to printed output are between the
     start-of-header and end-of-header lines, then ‘texinfo-tex-region’
     will format the region accordingly.  For example, if you write the
     ‘@smallbook’ command between the start-of-header and end-of-header
     lines, ‘texinfo-tex-region’, will format the region in "small" book
     size.

‘C-c C-t C-i’
‘M-x texinfo-texindex’
     Run ‘texindex’ to sort the indices of a Texinfo file formatted with
     ‘texinfo-tex-region’.  The ‘texinfo-tex-region’ command does not
     run ‘texindex’ automatically; it only runs the ‘tex’ typesetting
     command.  You must run the ‘texinfo-tex-region’ command a second
     time after sorting the raw index files with the ‘texindex’ command.
     (Usually, you do not format an index when you format a region, only
     when you format a buffer.  Now that the ‘texi2dvi’ command exists,
     there is little or no need for this command.)

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

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

D.8 Texinfo Mode Summary
========================

In Texinfo mode, each set of commands has default keybindings that begin
with the same keys.  All the commands that are custom-created for
Texinfo mode begin with ‘C-c’.  The keys are somewhat mnemonic.

Insert Commands
---------------

The insert commands are invoked by typing ‘C-c’ twice and then the first
letter of the @-command to be inserted.  (It might make more sense
mnemonically to use ‘C-c C-i’, for 'custom insert', but ‘C-c C-c’ is
quick to type.)

     C-c C-c c       Insert ‘@code’.
     C-c C-c d       Insert ‘@dfn’.
     C-c C-c e       Insert ‘@end’.
     C-c C-c i       Insert ‘@item’.
     C-c C-c n       Insert ‘@node’.
     C-c C-c s       Insert ‘@samp’.
     C-c C-c v       Insert ‘@var’.
     C-c {       Insert braces.
     C-c ]
     C-c }       Move out of enclosing braces.

     C-c C-c C-d     Insert a node's section title
                    in the space for the description
                    in a menu entry line.

Show Structure
--------------

The ‘texinfo-show-structure’ command is often used within a narrowed
region.

     C-c C-s         List all the headings.

The Master Update Command
-------------------------

The ‘texinfo-master-menu’ command creates a master menu; and can be used
to update every node and menu in a file as well.

     C-c C-u m
     M-x texinfo-master-menu
                    Create or update a master menu.

     C-u C-c C-u m   With ‘C-u’ as a prefix argument, first
                    create or update all nodes and regular
                    menus, and then create a master menu.

Update Pointers
---------------

The update pointer commands are invoked by typing ‘C-c C-u’ and then
either ‘C-n’ for ‘texinfo-update-node’ or ‘C-e’ for
‘texinfo-every-node-update’.

     C-c C-u C-n     Update a node.
     C-c C-u C-e     Update every node in the buffer.

Update Menus
------------

Invoke the update menu commands by typing ‘C-c C-u’ and then either
‘C-m’ for ‘texinfo-make-menu’ or ‘C-a’ for ‘texinfo-all-menus-update’.
To update both nodes and menus at the same time, precede ‘C-c C-u C-a’
with ‘C-u’.

     C-c C-u C-m     Make or update a menu.

     C-c C-u C-a     Make or update all
                    menus in a buffer.

     C-u C-c C-u C-a With ‘C-u’ as a prefix argument,
                    first create or update all nodes and
                    then create or update all menus.

Format for Info
---------------

The Info formatting commands that are written in Emacs Lisp are invoked
by typing ‘C-c C-e’ and then either ‘C-r’ for a region or ‘C-b’ for the
whole buffer.

   The Info formatting commands that are based on the
‘texi2any’/‘makeinfo’ program are invoked by typing ‘C-c C-m’ and then
either ‘C-r’ for a region or ‘C-b’ for the whole buffer.

Use the ‘texinfo-format...’ commands:

     C-c C-e C-r     Format the region.
     C-c C-e C-b     Format the buffer.

Use ‘texi2any’/‘makeinfo’:

     C-c C-m C-r     Format the region.
     C-c C-m C-b     Format the buffer.
     C-c C-m C-l     Recenter the ‘texi2any’ output buffer.
     C-c C-m C-k     Kill the ‘texi2any’ formatting job.

Typeset and Print
-----------------

The TeX typesetting and printing commands are invoked by typing ‘C-c
C-t’ and then another control command: ‘C-r’ for ‘texinfo-tex-region’,
‘C-b’ for ‘texinfo-tex-buffer’, and so on.

     C-c C-t C-r     Run TeX on the region.
     C-c C-t C-b     Run texi2dvi on the buffer.
     C-c C-t C-i     Run texindex.
     C-c C-t C-p     Print the DVI file.
     C-c C-t C-q     Show the print queue.
     C-c C-t C-d     Delete a job from the print queue.
     C-c C-t C-k     Kill the current TeX formatting job.
     C-c C-t C-x     Quit a currently stopped TeX formatting job.
     C-c C-t C-l     Recenter the output buffer.

Other Updating Commands
-----------------------

The remaining updating commands do not have standard keybindings because
they are rarely used.

     M-x texinfo-insert-node-lines
                    Insert missing ‘@node’ lines in region.
                    With ‘C-u’ as a prefix argument,
                    use section titles as node names.

     M-x texinfo-multiple-files-update
                    Update a multi-file document.
                    With ‘C-u 2’ as a prefix argument,
                    create or update all nodes and menus
                    in all included files first.

     M-x texinfo-indent-menu-description
                    Indent descriptions.

     M-x texinfo-sequential-node-update
                    Insert node pointers in strict sequence.

D.9 Direct Formatting of Info files
===================================

In general, there is no need to edit or process Info files.  Most of the
content of Info file is plain text, but the tag tables require computing
offsets for nodes and indirect files (see Tag and Split Files),
which is impractical.  The Texinfo processors output well-formatted Info
from Texinfo input.  Also, lot of information from the Texinfo source is
lost in the Info file.  The Texinfo source is therefore more suitable to
analyse a manual, be it for error reporting, for statistics, or to set
up translations.

   Still, especially with manually written Info files, there are some
situations where it may be interesting to process Info files directly,
in particular to compute Info files node offsets and to compute split
Info files file offsets.  Two Emacs commands do that.  ‘Info-tagify’
adds a tag table for a nonsplit file lacking one.  This function is also
useful for Info file validation (see Running Info-validate).  It is
also possible to split a nonsplit Info file with ‘Info-split’.

D.9.1 Tagifying a File
----------------------

Texinfo processors create tag tables automatically.  The only exception
arise when ‘texinfo-format-buffer’ is called with a prefix, as ‘C-u M-x
texinfo-format-buffer’, to create an non split Info file without a tag
table (which can be useful in some cases for Info file validation, see
Unsplit and Tagify).  Adding a tag table is therefore more generally
useful for manually written Info files.

   To create a tag table for an nonsplit file, visit the Info file you
wish to tagify and type:

     M-x Info-tagify

(Note the uppercase ‘I’ in ‘Info-tagify’.)  This creates an Info file
with a tag table.  A tag table is part of a well formed Info file (see
Tag and Split Files).  A tag table is also needed to validate or split
the Info file.

D.9.2 Splitting a File Manually
-------------------------------

You should split a large file or else let the ‘texinfo-format-buffer’ or
‘makeinfo-buffer’ command do it for you automatically.  (Generally you
will let one of the formatting commands do this job for you.  See Info Formatting.)

   The split-off files are called the indirect subfiles.

   Tag tables are created automatically by the formatting command; you
only need to create a tag table yourself if you are doing the job
manually.  See Tagifying, for information about creating a tag
table.

   Visit the Info file you wish to tagify and split manually and type
the two commands:

     M-x Info-tagify
     M-x Info-split

(Note that the ‘I’ in ‘Info’ is uppercase.)

   When you use the ‘Info-split’ command, the buffer is modified into a
(small) Info file which lists the indirect subfiles.  This file should
be saved in place of the original visited file.  The indirect subfiles
are written in the same directory the original file is in, with names
generated by appending ‘-’ and a number to the original file name.

   The primary file still functions as an Info file, but it contains
just the tag table and a directory of subfiles.  See Tag and Split Files.

D.10 Catching Mistakes
======================

Besides mistakes in the content of your documentation, there are two
kinds of mistake you can make with Texinfo: you can make mistakes with
@-commands, and you can make mistakes with the structure of the nodes
and chapters.

   For finding problems with @-commands, you can run TeX or a region
formatting command on the region that has a problem; indeed, you can run
these commands on each region as you write it.

   For finding problems with the structure of nodes and chapters, you
can use ‘C-c C-s’ (‘texinfo-show-structure’) and the related ‘occur’
command and you can use the ‘M-x Info-validate’ command.

D.10.1 ‘texi2any’ Preferred
---------------------------

The ‘texi2any’ program does an excellent job of catching errors and
reporting them--far better than ‘texinfo-format-region’ or
‘texinfo-format-buffer’.  In addition, the various functions for
automatically creating and updating node pointers and menus remove many
opportunities for human error.

   Use ‘texi2any’ (or its Texinfo mode manifestations, ‘makeinfo-region’
and ‘makeinfo-buffer’) to format your file and check for other errors.
This is the best way to work with Texinfo.  But if you cannot use
‘texi2any’, or your problem is very puzzling, then you may want to use
the tools described in this section.

D.10.2 Catching Errors with Info Formatting
-------------------------------------------

After you have written part of a Texinfo file, you can use the
‘texinfo-format-region’ or the ‘makeinfo-region’ command to see whether
the region formats properly.

   Most likely, however, you are reading this section because for some
reason you cannot use the ‘makeinfo-region’ command; therefore, the rest
of this section presumes that you are using ‘texinfo-format-region’.

   If you have made a mistake with an @-command, ‘texinfo-format-region’
will stop processing at or after the error and display an error message.
To see where in the buffer the error occurred, switch to the ‘*Info
Region*’ buffer; the cursor will be in a position that is after the
location of the error.  Also, the text will not be formatted after the
place where the error occurred (or more precisely, where it was
detected).

   For example, if you accidentally end a menu with the command ‘@end
menus’ with an 's' on the end, instead of with ‘@end menu’, you will see
an error message that says:

     @end menus is not handled by texinfo

The cursor will stop at the point in the buffer where the error occurs,
or not long after it.  The buffer will look like this:

     ---------- Buffer: *Info Region* ----------
     * Menu:

     * Using texinfo-show-structure::  How to use
                                      `texinfo-show-structure'
                                      to catch mistakes.
     * Running Info-validate::         How to check for
                                      unreferenced nodes.
     @end menus
     ⋆
     ---------- Buffer: *Info Region* ----------

   The ‘texinfo-format-region’ command sometimes provides slightly odd
error messages.  For example, the following cross-reference fails to
format:

     (@xref{Catching Mistakes, for more info.)

In this case, ‘texinfo-format-region’ detects the missing closing brace
but displays a message that says ‘Unbalanced parentheses’ rather than
‘Unbalanced braces’.  This is because the formatting command looks for
mismatches between braces as if they were parentheses.

   Sometimes ‘texinfo-format-region’ fails to detect mistakes.  For
example, in the following, the closing brace is swapped with the closing
parenthesis:

     (@xref{Catching Mistakes), for more info.}

Formatting produces:
     (see for more info.,
     for more info.)

   Incidentally, if you are reading this node in Info and type ‘f <RET>’
(‘Info-follow-reference’), you will generate an error message that says:

     No such node: "Catching Mistakes) The only way ...

This is because Info perceives the example of the error as the first
cross-reference in this node and if you type a <RET> immediately after
typing the Info ‘f’ command, Info will attempt to go to the referenced
node.  If you type ‘f catch <TAB> <RET>’, Info will complete the node
name of the correctly written example and take you to the 'Catching
Mistakes' node.  (If you try this, you can return from the 'Catching
Mistakes' node by typing ‘l’ (‘Info-last’).)

D.10.3 Debugging with TeX
-------------------------

You can also catch mistakes when you format a file with TeX.

   Usually, you will want to do this after you have run
‘texinfo-format-buffer’ (or, better, ‘makeinfo-buffer’) on the same
file, because ‘texinfo-format-buffer’ sometimes displays error messages
that make more sense than TeX.  (see Debugging with Info, for more
information.)

   For example, TeX was run on a Texinfo file, part of which is shown
here:

     ---------- Buffer: texinfo.texi ----------
     name of the Texinfo file as an extension.  The
     @samp{??} are `wildcards' that cause the shell to
     substitute all the raw index files.  (@xref{sorting
     indices, for more information about sorting
     indices.)
     ---------- Buffer: texinfo.texi ----------

(The cross-reference lacks a closing brace.)  TeX produced the following
output, after which it stopped:

     ---------- Buffer: *tex-shell* ----------
     Runaway argument?
     {sorting indices, for more information about sorting
     indices.) @ETC.
     ! Paragraph ended before @xref was complete.
     <to be read again>
                       @par
     l.27

     ?
     ---------- Buffer: *tex-shell* ----------

   In this case, TeX produced an accurate and understandable error
message:

     Paragraph ended before @xref was complete.

‘@par’ is an internal TeX command of no relevance to Texinfo.  ‘l.27’
means that TeX detected the problem on line 27 of the Texinfo file.  The
‘?’ is the prompt TeX uses in this circumstance.

   Unfortunately, TeX is not always so helpful, and sometimes you must
truly be a Sherlock Holmes to discover what went wrong.

   In any case, if you run into a problem like this, you can do one of
three things.

  1. You can tell TeX to continue running and ignore just this error by
     typing <RET> at the ‘?’ prompt.

  2. You can tell TeX to continue running and to ignore all errors as
     best it can by typing ‘r <RET>’ at the ‘?’ prompt.

     This is often the best thing to do.  However, beware: the one error
     may produce a cascade of additional error messages as its
     consequences are felt through the rest of the file.  To stop TeX
     when it is producing such an avalanche of error messages, type
     ‘C-c’ (or ‘C-c C-c’, if you are running a shell inside Emacs).

  3. You can tell TeX to stop this run by typing ‘x <RET>’ at the ‘?’
     prompt.

   If you are running TeX inside Emacs, you need to switch to the shell
buffer and line at which TeX offers the ‘?’ prompt.

   Sometimes TeX will format a file without producing error messages
even though there is a problem.  This usually occurs if a command is not
ended but TeX is able to continue processing anyhow.  For example, if
you fail to end an itemized list with the ‘@end itemize’ command, TeX
will write a DVI file that you can print out.  The only error message
that TeX will give you is the somewhat mysterious comment:

     (@end occurred inside a group at level 1)

However, if you print the DVI file, you will find that the text of the
file that follows the itemized list is entirely indented as if it were
part of the last item in the itemized list.  The error message is the
way TeX says that it expected to find an ‘@end’ command somewhere in the
file; but that it could not determine where it was needed.

   Another source of notoriously hard-to-find errors is a missing ‘@end
group’ command.  If you ever are stumped by incomprehensible errors,
look for a missing ‘@end group’ command first.

   If the Texinfo file lacks header lines, TeX may stop in the beginning
of its run and display output that looks like the following.  The ‘*’
indicates that TeX is waiting for input.

     This is TeX, Version 3.14159 (Web2c 7.0)
     (test.texinfo [1])
     *

In this case, simply type ‘\end <RET>’ after the asterisk.  Then write
the header lines in the Texinfo file and run the TeX command again.
(Note the use of the backslash, ‘\’.  TeX uses ‘\’ instead of ‘@’; and
in this circumstance, you are working directly with TeX, not with
Texinfo.)

D.10.4 Finding Badly Referenced Nodes
-------------------------------------

You can use the ‘Info-validate’ command to check whether any of the
'Next', 'Previous', 'Up' or other node pointers fail to point to a node.
This command checks that every node pointer points to an existing node.
The ‘Info-validate’ command works only on Info files, not on Texinfo
files.

   The ‘texi2any’ program validates pointers automatically, so you do
not need to use the ‘Info-validate’ command if you are using ‘texi2any’.
With the customization variable ‘CHECK_NORMAL_MENU_STRUCTURE’ set,
‘texi2any’ will also warn if the nodes pointers (either explicitly or
automatically set) are not consistent with the order of node menu
entries.  ‘texi2any’ does not check that every 'Next' pointer is matched
by a 'Previous' (in the node where the 'Next' points) which points back,
since it may be correct for a non standard document structure.

   You only may need to use ‘Info-validate’ if you are unable to run
‘texi2any’ and instead must create an Info file using
‘texinfo-format-region’ or ‘texinfo-format-buffer’, or if you write an
Info file from scratch.

D.10.4.1 Using ‘Info-validate’
..............................

To use ‘Info-validate’, visit the Info file you wish to check and type:

     M-x Info-validate

Note that the ‘Info-validate’ command requires an uppercase 'I'.  You
may also need to create a tag table before running ‘Info-validate’.
See Tagifying.

   If your file is valid, you will receive a message that says "File
appears valid".  However, if you have a pointer that does not point to a
node, error messages will be displayed in a buffer called ‘*problems in
info file*’.

   For example, ‘Info-validate’ was run on a test file that contained
only the first node of this manual.  One of the messages said:

     In node "Overview", invalid Next: Texinfo Mode

This meant that the node called ‘Overview’ had a 'Next' pointer that did
not point to anything (which was true in this case, since the test file
had only one node in it).

   Now suppose we add a node named ‘Texinfo Mode’ to our test case but
we do not specify a 'Previous' for this node.  Then we will get the
following error message:

     In node "Texinfo Mode", should have Previous: Overview

This is because, with a standard document structure, every 'Next'
pointer should be matched by a 'Previous' (in the node where the 'Next'
points) which points back.

   ‘Info-validate’ also checks that all menu entries and
cross-references point to actual nodes.

   ‘Info-validate’ requires a tag table and does not work with files
that have been split.  (The ‘texinfo-format-buffer’ command
automatically splits large files.)  In order to use ‘Info-validate’ on a
large file, you must run ‘texinfo-format-buffer’ with an argument so
that it does not split the Info file; and you must create a tag table
for the unsplit file.

D.10.4.2 Creating an Unsplit File and Adding a Tag Table
........................................................

You can run ‘Info-validate’ only on a single Info file that has a tag
table.  The command will not work on the indirect subfiles that are
generated when a master file is split.  If you have a large file (longer
than 300,000 bytes or so), you need to run the ‘texinfo-format-buffer’
or ‘makeinfo-buffer’ command in such a way that it does not create
indirect subfiles.  You will also need to create a tag table for the
Info file.  After you have done this, you can run ‘Info-validate’ and
look for badly referenced nodes.

   The first step is to create an unsplit Info file.  To prevent
‘texinfo-format-buffer’ from splitting a Texinfo file into smaller Info
files, give a prefix to the ‘M-x texinfo-format-buffer’ command:

     C-u M-x texinfo-format-buffer

or else

     C-u C-c C-e C-b

When you do this, ‘texinfo-format-buffer’ will not split the file and
will not create a tag table for it.

   After creating an unsplit Info file, you must create a tag table for
it (see Tagifying).  Visit the unsplit Info file created by
‘texinfo-format-buffer’ and type:

     M-x Info-tagify

   The third step is to validate the Info file:

     M-x Info-validate

(Note the uppercase ‘I’ in ‘Info-validate’.)  In brief, the steps are:

     C-u M-x texinfo-format-buffer
     M-x Info-tagify
     M-x Info-validate

   After you have validated the node structure, you can rerun
‘texinfo-format-buffer’ in the normal way so it will construct a tag
table and split the file automatically, or you can make the tag table
and split the file manually (see Splitting).

D.11 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 ‘texi2any’ 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.)

Appendix E Global Document Commands
***********************************

Here are additional commands which affect the document as a whole.  Most
of these commands are for customizing the appearance of the printed
output.  They are generally all given before the Top node, if they are
given at all.

E.1 ‘@setchapternewpage’: Blank Pages Before Chapters
=====================================================

In an officially bound book, text is usually printed on both sides of
the paper, chapters start on right-hand pages, and right-hand pages have
odd numbers.  But in short reports, text often is printed only on one
side of the paper.  Also in short reports, chapters sometimes do not
start on new pages, but are printed on the same page as the end of the
preceding chapter, after a small amount of vertical whitespace.

   You can use the ‘@setchapternewpage’ command with various arguments
to specify how chapters should be started in printed output and whether
headers should be formatted for printing on one or both sides of the
paper (single-sided or double-sided printing).

   Write the ‘@setchapternewpage’ command at the beginning of a line
followed by its argument.  For example, you would write the following to
cause each chapter to start on a fresh odd-numbered page:

     @setchapternewpage odd

   You can specify one of three alternatives with the
‘@setchapternewpage’ command:

‘@setchapternewpage off’
     Typeset a new chapter on the same page as the last chapter, after
     skipping some vertical whitespace.  Also, format page headers for
     single-sided printing.

‘@setchapternewpage on’
     Start new chapters on new pages and format page headers for
     single-sided printing.  This is the form most often used for short
     reports or personal printing.  This is the default.

‘@setchapternewpage odd’
     Start new chapters on new, odd-numbered pages (right-handed pages)
     and typeset for double-sided printing.  This is the form most often
     used for books and manuals.

   Texinfo does not have a ‘@setchapternewpage even’ command, because
there is no printing tradition of starting chapters or books on an
even-numbered page.

   If you don't like the default headers that ‘@setchapternewpage’ sets,
you can explicit control them with the ‘@headings’ command.  See
@headings.

   At the beginning of a manual or book, pages are not numbered--for
example, the title and copyright pages of a book are not numbered.  By
convention, table of contents and frontmatter pages are numbered with
roman numerals and not in sequence with the rest of the document.

   The ‘@setchapternewpage’ has no effect in output formats that do not
have pages, such as Info and HTML.

   We recommend not including any ‘@setchapternewpage’ command in your
document source at all, since such desired pagination is not intrinsic
to the document.  For a particular hard copy run, if you don't want the
default output (no blank pages, same headers on all pages) use the
‘--texinfo’ option to ‘texi2dvi’ to specify the output you want.

E.2 Page Headings
=================

Most printed manuals contain headings along the top of every page except
the title and copyright pages.  Some manuals also contain footings.
Headings and footings have no meaning in Info or the other output
formats.

   Texinfo provides two standard heading formats, one for manuals
printed on one side of each sheet of paper, and the other for manuals
printed on both sides of the paper.  By default, nothing is specified
for the footing of a Texinfo file, so the footing remains blank.

   Texinfo also has several heading and footing commands that you can
use to generate your own heading and footing formats.

   In Texinfo, headings and footings are single lines at the tops and
bottoms of pages; you cannot create multiline headings or footings.
Each header or footer line is divided into three parts: a left part, a
middle part, and a right part.  Any part, or a whole line, may be left
blank.  Text for the left part of a header or footer line is set
flushleft; text for the middle part is centered; and, text for the right
part is set flushright.

E.2.1 The ‘@headings’ Command
-----------------------------

The ‘@headings’ command is rarely used.  It specifies what kinds of page
headings and footings to print on each page.  Usually, this is
controlled by the ‘@setchapternewpage’ command.  You need the
‘@headings’ command only if the ‘@setchapternewpage’ command does not do
what you want.

   You can use ‘@headings’ as follows:

‘@headings off’
     Turn off printing of page headings.

‘@headings single’
     Turn on page headings appropriate for single-sided printing.

‘@headings double’
     Turn on page headings appropriate for double-sided printing.

‘@headings singleafter’
‘@headings doubleafter’
     Turn on ‘single’ or ‘double’ headings, respectively, after the
     current page is output.

‘@headings on’
     Turn on page headings: ‘single’ if ‘@setchapternewpage on’,
     ‘double’ otherwise.

   For example, suppose you write ‘@setchapternewpage off’ before the
‘@titlepage’ command to start a new chapter on the same page as the end
of the last chapter.  This command also causes page headers to be
typeset for single-sided printing.  To cause page headers to be typeset
for double-sided printing, write ‘@headings double’.

   You can stop any page headings at all from being generated by writing
‘@headings off’ on a line of its own, like this:

     @headings off

E.2.2 Standard Heading Formats
------------------------------

Texinfo provides two standard heading formats, one for manuals printed
on one side of each sheet of paper, and the other for manuals printed on
both sides of the paper.

   The standard format for single-sided printing consists of a header
line in which the left-hand part contains the name of the chapter, the
central part is blank, and the right-hand part contains the page number.
A single-sided page looks like this:

       _______________________
      |                       |
      | chapter   page number |
      |                       |
      | Start of text ...     |
      | ...                   |
      |                       |

   In the standard double-sided format, the left part of the left-hand
(even-numbered) page contains the page number, the central part is
blank, and the right part contains the title (specified by the
‘@settitle’ command).  The left part of the right-hand (odd-numbered)
page contains the name of the chapter, the central part is blank, and
the right part contains the page number.  An even-numbered page and an
odd-numbered page, side by side as in an open book, look like this:

       _______________________     _______________________
      |                       |   |                       |
      | page number     title |   | chapter   page number |
      |                       |   |                       |
      | Start of text ...     |   | More  text ...        |
      | ...                   |   | ...                   |
      |                       |   |                       |

The chapter name is preceded by the word "Chapter", the chapter number
and a colon.  This makes it easier to keep track of where you are in the
manual.

   Note that on pages where a new chapter starts, some text may be
omitted from the heading line.

   By default, nothing is specified for the footing of a Texinfo file,
so the footing remains blank.

E.2.3 How to Make Your Own Headings
-----------------------------------

You can use the standard headings provided with Texinfo or specify your
own.  By default, Texinfo has no footers, so if you specify them, the
available page size for the main text will be slightly reduced.

   Texinfo provides six commands for specifying headings and footings:
   • ‘@everyheading’ and ‘@everyfooting’ generate page headers and
     footers that are the same for both even- and odd-numbered pages.
   • ‘@evenheading’ and ‘@evenfooting’ commands generate headers and
     footers for even-numbered (left-hand) pages.
   • ‘@oddheading’ and ‘@oddfooting’ generate headers and footers for
     odd-numbered (right-hand) pages.

   You must cancel the predefined heading commands with the ‘@headings
off’ command before defining your own specifications.

   Here is how to place the chapter name at the left, the page number in
the center, and the date at the right of every header for both even- and
odd-numbered pages:

     @headings off
     @everyheading @thischapter @| @thispage @| @today{}

You need to divide the left part from the central part and the central
part from the right part by inserting ‘@|’ between parts.  Otherwise,
the specification command will not be able to tell where the text for
one part ends and the next part begins.

   Each part can contain text or @-commands.  The text is printed as if
the part were within an ordinary paragraph in the body of the page.  The
@-commands replace themselves with the page number, date, chapter name,
or whatever.

   Here are the six heading and footing commands:

‘@everyheading LEFT @| CENTER @| RIGHT’
‘@everyfooting LEFT @| CENTER @| RIGHT’
     The 'every' commands specify the format for both even- and
     odd-numbered pages.  These commands are for documents that are
     printed on one side of each sheet of paper, or for documents in
     which you want symmetrical headers or footers.

‘@evenheading LEFT @| CENTER @| RIGHT’
‘@oddheading LEFT @| CENTER @| RIGHT’
‘@evenfooting LEFT @| CENTER @| RIGHT’
‘@oddfooting LEFT @| CENTER @| RIGHT’
     The 'even' and 'odd' commands specify the format for even-numbered
     pages and odd-numbered pages.  These commands are for books and
     manuals that are printed on both sides of each sheet of paper.

   Use the ‘@this...’ series of @-commands to provide the names of
chapters and sections and the page number.  You can use the ‘@this...’
commands in the left, center, or right portions of headers and footers.

   Here are the ‘@this...’ commands:

‘@thispage’
     Expands to the current page number.

‘@thissectionname’
     Expands to the name of the current section.

‘@thissectionnum’
     Expands to the number of the current section.

‘@thissection’
     Expands to the number and name of the current section, in the
     format 'Section 1: Title'.

‘@thischaptername’
     Expands to the name of the current chapter.

‘@thischapternum’
     Expands to the number of the current chapter, or letter of the
     current appendix.

‘@thischapter’
     Expands to the number and name of the current chapter, in the
     format 'Chapter 1: Title'.

‘@thistitle’
     Expands to the name of the document, as specified by the
     ‘@settitle’ command.

‘@thisfile’
     For ‘@include’ files only: expands to the name of the current
     ‘@include’ file.  If the current Texinfo source file is not an
     ‘@include’ file, this command has no effect.  This command does
     _not_ provide the name of the current Texinfo source file unless it
     is an ‘@include’ file.  (see Include Files, for more
     information about ‘@include’ files.)

You can also use the ‘@today{}’ command, which expands to the current
date, in '1 Jan 1900' format.

   Other @-commands and text are printed in a header or footer just as
if they were in the body of a page.  It is useful to incorporate text,
particularly when you are writing drafts:

     @headings off
     @everyheading @emph{Draft!} @| @thispage @| @thischapter
     @everyfooting @| @| Version: 0.27: @today{}

   Beware of overlong titles: they may overlap another part of the
header or footer and blot it out.

   If you have very short chapters and/or sections, several of them can
appear on a single page.  You can specify which chapters and sections
you want ‘@thischapter’, ‘@thissection’ and other such macros to refer
to on such pages as follows:

‘@everyheadingmarks REF’
‘@everyfootingmarks REF’
     The REF argument can be either ‘top’ (the ‘@this...’ commands will
     refer to the chapter/section at the top of a page) or ‘bottom’ (the
     commands will reflect the situation at the bottom of a page).
     These ‘@every...’ commands specify what to do on both even- and
     odd-numbered pages.

‘@evenheadingmarks REF’
‘@oddheadingmarks REF’
‘@evenfootingmarks REF’
‘@oddfootingmarks REF’
     These ‘@even...’ and ‘@odd...’ commands specify what to do on only
     even- or odd-numbered pages, respectively.  The REF argument is the
     same as with the ‘@every...’ commands.

   Write these commands immediately after the ‘@...contents’ commands,
or after the ‘@end titlepage’ command if you don't have a table of
contents or if it is printed at the end of your manual.  These commands
have no effect in LaTeX.

   By default, for TeX, the ‘@this...’ commands reflect the situation at
the bottom of a page both in headings and in footings.

E.3 ‘@paragraphindent’: Controlling Paragraph Indentation
=========================================================

The Texinfo processors may insert whitespace at the beginning of the
first line of each paragraph, thereby indenting that paragraph.  You can
use the ‘@paragraphindent’ command to specify this indentation.  Write a
‘@paragraphindent’ command at the beginning of a line followed by either
‘asis’ or a number:

     @paragraphindent INDENT

   The indentation is according to the value of INDENT:

‘asis’
     Do not change the existing indentation (not implemented in printed
     output).

‘none’
0
     Omit all indentation.

N
     Indent by N space characters in Info output, by N ems in printed
     output.

   The default value of INDENT is 3.  ‘@paragraphindent’ is ignored for
HTML output.

   It is best to write the ‘@paragraphindent’ command before the
end-of-header line at the beginning of a Texinfo file, so the region
formatting commands indent paragraphs as specified.  See Start of Header.

E.4 ‘@firstparagraphindent’: Indenting After Headings
=====================================================

As you can see in the present manual, the first paragraph in any section
is not indented by default.  Typographically, indentation is a paragraph
separator, which means that it is unnecessary when a new section begins.
This indentation is controlled with the ‘@firstparagraphindent’ command:

     @firstparagraphindent WORD

   The first paragraph after a heading is indented according to the
value of WORD:

‘none’
     Prevents the first paragraph from being indented (default).  This
     option is ignored by ‘makeinfo’ if ‘@paragraphindent asis’ is in
     effect.

‘insert’
     Include normal paragraph indentation.  This respects the paragraph
     indentation set by a ‘@paragraphindent’ command (see
     @paragraphindent).

   ‘@firstparagraphindent’ is ignored for HTML and DocBook output.

   It is best to write the ‘@firstparagraphindent’ command before the
end-of-header line at the beginning of a Texinfo file, so the region
formatting commands indent paragraphs as specified.  See Start of Header.

E.5 ‘@exampleindent’: Environment Indenting
===========================================

The Texinfo processors indent each line of ‘@example’ and similar
environments.  You can use the ‘@exampleindent’ command to specify this
indentation.  Write an ‘@exampleindent’ command at the beginning of a
line followed by either ‘asis’ or a number:

     @exampleindent INDENT

   The indentation is according to the value of INDENT:

‘asis’
     Do not change the existing indentation (not implemented in printed
     output).

0
     Omit all indentation.

N
     Indent environments by N space characters in Info output, by N ems
     in printed output.

   The default value of INDENT is 5 spaces in Info, and 0.4in in printed
output, which is somewhat less.  (The reduction is to help fit more
characters onto physical lines in printed manuals.)

   It is best to write the ‘@exampleindent’ command before the
end-of-header line at the beginning of a Texinfo file, so the region
formatting commands indent paragraphs as specified.  See Start of Header.

E.6 ‘@smallbook’: Printing "Small" Books
========================================

By default, TeX typesets pages for printing in an 8.5 by 11 inch format,
which is the "letter" size commonly used in the United States.  However,
you can direct TeX or LaTeX to typeset a document in a 7 by 9.25 inch
format that is suitable for bound books by inserting the following
command on a line by itself at the beginning of the Texinfo file, before
the title page:

     @smallbook

(Since many books are about 7 by 9.25 inches, this command might better
have been called the ‘@regularbooksize’ command, but it came to be
called the ‘@smallbook’ command by comparison to the 8.5 by 11 inch
format.)

   See Format with texi2dvi or texi2pdf, and Preparing for TeX,
for other ways to format with ‘@smallbook’ with TeX that do not
require changing the source file.

E.7 Printing on A4 Paper
========================

You can format a document for printing on ISO 216 A4 paper size with the
‘@afourpaper’ command.  Write the command on a line by itself near the
beginning of the Texinfo file, before the title page.

   You may or may not prefer the formatting that results from the
command ‘@afourlatex’.  There's also ‘@afourwide’ for A4 paper in wide
format, ‘@afivepaper’ for A5 paper, and ‘@bsixpaper’ for B6 paper.

   See Format with texi2dvi or texi2pdf and Preparing for TeX,
for other ways to format for different paper sizes that do not
require changing the source file.

E.8 ‘@pagesizes’ [WIDTH][, HEIGHT]: Custom Page Sizes
=====================================================

You can explicitly specify the height and (optionally) width of the main
text area on the page with the ‘@pagesizes’ command.  Write this on a
line by itself near the beginning of the Texinfo file, before the title
page.  The height comes first, then the width if desired, separated by a
comma.  Examples:

     @pagesizes 200mm,150mm
and
     @pagesizes 11.5in

   This would be reasonable for printing on B5-size paper.  To
emphasize, this command specifies the size of the _text area_, not the
size of the paper (which is 250mm by 177mm for B5, 14in by 8.5in for
legal).

   To make more elaborate changes, such as changing any of the page
margins, you must define a new command in ‘texinfo.tex’ or
‘texinfo.cnf’.

   See Format with texi2dvi or texi2pdf, and Preparing for TeX,
for other ways to specify ‘@pagesizes’ that do not require
changing the source file.

E.9 Microtypography
===================

Some versions of TeX, namely pdfTeX and LuaTeX, have “microtypography”
features.  These involve stretching font glyphs slightly, and allowing
text to produce very slightly into the margins.  Use of these gives TeX
more flexibility in breaking a paragraph into lines, and can improve
paragraph appearance by reducing hyphenation and producing a more
consistent typographic color.

   ‘texinfo.tex’ uses these features ('microtype' for short) when
available.  You can turn microtype off by specifying ‘@microtype off’ in
your input file; likewise, ‘@microtype on’ turns microtype back on.

   The fonts used in LaTeX output may not be scalable.  If fonts are not
scalable, using microtypography could trigger an error when converting
the LaTeX output.  Therefore microtypography is not turned on in the
default case in LaTeX output.  It is possible to turn it on with
‘@microtype on’.  A way to get scalable fonts for the font used in the
default LaTeX output is to install the CM-Super font package
(<http://ctan.org/pkg/cm-super>).

   The ‘@microtype’ command does nothing for other output formats.

E.10 Magnification
==================

You can attempt to direct TeX to typeset pages larger or smaller than
usual with the ‘\mag’ TeX command.  Everything that is typeset is scaled
proportionally larger or smaller.  (‘\mag’ stands for "magnification".)
This is _not_ a Texinfo @-command, but is a raw TeX command that is
prefixed with a backslash.  You have to write this command between
‘@tex’ and ‘@end tex’ (see Raw Formatter Commands).

   Follow the ‘\mag’ command with an ‘=’ and then a number that is 1000
times the magnification you desire.  For example, to print pages at 1.2
normal size, write the following near the beginning of the Texinfo file,
before the title page:

     @tex
     \global\mag=1200
     @end tex

   With some printing technologies, you can print normal-sized copies
that look better than usual by giving a larger-than-normal master to
your print shop.  They do the reduction, thus effectively increasing the
resolution.

   Depending on your system, DVI files prepared with a
nonstandard-‘\mag’ may not print or may print only with certain
magnifications.  Be prepared to experiment.

Appendix F Info Format Specification
************************************

Here we describe the technical details of the Info format.

   In this formal description, the characters ‘<>*()|=#’ are used for
the language of the description itself.  Other characters are literal.
The formal constructs used are typical: ‘<...>’ indicates a metavariable
name, ‘=’ means definition, ‘*’ repetition, ‘?’ optional, ‘()’ grouping,
‘|’ alternation, and ‘#’ comment.

   In general, programs that read Info files should try to be
case-insensitive to keywords that occur in the file (for example, ‘Tag
Table’ and ‘Tag table’ should be equivalent) in order to support
Info-generating programs that use different capitalization.

   We specify literal parentheses (those that are part of the Info
format) with <lparen> and <rparen>, meaning the single characters ‘(’
and ‘)’ respectively.  Finally, the two-character sequence ‘^X’ means
the single character ‘CTRL-X’, for any X.

   This format definition was written some 25 years after the Info
format was first devised.  So in the event of conflicts between this
definition and actual practice, practice wins.  It also assumes some
general knowledge of Texinfo; it is meant to be a guide for implementors
rather than a rigid technical standard.  We may refer back to other
parts of this manual for examples and definitions, rather than
redundantly spelling out every detail.

F.1 Info Format: A Whole Manual
===============================

To begin, an Info manual is either “nonsplit” (contained wholly within a
single file) or “split” (across several files).

   The syntax for a nonsplit manual is:

         <nonsplit info file> =
     <preamble>
     <node>*
     <tag table>?
     <local variables>?

   When split, there is a “main file”, which contains only pointers to
the nodes given in other “subfiles”.  The main file looks like this:

         <split info main file> =
     <preamble>
     <indirect table>
     <tag table>
     <local variables>?

   The subfiles in a split manual have the following syntax:

         <split info subfile> =
     <preamble>
     <node>*

   Note that the tag table is not optional for split files, as it is
used with the indirect table to deduce which subfile a particular node
is in.

   Several of the sections in an Info file (such as nodes or tag tables)
begin with a sequence:

         <separator> = (^L)?^_(^L)?^J

That is, a ‘CTRL-_’ character followed by a newline, with optional
formfeed characters.

F.2 Info Format: Preamble
=========================

The <preamble> is text at the beginning of all output files.  It is not
intended to be visible by default in an Info viewer, but may be
displayed upon user request.

         <preamble> =
     <identification>       # "This is FILENAME, produced by ..."
     <copying text>         # Expansion of @copying text.
     <dir entries>          # Derived from @dircategory and @direntry.

These pieces are:

<identification line>
     An arbitrary string beginning the output file, followed by a blank
     line.

<copying text>
     The expansion of a ‘@copying’ environment, if the manual has one
     (see @copying).

<dir entries>
     The result of any ‘@dircategory’ and ‘@direntry’ commands present
     in the manual (see Installing Dir Entries).

F.3 Info Format: Indirect Table
===============================

         <indirect table> =
     <separator>
     Indirect:
     (<filename>: <bytepos>)*

   The indirect table is written to the main file in the case of split
output only.  It specifies, as a decimal integer, the starting byte
position (zero-based) that the first node of each subfile would have if
the subfiles were concatenated together in order, not including the
top-level file.  The first node of actual content is pointed to by the
first entry.

   As an example, suppose split output is generated for the GDB manual.
The top-level file ‘gdb.info’ will contain something like this:

     <separator>
     Indirect:
     gdb.info-1: 1878
     gdb.info-2: 295733
     ...

   This tells Info viewers that the first node of the manual occurs at
byte 1878 of the file ‘gdb.info-1’ (which would be after that file's
preamble.)  The first node in the ‘gdb.info-2’ subfile would start at
byte 295733 if ‘gdb.info-2’ were appended to ‘gdb.info-1’, including any
preamble sections in both files.

   Unfortunately, Info-creating programs such as ‘makeinfo’ have not
always implemented these rules perfectly, due to various bugs and
oversights.  Therefore, robust Info viewers should fall back to
searching "nearby" the given position for a node, instead of giving up
immediately if the position is not exactly at a node beginning.

F.4 Info Format: Tag Table
==========================

         <tag table> =
     <separator>
     Tag Table:
     (<lparen>Indirect<rparen>)?
     (Node|Ref): <nodeid>^?<bytepos>
     <separator>
     End Tag Table

   The ‘(Indirect)’ line appears in the case of split output only.

   The tag table specifies the starting byte position of each node and
anchor in the file.  In the case of split output, it is only written in
the main output file.

   Each line defines an identifier as either an anchor or a node, as
specified.  For example, ‘Node: Top^?1647’ says that the node named
‘Top’ starts at byte 1647 while ‘Ref: Overview-Footnote-1^?30045’ says
that the anchor named ‘Overview-Footnote-1’ starts at byte 30045.  It is
an error to define the same identifier both ways.

   In the case of nonsplit output, the byte positions simply refer to
the location in the output file.  In the case of split output, the byte
positions refer to an imaginary file created by concatenating all the
split files (but not the top-level file).  See the previous section.

   Here is an example:

     ^_
     Tag Table:
     Node: Top^?89
     Node: Ch1^?292
     ^_
     End Tag Table

This specifies a manual with two nodes, 'Top' and 'Ch1', at byte
positions 89 and 292 respectively.  Because the ‘(Indirect)’ line is not
present, the manual is not split.

   Preamble sections or other non-node sections of files do not have a
tag table entry.

F.5 Info Format: Local Variables
================================

The local variables section is optional.  It is currently used to give
the encoding information and/or the document language code.

         <local variables> =
     <separator>
     Local Variables:
     (coding: <encoding>)?
     (Info-documentlanguage: <language>)?
     End:

   @documentencoding for information about the document
encoding.

   ‘<language>’ should be of the form LL or LL_CC; see
@documentlanguage.  Only one language can be specified in the local
variables section even if ‘@documentlanguage’ occurs several times in a
Texinfo document.

F.6 Info Format: Regular Nodes
==============================

Regular nodes look like this:

         <node> =
     <separator>
     File: <fn>, Node: <id1>, (Next: <id2>, )? (Prev: <id3>, )? Up: <id4>

     <general text, until the next ^_ or end-of-file>

At least one space or tab must be present after each colon and comma,
but any number of spaces are ignored.  The <id> node identifiers have
following format:

        <id> = (<lparen><infofile><rparen>)?<node-spec>?
        <node-spec> = <nodename> | <del><nodename><del>
        <del> = ^?

   This <node> defines <id1> in file <fn>, which is typically either
‘manualname’ or ‘manualname.info’.  No parenthesized <infofile>
component may appear within <id1>.

   Each of the identifiers after ‘Next’, ‘Prev’ and ‘Up’ refer to nodes
or anchors within a file.  These pointers normally refer within the same
file, but ‘(dir)’ is often used to point to the top-level dir file.  If
an <infofile> component is used then the node name may be omitted, in
which case the node identifier refers to the ‘Top’ node within the
referenced file.

   The ‘Next’ and ‘Prev’ pointers are optional.  The ‘Up’ pointer is
technically also optional, although most likely this indicates a mistake
in the node structuring.  Conventionally, the nodes are arranged to form
a tree, but this is not a requirement of the format.

   Node names containing periods, commas, colons or parentheses can
confuse Info readers.  If it is necessary to refer to a node whose name
contains any of these, the <nodename> should be surrounded by a pair of
‘DEL’ characters (‘CTRL-?’, character number 127).  ‘makeinfo’ adds
these characters when needed in the default case.  Note that not all
Info readers recognize this syntax.  See Info Node Names Constraints.

   The <general text> of the node can include the special constructs
described next.

F.7 Info Format: Menu
=====================

Conventionally menus appear at the end of nodes, but the Info format
places no restrictions on their location.

         <menu> =
     * Menu:
     (<menu entry> | <menu comment>)*

   The parts of a <menu entry> are also described in Menu Parts.
They have the same syntax as cross-references, with a leading ‘*’
instead of ‘* (N|n)ote’ (see Info Format Cross Reference).  Indices
extend the menu format to specify the destination line; see Info Format Printindex.

   A <menu comment> is any line not beginning with ‘*’ that appears
either at the beginning of the menu or is separated from a menu entry by
one or more blank lines.  These comments are intended to be displayed as
part of the menu, as-is (see Writing a Menu).

F.8 Info Format: Image
======================

The ‘@image’ command results in the following special directive within
the Info file (see Images):

         <image> =
     ^@^H[image src="<image file>"
                 (text="<txt file contents>")?
                 (alt="<alt text>")?
     ^@^H]

   The line breaks and indentation in this description are editorial;
the whitespace between the different parts of the directive in Info
files is arbitrary.

   In the strings <image file>, <txt file contents> and <alt text>, ‘"’
is quoted as ‘\"’ and ‘\’ is quoted as ‘\\’.  The txt and alt
specifications are optional.

   The alt value serves the same purpose as in HTML: A prose description
of the image.  In text-only displays or speech systems, for example, the
alt value may be used instead of displaying the (typically graphical)
<image file>.

   The <txt file contents>, if present, should be taken as an ASCII
representation of the image, for possible use on a text-only display.

   The format does not prescribe the choice between displaying the
<image file>, the <alt text> or the <txt file contents>.

F.9 Info Format: Printindex
===========================

An index in Info format is a kind of menu, with an additional directive
at the beginning to mark it as an index menu.

         <printindex> =
     ^@^H[index^@^H]
     * Menu:

     <index entry>*

   The <index entry> items are similar to normal menu entries, but the
free-format description is replaced by the line number of where the
entries occurs in the text:

         <index entry> =
     * <entry text>: <node-spec>. <line-spec>

         <line-spec> =
     <lparen>line <lineno><rparen>

   The initial part, ‘<entry text>: <entry node>.’, should be on a
single line.  The <entry text> is the index term.

   Even though <entry text> is followed by a colon, it may itself
contain colons, so Info readers should try to include as much of the
line as possible in the <entry text>.  (However, <entry text> may not
contain the ‘DEL’ characters that may occur in <node-spec>.)

   <lineno> is an unsigned integer, given relative to the start of the
<entry node>.  An optional line break may occur before ‘<line-spec>’.

   Here is an example:

     ^@^H[index^@^H]
     * Menu:

     * thunder:           Weather Phenomena.             (line 5)

   This means that an index entry for 'thunder' appears at line 5 of the
node 'Weather Phenomena'.

F.10 Info Format: Cross-reference
=================================

A general cross-reference in Info format has one of the following two
forms:

         <cross-reference> =
       * (N|n)ote <id>::
     | * (N|n)ote <label>:<id>(.|,)

         <id> = (<lparen><infofile><rparen>)?<node-spec>?
         <label> = <label text> | <del><label text><del>

   No space should occur between the ‘*’ character and the following ‘N’
or ‘n’.  ‘*Note’ should be used at the start of a sentence, otherwise
‘*note’ should be used.  (Some Info readers, such as the one in Emacs,
can display ‘*Note’ and ‘*note’ as ‘See’ and ‘see’ respectively.)  In
both cases, <label text> is descriptive text.

   In both forms the <id> refers to a node or anchor, in the same way as
a reference in the node information line does (see Info Format Regular Nodes).
The optional parenthesized ‘<infofile>’ is the name of the
manual being referenced, and <node-spec> gives the node or anchor within
that manual.

   The second form has a descriptive label.  A cross-reference in this
form should usually be terminated with a comma or period, to make it
feasible to find the end of the <id>.

   If <label> contains a colon character (:), it should be surrounded
with a pair of <del> characters.  Likewise, quoting characters may be
used for the node name if it contains problematic characters; then a
terminating comma or period is not needed.  As stated earlier, this
quoting mechanism is not supported in all Info-reading programs.

   The format does not prescribe how to find other manuals to resolve
such references.

   Here are some examples:

     GNU Free Documentation License
     See Tag table, for details.
     See Overview (make).
     See ^?.
     See alloca.h (gnulib).h^?.

   The first shows a reference to a node in the current manual using the
short form.

   The second also refers to a node in the current manual, namely 'Info
Format Tag Table'; the 'Tag table' before the ‘:’ is only a label on
this particular reference, and the ‘for details.’ is text belonging to
the sentence, not part of the reference.

   The third example refers to the node 'Top' in another manual, namely
‘make’, with 'Overview' being the label for this cross-reference.

   The fourth example shows a colon character being quoted in a label,
and the fifth example shows a period being quoted in a node name.

   See Cross References.

Appendix G GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <https://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document “free” in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     The "publisher" means any person or entity that distributes copies
     of the Document to the public.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled "History" in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          "History" section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version's
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, receipt of a copy of some or all of the
     same material does not give you any rights to use it.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <https://www.gnu.org/licenses/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.  If the Document specifies that a proxy can
     decide which future versions of this License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

  11. RELICENSING

     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     "Incorporate" means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is "eligible for relicensing" if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

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

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.

Command Index
*************

This is an alphabetical list of all the @-commands and assorted Emacs
Lisp functions.  To make the list easier to use, the commands are listed
without their preceding ‘@’.