branch master updated: * doc/texinfo.texi (Customization Variables) (HTML Output Advanced Customization): add the 'HTML Output Advanced Customization' node in 'Generating HTML' for the description of HTML customization variables use.

[Patrice Dumas]

This is an automated email from the git hooks/post-receive script.

pertusus pushed a commit to branch master
in repository texinfo.

The following commit(s) were added to refs/heads/master by this push:
     new 3cb52062ac * doc/texinfo.texi (Customization Variables) (HTML Output 
Advanced Customization): add the 'HTML Output Advanced Customization' node in 
'Generating HTML' for the description of HTML customization variables use.
3cb52062ac is described below

commit 3cb52062ac9ea0f1c224ca1f2a9a1031296088ee
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Mon Apr 1 14:50:20 2024 +0200

    * doc/texinfo.texi (Customization Variables)
    (HTML Output Advanced Customization): add the 'HTML Output Advanced
    Customization' node in 'Generating HTML' for the description of HTML
    customization variables use.
---
 ChangeLog        |    7 +
 doc/texinfo.texi | 5535 +++++++++++++++++++++++++++---------------------------
 2 files changed, 2779 insertions(+), 2763 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 49e20cb9de..e7e4b9fa1d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2024-04-01  Patrice Dumas  <pertusus@free.fr>
+
+       * doc/texinfo.texi (Customization Variables)
+       (HTML Output Advanced Customization): add the 'HTML Output Advanced
+       Customization' node in 'Generating HTML' for the description of HTML
+       customization variables use.
+
 2024-04-01  Patrice Dumas  <pertusus@free.fr>
 
        * doc/texinfo.texi (HTML Customization for Math): add a node for HTML
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index f0188e0a95..bd4fc4e53f 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -15359,12 +15359,6 @@ The sections below give the details for each of these.
 @menu
 * Commands: Customization Variables for @@-Commands.
 * Options:  Customization Variables and Options.
-* HTML Structure:   HTML Output Structure Customization.
-* HTML Links:       File Names and Links Customization for HTML.
-* HTML Headers:     Customization of Navigation and Headers.
-* HTML code:        General Customization of HTML Code.
-* HTML constructs:  Specific Customization of HTML Formatting.
-* HTML Math:        HTML Customization for Math.
 * HTML:     HTML Customization Variables List.
 * MathJax:  MathJax Customization Variables.
 * latex2html:  @command{latex2html} Customization Variables.
@@ -15545,450 +15539,243 @@ exec texi2any -c TEXINPUT_OUTPUT_FORMAT=textcontent 
"$@@"
 @end table
 
 
-@node HTML Output Structure Customization
-@subsection HTML Output Structure Customization
-
-In the default case, the HTML output is tailored for online viewing with
-a direct access to the information at the Top node.  For an output more
-similar to a book, set @code{NO_TOP_NODE_OUTPUT} to remove the Top node.
-If @code{SHOW_TITLE} is @samp{undef}, the default,
-setting @code{NO_TOP_NODE_OUTPUT} also sets @code{SHOW_TITLE} to
-output a title at the beginning of the document.  In the default case
-the full @code{@@titlepage} is used for the title, unset
-@code{USE_TITLEPAGE_FOR_TITLE} to get a simple title string.
-If @code{SHOW_TITLE} is set, it is possible to output the table of contents
-at the end of the title by setting @code{CONTENTS_OUTPUT_LOCATION} to
-@samp{after_title}.
-
-In the default case, a list of subordinate sections is output in each node
-for navigation, corresponding to @code{FORMAT_MENU} set to @samp{sectiontoc}.
-The table of contents are output at the end of the @code{@@top}
-section, to have the main location for navigation in the whole document
-early on, corresponding to @code{CONTENTS_OUTPUT_LOCATION} set to
-samp @code{after_top}.  To use menus instead to navigate in the document
-(@pxref{Menus}), set @code{FORMAT_MENU} to @samp{menu}.
-
-If menus are used for navigation, the tables of contents are not
-needed at the end of the @code{@@top} section as
-there should already be a master menu (@pxref{Master Menu Parts}).
-To output the table of contents at the end of the document or to a separate
-file, if output is split, set @code{CONTENTS_OUTPUT_LOCATION}
-to @samp{separate_element}.  It is also possible to set
-@code{CONTENTS_OUTPUT_LOCATION} to @samp{inline}, in that case the
-the tables of content are output where
-the corresponding @@-command, for example @code{@@contents}, is set.
-
-A special @dfn{About} element explaining how to navigate can be added by
-setting @code{DO_ABOUT}, set to 0 in the default case (no About element).
-
-If non-split, in the default case, the special elements such as the About
-element or the tables of contents are output in the same file as the
-manual nodes and sections.  If you prefer such special elements to be separate,
-set @code{MONOLITHIC} to 0 to output special elements to separate files.  As
-already described, the table of contents location may also be tuned with
-@code{CONTENTS_OUTPUT_LOCATION}.
-
-An experimental JavaScript browsing interface to the manual can be added, by
-setting @code{INFO_JS_DIR} value to the directory to place the code for this
-interface as e.g.@: @samp{texi2any --html -c INFO_JS_DIR=js @var{manual}.texi}
-to place files in a @samp{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.
-
-@anchor{JavaScript license web labels}
-@cindex JavaScript license web labels page
-@vindex JS_WEBLABELS
-@vindex JS_WEBLABELS_FILE
-In the default case, a @dfn{JavaScript license web labels page} is setup
-to give licensing information and source code for any JavaScript used in
-the HTML files for the manual
-(See @uref{https://www.gnu.org/licenses/javascript-labels.html}).  To avoid
-generating a JavaScript license web labels page, set @code{JS_WEBLABELS}
-to @samp{omit}.  With @code{JS_WEBLABELS} set to @samp{generate}, the default,
-generate a labels page at @code{JS_WEBLABELS_FILE}, @file{js_licenses.html}
-in the default case, and link to it in the HTML output files.  With
-@code{JS_WEBLABELS} set to @samp{reference}, link to the labels file given by
-@code{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.
-Labels files are generated for @code{INFO_JS_DIR} and with @code{HTML_MATH}
-set to @samp{mathjax} (@pxref{MathJax scripts}).
-
-The @code{@@node} @@-commands are usually followed by a sectioning command,
-which provides a heading for the node.  In the default case, a node not
-associated to a sectioning command but followed by a command like
-@code{@@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
-@code{USE_NEXT_HEADING_FOR_LONE_NODE} to 0.
-
-
-@node File Names and Links Customization for HTML
-@subsection File Names and Links Customization for HTML
-
-@c file names
-
-@vindex PREFIX
-@vindex SUBDIR
-@vindex EXTENSION
-It is possible to specify the output file names with more control than
-merely the command line option @option{--output} (@pxref{Invoking
-@command{texi2any}}). The @code{PREFIX} customization
-variable overrides the base name of the file given by @code{@@setfilename} or
-the file name and should not contain any directory components.  To alter
-intermediate directories, use the @code{SUBDIR} customization variable.
-Finally, the extension may also be overriden by the customization variable
-@code{EXTENSION}.  This variable should be @code{undef} if no extension is to
-be added.  If @code{CASE_INSENSITIVE_FILENAMES} is set, 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.
-
-@vindex TOP_FILE
-Furthermore, the customization variables @code{TOP_FILE} override
-the output file name for the top element.  This is, in general,
-only taken into account when output is split.
-
-If @code{USE_ACCESSKEY} is set, the default, the @code{accesskey} attribute
-is used in navigation.  Keyboards shortcuts are set for selected directions
-only, with @kbd{n} for links to next node or section, @kbd{p} for links to
-previous previous node or section and @kbd{u} for up directions links.
-Similarly, if the @code{USE_REL_REV} customization variable is set, the
-default, the @code{rel} attribute is used in navigation to define the
-relationship between the current page and the linked resource.  For example,
-the @samp{contents} @code{rel} attribute is set for a link to the table of
-contents, the @samp{next} @code{rel} attribute is set for a link to the next
-node or section.
-
-@c internal links
-
-Internal links customization is specific of link type:
-@table @emph
-@item cross-reference command link
-@vindex XREF_USE_NODE_NAME_ARG
-If the second argument of a cross-reference command is set, it is displayed
-as hyperlink text (@pxref{Two Arguments}).  Otherwise the
-@code{XREF_USE_NODE_NAME_ARG} customization variable is used to determine the
-hyperlink text.  If set to@tie{}1, use the node name (first) argument in
-cross-reference @@-commands for the text displayed as the hyperlink.  If set
-to@tie{}0, use the node name if @code{USE_NODES} is set, otherwise the section
-name.  If set to @samp{undef}, use the first argument in preformatted
-environments, otherwise use the node name or section name depending on
-@code{USE_NODES}.  The default is @samp{undef}.
-
-@item link to float
-@vindex XREF_USE_FLOAT_LABEL
-If @code{XREF_USE_FLOAT_LABEL} is set (default is off), use the float label
-instead of the type followed by the float number (@pxref{@code{@@float}}).
-
-@item link to index entries root commands
-@vindex NODE_NAME_IN_INDEX
-In @code{@@printindex} formatting, two links are output, a link to the index
-entry and a link to the root @@-command containing the index entry.
-The @code{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 prefer section names.  If undefined, use
-@code{USE_NODES} value to determine which root @@-command to prefer.
-Default is undefined.
-
-@item menu links
-@vindex NODE_NAME_IN_MENU
-In the default case, node names are used in menu entries links.  Set
-@code{NODE_NAME_IN_MENU} to false to use section names instead.
-
-@item Table of contents links
-@vindex SHORT_TOC_LINK_TO_TOC
-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
-@code{SHORT_TOC_LINK_TO_TOC} to 0 to link to the sectioning commands instead.
-
-@vindex TOC_LINKS
-If @code{TOC_LINKS} if set, links from headings to toc entries are created;
-default false.
+@node HTML Customization Variables List
+@subsection HTML Customization Variables List
 
-@item Top node up direction link
-@vindex IGNORE_REF_TO_TOP_NODE_UP
-In the default case, no Top node Up reference is generated.  It is possible
-to ignore references to the Top node Up appearing in other cross-references
-by setting @code{IGNORE_REF_TO_TOP_NODE_UP}.  @code{IGNORE_REF_TO_TOP_NODE_UP}
-is not set in the default case.
+This table gives the customization variables which apply to HTML
+output only.  A few other customization variables apply to both HTML
+and other output formats; see @ref{Other Customization Variables}.
 
-@vindex TOP_NODE_UP_URL
-@vindex 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
-@code{TOP_NODE_UP_URL} to the URL used for Top node up references.
-If @code{TOP_NODE_UP_URL} is set, the @code{TOP_NODE_UP} customization
-variable value is used for the hyperlink text, with @samp{(dir)} as default.
+@vtable @code
+@item AVOID_MENU_REDUNDANCY
+If set, and the menu entry and menu description are the
+same, then do not print the menu description; default false.
 
-For example, for GNU @url{http://www.gnu.org/manual/} collects
-links to most GNU manuals, therefore @code{TOP_NODE_UP_URL} is
-best  specified as  @code{/manual/} if the manual
-will be installed on @code{www.gnu.org}.
+@item AFTER_BODY_OPEN
+Text added at the beginning of each HTML file; default unset.
 
-@xref{First Node} for more about the Top node pointers.
+@item AFTER_SHORT_TOC_LINES
+@itemx AFTER_TOC_LINES
+Text output after the short table of contents for
+@code{AFTER_SHORT_TOC_LINES} and after the table of
+contents for @code{AFTER_TOC_LINES} if set; otherwise, a default string is
+used.  At the time of writing, a @code{</div>} element is closed.
 
-@item images links
-@vindex IMAGE_LINK_PREFIX
-If @code{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.
-@end table
+In general, you should set @code{BEFORE_SHORT_TOC_LINES} if
+@code{AFTER_SHORT_TOC_LINES} is set, and you should set
+@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set.
 
-@c Cross references
+@item 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 (@pxref{HTML Xref Link Basics}).
 
-Cross-references between HTML manuals are specified precisely
-(@pxref{HTML Xref}).  Customization of manual locations is already provided
-through the @file{htmlxref.cnf} file (@pxref{HTML Xref Configuration}).
+@item BEFORE_SHORT_TOC_LINES
+@itemx BEFORE_TOC_LINES
+If set, text output before the short table of contents for
+@code{BEFORE_SHORT_TOC_LINES} and before the table of contents for
+@code{BEFORE_TOC_LINES}, otherwise a default string is used.  At the time of
+writing, a @code{<div ...>} element is opened.
 
-@vindex CHECK_HTMLXREF
-Defaults are used for cross-reference target manual not
-found through HTML Xref Configuration (@pxref{HTML Xref Link Basics}).  If
-you want to add all the manuals referred to to an HTML Xref configuration file,
-set @code{CHECK_HTMLXREF} to get a message for each external manual not in the
-HTML Xref configuration files.  This could be relevant, for example, if you
-know that no manual is installed locally.
+In general you should set @code{AFTER_SHORT_TOC_LINES} if
+@code{BEFORE_SHORT_TOC_LINES} is set, and you should set
+@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set.
 
-@vindex HTMLXREF_MODE
-@vindex HTMLXREF_FILE
-@vindex EXTERNAL_CROSSREF_SPLIT
-Customization variables can specify more precisely the HTML Xref Configuration.
-In the default case, the file name used for HTML Xref configuration
-is searched for in directories, and all the files found are used.
-The @code{HTMLXREF_MODE} customization variable can be set to modify how
-cross-references to other manuals information is determined.
-If @code{HTMLXREF_MODE} is set to @samp{file}, the file name is directly used
-as the source of information.  If @code{HTMLXREF_MODE} is set to @samp{none}
-no information is used.  The default case is obtained with @code{HTMLXREF_MODE}
-not defined or set to any other value.  The @code{HTMLXREF_FILE} customization
-variable sets the file used for HTML Xref configuration to another value than
-the default, @file{htmlxref.cnf}.  In the default case, the distant manual
-is considered to be split or monolithic based on the splitting of the manual
-being output.  It is possible to set it explicitely, instead, with
-@code{EXTERNAL_CROSSREF_SPLIT}.
 
-It also is possible to set customization variables to modify how
-cross-references are output in various other ways.  In general, this 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 produced using
-corresponding customization.  It is therefore, in general, better to use HTML
-Xref Configuration only.
+@item BIG_RULE
+Rule used after and before the top element and before
+special elements, but not for footers and headers; default
+@code{<hr>}.
 
-The file name used for the Top node in cross-references is set to
-the @code{TOP_NODE_FILE_TARGET} customization variable value; default is
-@file{index.html}.  A base directory for external manuals is specified
-with @code{EXTERNAL_DIR}, in the default case there is none.  Similarly,
-the file extension for cross-references to other manuals is set with
-@code{EXTERNAL_CROSSREF_EXTENSION}, which, if unset, is based
-on @code{EXTENSION}.  In the default case, the base file names are truncated
-to 245 characters (@pxref{HTML Xref Link Basics}).  The maximum length of a
-base file name is changed by setting @code{BASEFILENAME_LENGTH}.
+@cindex @code{<body>} text, customizing
+@opindex lang@r{, HTML attribute}
+@item BODYTEXT
+The @code{<body>} attributes text.  By default, sets the
+HTML @code{lang} attribute to the document language
+(@pxref{@code{@@documentlanguage}}).
 
+@item CASE_INSENSITIVE_FILENAMES
+Construct output file names as if the filesystem were case
+insensitive (@pxref{HTML Splitting}); default false.
 
-@node Customization of Navigation and Headers
-@subsection Customization of Navigation and Headers
+@item CHAPTER_HEADER_LEVEL
+Header formatting level used for chapter level sectioning
+commands; default @samp{2}.
 
-Headers with a navigation panel are output in the default case.  if
-@option{--no-headers} is used or the customization variable @code{HEADERS}
-is unset, the navigation bar is only inserted at the beginning of
-split files.
+@item CHECK_HTMLXREF
+Check that manuals which are the target of external
+cross-references (@pxref{Four and Five Arguments}) are present in
+@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false.
 
-In the default case, @code{<link>} elements are generated in the
-HTML @code{<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 @code{USE_LINKS} to avoid those elements.
+@item COMPLEX_FORMAT_IN_TABLE
+If set, use tables for indentation of complex formats; default
+false.
 
-The @code{<title>} and the document description in @code{<head>}
-are based on @code{@@settitle} (@pxref{@code{@@settitle}}).
-If the manual is split, the node name is also added to this HTML title.
-If @code{SECTION_NAME_IN_TITLE} is set, the argument of the associated
-chapter structuring command is used instead of the node name.
+@item CONTENTS_OUTPUT_LOCATION
+If set to @samp{after_top}, output the contents at the end of the @code{@@top}
+section.  If set to @samp{inline}, output the contents where the
+@code{@@contents} and similar @@-commands are located.  If set to
+@samp{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
+@samp{after_title} the tables of contents are output after the title; default
+@samp{after_top}.
 
-When output is split at nodes (@pxref{HTML Splitting}), the
-@code{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.
+@item CONVERT_TO_LATEX_IN_MATH
+If set, try to convert any Texinfo @@-commands inside @code{@@math} and
+@code{@@displaymath} to @LaTeX{}, before converting the @code{@@math} or
+@code{@@displaymath} to HTML.  Default @code{undef}.  If undefined,
+set if @code{HTML_MATH} is set.
 
-The appearance of the navigation panel is affected by the following
-customization variables, false in the default case:
+@item COPIABLE_LINKS
+If set, output copiable links for the definition commands
+(@pxref{Definition Commands}), table commands (@pxref{Two-column
+Tables}) where an index entry is defined and headings.  A link appears
+as a `@U{00B6}'
+@c pilcrow sign
+sign that appears when you hover the mouse pointer over the heading text.
 
-@vtable @code
 @item DATE_IN_HEADER
-Put the document generation date in the header.
-
-@item HEADER_IN_TABLE
-Use tables for header formatting rather than a simple @samp{<div>}.
-
-@item ICONS
-Use icons for the navigation panel.
-
-@item PROGRAM_NAME_IN_FOOTER
-If set, output the program name and miscellaneous related information in the
-page footers.
-
-@item VERTICAL_HEAD_NAVIGATION
-If set, a vertical navigation panel is used.
-@end vtable
-
-Setting @code{ICONS} is necessary but not sufficient to get icons for direction
-buttons since no button image is specified in the default case.
-The @code{ACTIVE_ICONS} and @code{PASSIVE_ICONS} customization
-variables need to be set in addition.  This requires using an
-initialization file (@pxref{Invoking @command{texi2any}}).
-@xref{,,, texi2any_api, GNU Texinfo @command{texi2any} Output Customization}.
-
+Put the document generation date in the header; off by default.
 
-@node General Customization of HTML Code
-@subsection General Customization of HTML Code
+@item DEF_TABLE
+If set, a @code{<table>} construction for @code{@@deffn}
+and similar @@-commands is used (looking more like the @TeX{} output),
+instead of definition lists; default false.
 
-The generated HTML code may be modified in two way.  Firstly by specifying
-broad features of the generated HTML and secondly by inserting
-some HTML code in a few specific places.
+@item DEFAULT_RULE
+Rule used between element, except before and after the
+top element, and before special elements, and for footers and headers;
+default @code{<hr>}.
 
-In the default case, HTML is generated, but it is also possible to
-generate XML compatible code, by setting @code{USE_XML_SYNTAX}.  The main
-difference is that @samp{/>} instead of @samp{>} closes elements with an
-opening element, but no closing element, such as @code{<img>} or @code{<link>}
-(also called @dfn{void elements}).
-To set the @dfn{DOCTYPE}, set the @code{DOCTYPE} customization variable.
-The default is the HTML5 DTD-less simple DOCTYPE.
+@item DO_ABOUT
+If set to 0 never do an About special element;
+if set to 1 always do an About special element;
+default 0.
+@c @xref{Output Elements Defined}.
 
-In the default case, entities are used for doubled single-quote characters
-(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
-(@pxref{Conventions}).  Set @code{USE_ISO} to @samp{0} in the unlikely case
-that you want a simpler formatting.
-In the default case, textual entities are used when possible.  Set
-@code{USE_NUMERIC_ENTITY} to use numeric entities only.
-Set @code{OUTPUT_CHARACTERS} to output accented characters based on
-the output encoding instead of entities.
+@item 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 @code{SPLIT}.  @xref{HTML Xref}, and @pxref{HTML
+Xref Configuration}.
 
-In the default case, 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, it is
-possible to set @code{NO_CUSTOM_HTML_ATTRIBUTE} to prevent custom attributes to
-be output.
+@item EXTERNAL_DIR
+Base directory for external manuals; default none.  It is
+better to use the general external cross-reference mechanism
+(@pxref{HTML Xref Configuration}) than this variable.
 
-To change the HTML code for breaks (horizontal rule) inserted in various
-contexts, set @code{DEFAULT_RULE},
-used for most horizontal separators output in the resulting HTML,
-and set @code{BIG_RULE} for the wider separator sometime used.
+@item EXTERNAL_CROSSREF_EXTENSION
+File extension for cross-references to other manuals.  If unset,
+based on @code{EXTENSION}.
 
-Copiable links are output for link targets for the definition commands
-(@pxref{Definition Commands}), table commands (@pxref{Two-column
-Tables}) where an index entry is defined and headings.  A link appears
-as a `@U{00B6}'
-@c pilcrow sign
-sign that appears when you hover the mouse pointer over the heading text.
-Unset @code{COPIABLE_LINKS} to prevent copiable links output.
+@item EXTRA_HEAD
+Additional text appearing within @code{<head>}; default unset.
 
-@c Arguments are HTML content to be inserted at certain points in the output.
+@item FOOTNOTE_END_HEADER_LEVEL
+Header formatting level used for the footnotes header with
+the `end' footnotestyle; default @samp{4}.  @xref{Footnote Styles}.
 
-@vindex HTML_ROOT_ELEMENT_ATTRIBUTES
-@vindex EXTRA_HEAD
-@vindex AFTER_BODY_OPEN
-@cindex @code{<head>} block, adding to
-@vindex BODYTEXT
-You can set @code{HTML_ROOT_ELEMENT_ATTRIBUTES} to add attributes to
-the @code{<html>} element.
-You can define the variable @code{EXTRA_HEAD} to add text within the
-@code{<head>} HTML element.  Similarly, the value of
-@code{AFTER_BODY_OPEN} is added just after @code{<body>} is output.
-These variables are empty by default.
-@cindex @code{<body>} tag, attributes of
-The @code{<body>} element attributes may be set by defining the
-customization variable @code{BODYTEXT}.
+@item FOOTNOTE_SEPARATE_HEADER_LEVEL
+Header formatting level used for the footnotes header with
+the `separate' footnotestyle; default @samp{4}.  @xref{Footnote
+Styles}.
 
-@vindex PRE_BODY_CLOSE
-You can define the variable @code{PRE_BODY_CLOSE} to add text just
-before the HTML @code{</body>} element.  Nothing is added by default.
+@item HEADER_IN_TABLE
+Use tables for header formatting rather than a simple
+@code{<div>} element; default false.
 
-Similarly, the following variables allow for some useful control of the
-formatting of table of contents and short table of contents:
+@item HTML_MATH
+Method to use to render @code{@@math}.  This can be unset, set to
+@samp{mathjax} (@pxref{MathJax Customization Variables}),
+set to @samp{l2h}, which uses @command{latex2html}
+(@pxref{@command{latex2html} Customization Variables}), or set to
+@samp{t4h}, which uses @command{tex4ht}
+(@pxref{@command{tex4ht} Customization Variables}).  In the default case,
+setting @code{HTML_MATH} also sets @code{CONVERT_TO_LATEX_IN_MATH}.
 
-@vtable @code
-@item BEFORE_TOC_LINES
-Inserted before the table of contents text.
+@item HTML_ROOT_ELEMENT_ATTRIBUTES
+Use that string for the @code{<html>} HTML document root element.
+Default undefined.
 
-@item AFTER_TOC_LINES
-Inserted after the table of contents text.
+@item HTMLXREF_FILE
+Set the file name used for cross-references to other manuals.  If
+not defined, @file{htmlxref.cnf} is used (@pxref{HTML Xref Configuration}).
+Not defined in the default case.  If @code{TEST} is set, @code{HTMLXREF_MODE}
+is set to the default and @code{HTMLXREF_FILE} is not defined, information on
+cross-references to other manuals is not used.
 
-@item BEFORE_SHORT_TOC_LINES
-Inserted before the short table of contents text.
+If @code{HTMLXREF_MODE} is set to @samp{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 (@pxref{HTML Xref
+Configuration}).
 
-@item AFTER_SHORT_TOC_LINES
-Inserted after the short table of contents text.
+@item HTMLXREF_MODE
+How cross-references to other manuals information is determined.
+If set to @samp{none}, no information is used.  If set to @samp{file},
+the information is determined from a file path, @file{htmlxref.cnf}
+in the default case, or the value of @code{HTMLXREF_FILE}.  If not defined
+(the default) or set to any other value, search in
+directories and use all the files (@pxref{HTML Xref Configuration}).
 
-@end vtable
-At the time of writing, these variables default values are set to
-@code{<div>} elements opening and closing for tables of contents.
+@item ICONS
+Use icons for the navigation panel; default false.
 
-@ignore
-Could be an example, but would need either to specify as command-line
-arguments, which would be cumbersome, or requires knowing about init
-files
-@c output valid XHTML XML 1.0 Document
-@example
-texinfo_set_from_init_file('HTML_ROOT_ELEMENT_ATTRIBUTES',
-                           'xmlns="http://www.w3.org/1999/xhtml";');
-texinfo_set_from_init_file('NO_CUSTOM_HTML_ATTRIBUTE', 1);
-texinfo_set_from_init_file('USE_XML_SYNTAX', 1);
-texinfo_set_from_init_file('DOCTYPE', '<?xml version="1.0" 
encoding="UTF-8"?>'."\n"
-                                      .'<!DOCTYPE html>');
-texinfo_set_from_init_file('USE_NUMERIC_ENTITY', 1);
-texinfo_set_from_init_file('OUTPUT_ENCODING_NAME', 'utf-8');
-@end example
+@item IMAGE_LINK_PREFIX
+If set, the associated value is prepended to the image file
+links; default unset.
 
-@end ignore
+@item INDEX_ENTRY_COLON
+Symbol used between the index entry and the associated node or section;
+default is an empty string.
 
-@node Specific Customization of HTML Formatting
-@subsection Specific Customization of HTML Formatting
+@item 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.@: @samp{texi2any --html
+-c INFO_JS_DIR=js @var{manual}.texi} to place files in a @samp{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.
 
-@c The appearance of specific construct is customizable.
+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.
 
-@c Header levels
+@item IGNORE_REF_TO_TOP_NODE_UP
+Ignore references to @code{TOP_NODE_UP}, the up node for the Top node.
 
-In HTML, heading levels translate to @samp{<h@var{n}>} elements
-where @var{n} is the heading level.  The following header levels are
-customizable:
+@item INLINE_CSS_STYLE
+Put CSS directly in HTML elements rather than at the
+beginning of the output; default false.
 
-@vtable @code
-@item CHAPTER_HEADER_LEVEL
-Header formatting level used for chapter level sectioning
-commands; default @samp{2}.
+@item JS_WEBLABELS
+@itemx JS_WEBLABELS_FILE
+Specify how to use a @dfn{JavaScript license web labels} page to
+give licensing information and source code for any JavaScript used
+in the HTML files for the manual.
+(See @uref{https://www.gnu.org/licenses/javascript-labels.html}).
 
-@item COMPLEX_FORMAT_IN_TABLE
-If set, use tables for indentation of complex formats; default
-false.
+With the value @samp{generate} (the default), generate a labels page
+at @code{JS_WEBLABELS_FILE}, and link to it in the HTML output files.
+Only do this if actually referencing JavaScript files (either with
+@code{HTML_MATH} set to @samp{mathjax}, or when using the experimental
+JS browsing interface when @code{INFO_JS_DIR} is set).  With this
+setting, @code{JS_WEBLABELS_FILE} must be a relative file name.
 
-@item FOOTNOTE_END_HEADER_LEVEL
-@itemx FOOTNOTE_SEPARATE_HEADER_LEVEL
-Header formatting level used for the footnotes header with
-the `end' footnotestyle or for the `separate' footnotestyle; default @samp{4}.
-@xref{Footnote Styles}.
+With the value @samp{reference}, link to the labels
+file given by @code{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 @samp{omit}, neither generate nor link to a labels file.
 
 @item MAX_HEADER_LEVEL
 Maximum header formatting level used (higher header
 formatting level numbers correspond to lower sectioning levels);
 default @samp{4}.
 
-@end vtable
-
-
-@c Menu  Options for the output of @@menu, as well as indices.
-@c Output of other constructs
-
-The appearance of various constructs may be modified by setting:
-@vtable @code
-@item DEF_TABLE
-If set, a @code{<table>} construction for @code{@@deffn}
-and similar @@-commands is used (looking more like the @TeX{} output),
-instead of definition lists; default false.
-
-@item INDEX_ENTRY_COLON
-Symbol used between the index entry and the associated node or section;
-default is an empty string.
-
 @item MENU_ENTRY_COLON
 Symbol used between the menu entry and the description; default
 @samp{:}.
@@ -15999,2984 +15786,3206 @@ for menu entries formatting; default is undefined 
and set to
 @code{&bull;} if @code{USE_NUMERIC_ENTITY} is not set, and to
 @code{&#8217;} if set.
 
-@item NUMBER_FOOTNOTES
-@itemx NO_NUMBER_FOOTNOTE_SYMBOL
-In the default case footnotes are numbered.  With
-@option{--no-number-footnotes} or if @code{NUMBER_FOOTNOTES} is set to 0, a
-@samp{*} is used instead, or the @code{NO_NUMBER_FOOTNOTE_SYMBOL} customization
-variable value, if set.
+@item MONOLITHIC
+Output only one file including the table of contents.  Set
+by default, but only relevant when the output is not split.
+
+@item NO_CSS
+Do not use CSS; default false.  @xref{HTML CSS}.
+
+@item NO_CUSTOM_HTML_ATTRIBUTE
+Do not output HTML with custom attributes in elements; default false.
+
+@item NO_NUMBER_FOOTNOTE_SYMBOL
+Symbol used for footnotes if @code{NUMBER_FOOTNOTES} is false.
+Default is @code{*}.
+
+@item NODE_NAME_IN_INDEX
+If true, use node names in index entries, otherwise prefer section names.
+If undefined, use @code{USE_NODES} value in HTML.  Default is undefined.
+
+@item PRE_BODY_CLOSE
+If set, the given text will appear at the footer of each
+HTML file; default unset.
 
 @item 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.
-@end vtable
 
-@c proposal to be removed
-@c AVOID_MENU_REDUNDANCY
+@item PROGRAM_NAME_IN_FOOTER
+If set, output the program name and miscellaneous related
+information in the page footers; default false.
+
+@item SECTION_NAME_IN_TITLE
+If set,  when output is split, use the argument of the chapter
+structuring command (e.g., @code{@@chapter} or @code{@@section})
+in the @code{<title>} instead of the argument to @code{@@node}.
+
+@item 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.
+
+@item SHOW_BUILTIN_CSS_RULES
+Output the built-in default CSS rules on the standard output and exit.
+
+@item SHOW_TITLE
+If set, output the title at the beginning of the document;
+default @samp{undef}.  If set to @samp{undef}, setting
+@code{NO_TOP_NODE_OUTPUT} also sets @code{SHOW_TITLE} for HTML.
+
+@item TOC_LINKS
+If set, links from headings to toc entries are created;
+default false.
+
+@item 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@.
+
+@item TOP_NODE_FILE_TARGET
+File name used for the Top node in cross-references;
+default is @code{index.html}.
+
+@item TOP_NODE_UP_URL
+A URL used for Top node up references; the default is
+@code{undef}, in that case no Top node Up reference is generated.
+For more about the Top node pointers, @pxref{First Node}.  For 
+overriding the Up pointer name in case @code{TOP_NODE_UP_URL} is set
+and for other formats, see @code{TOP_NODE_UP} in 
+@ref{Other Customization Variables}.
 
+@cindex @code{accesskey} @subentry customization variable for
+@item USE_ACCESSKEY
+Use @code{accesskey} in cross-references; default true.
 
-@node HTML Customization for Math
-@subsection HTML Customization for Math
+@item USE_ISO
+Use entities for doubled single-quote characters
+(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
+(@pxref{Conventions}); default true.
 
-Diverse methods can be used to render math in HTML (@pxref{Inserting Math}).
-The is controlled by the @code{HTML_MATH} customization variable
-value.  In the default case, the customization variable is unset
-and the HTML output is only emphasized.  Better options for
-displaying properly formatted mathematics may be selected.  Some of
-these options also translate @code{@@tex} if @option{--iftex} is set,
-and @code{@@latex} sections if @option{--iflatex} is set.
+@cindex @code{<link>} HTML tag, in @code{<head>}
+@cindex @code{<head>} HTML tag, and @code{<link>}
+@item USE_LINKS
+Generate @code{<link>} elements in the HTML @code{<head>}
+output; default true.
 
-@table @code
-@item l2h
-Use the @command{latex2html} program to produce
-image files for mathematical material.
+@item USE_NEXT_HEADING_FOR_LONE_NODE
+If set, a node not associated to a sectioning command but
+followed by a heading command not usually associated to node
+such as @code{@@heading} before other formatted contents
+do not have its name output as a heading, under the assumption
+that the command found provides the heading.  Default true.
 
-@command{latex2html} will process @LaTeX{} math in math commands,
-including @TeX{} math compatible with @LaTeX{}.
-@command{latex2html} is used to translates @code{@@tex}
-and @code{@@latex} sections to HTML if the corresponding sections
-are not ignored.  Note that @command{latex2html} can only process @LaTeX{},
-including when processing @code{@@tex} sections.
+@item 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
+@code{USE_NODES} value.  Default is undefined.  Note that this setting does not
+determine the link string only where the links points to, see @ref{Three
+Arguments, , xrefautomaticsectiontitle} for the link string customization.  If
+nodes and sections are systematically associated, this customization has no
+practical effect.
 
-Processing with @command{latex2html} should leave files in the
-output directory, with @samp{-l2h} in their name, in particular
-a cache file to avoid redoing translation HTML if already done.
+@item USE_REL_REV
+Use @code{rel} in cross-references; default true.
 
-@xref{@command{latex2html} Customization Variables}.
+@item USE_TITLEPAGE_FOR_TITLE
+Use the full @code{@@titlepage} as the title, not a simple title string;
+default true.  Only relevant if @code{SHOW_TITLE} is set.
 
-@item mathjax
-@anchor{MathJax scripts}
-Inserts references in the output files to MathJax scripts to format the
-material.  The MathJax option requires JavaScript
-to be enabled in the browser to work.
+@item USE_XML_SYNTAX
+Use XML/XHTML compatible syntax.
 
-MathJax handles @LaTeX{} math, including @TeX{}
-math compatible with @LaTeX{} commonly used.  Some specific constructs
-(for example some uses of @code{\text}) are not supported, but this should
-not be a practical issue.
+@item VERTICAL_HEAD_NAVIGATION
+If set, a vertical navigation panel is used; default false.
 
-If math commands are actually processed, a JavaScript license web label is
-generated for MathJax scripts (@pxref{JavaScript license web labels}).
+@cindex Navigation panel, bottom of page
+@cindex Navigation footer
+@item 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{MathJax Customization Variables}.
+@item 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
+(@pxref{@code{@@float}}).  The default is off.
 
-@item t4h
-Use the @command{tex4ht} to produce HTML for mathematical material.
+@item XREF_USE_NODE_NAME_ARG
+Only relevant for cross-reference commands with no cross
+reference name (second argument).  If set to@tie{}1, use the node name
+(first) argument in cross-reference @@-commands for the text displayed
+as the hyperlink.  If set to@tie{}0, use the node name if
+@code{USE_NODES} is set, otherwise the section name.  If set to
+@samp{undef}, use the first argument in preformatted environments,
+otherwise use the node name or section name depending on
+@code{USE_NODES}.  The default is @samp{undef}.
 
-@command{tex4ht} will process @LaTeX{} math in math commands,
-including @TeX{} math compatible with @LaTeX{}.
-@command{tex4ht} is used to translates @code{@@tex} and @code{@@latex}
-sections to HTML if the sections are not ignored.  The @code{@@tex} sections
-are processed in @TeX{} mode, while the @code{@@latex} sections are
-processed as @LaTeX{}.
+@end vtable
 
-Processing with @command{tex4ht} should leave files in the
-output directory, with @samp{_tex4ht} in their name.
 
-@xref{@command{tex4ht} Customization Variables}.
+@node MathJax Customization Variables
+@subsection MathJax Customization Variables
 
-@end table
+This table lists the customization variables which can be used when 
+MathJax is being used, which will be the case when @code{HTML_MATH}
+is set to @samp{mathjax}.
 
-In the default case, with @code{CONVERT_TO_LATEX_IN_MATH} undefined,
-setting @code{HTML_MATH} also sets @code{CONVERT_TO_LATEX_IN_MATH}.
-In that case Texinfo @@-commands inside @code{@@math} and @code{@@displaymath}
-are converted to @LaTeX{}, before converting the @code{@@math} or
-@code{@@displaymath} to HTML.
+@vtable @code
+@item MATHJAX_SCRIPT
+URL of the MathJax component file (e.g.@: @file{tex-svg.js}) you are using.
+@command{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.
 
+@item 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 @code{MATHJAX_SCRIPT}.  `Preferred form for modification'
+means that this should not be in a `minified' form.  Used in the
+license labels page (@pxref{HTML Customization Variables List}, under
+@code{JS_WEBLABELS}).
 
-@node HTML Customization Variables List
-@subsection HTML Customization Variables List
+Again, @command{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.
+@end vtable
 
-This table gives the customization variables which apply to HTML
-output only.  A few other customization variables apply to both HTML
-and other output formats; see @ref{Other Customization Variables}.
 
-@vtable @code
-@item AVOID_MENU_REDUNDANCY
-If set, and the menu entry and menu description are the
-same, then do not print the menu description; default false.
+@node @command{latex2html} Customization Variables
+@subsection @command{latex2html} Customization Variables
 
-@item AFTER_BODY_OPEN
-Text added at the beginning of each HTML file; default unset.
+This table lists the customization variables which can be used when 
+@command{latex2html} is being used to convert @code{@@math},
+@code{@@displaymath}, @code{@@latex} and @code{@@tex} sections for HTML@.
+These customization variables are relevant only if @code{HTML_MATH} is set to
+@samp{l2h}.
 
-@item AFTER_SHORT_TOC_LINES
-@itemx AFTER_TOC_LINES
-Text output after the short table of contents for
-@code{AFTER_SHORT_TOC_LINES} and after the table of
-contents for @code{AFTER_TOC_LINES} if set; otherwise, a default string is
-used.  At the time of writing, a @code{</div>} element is closed.
+To actually convert @code{@@tex} sections, @option{--iftex} should be used,
+and to actually convert @code{@@latex} sections, @option{--iflatex} should be
+used.
 
-In general, you should set @code{BEFORE_SHORT_TOC_LINES} if
-@code{AFTER_SHORT_TOC_LINES} is set, and you should set
-@code{BEFORE_TOC_LINES} if @code{AFTER_TOC_LINES} is set.
+@vtable @code
+@item L2H_CLEAN
+If set, the intermediate files generated in relation with @command{latex2html}
+are removed; default true.
 
-@item 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 (@pxref{HTML Xref Link Basics}).
+@item L2H_FILE
+If set, the given file is used as @command{latex2html}'s init file; default
+unset.
 
-@item BEFORE_SHORT_TOC_LINES
-@itemx BEFORE_TOC_LINES
-If set, text output before the short table of contents for
-@code{BEFORE_SHORT_TOC_LINES} and before the table of contents for
-@code{BEFORE_TOC_LINES}, otherwise a default string is used.  At the time of
-writing, a @code{<div ...>} element is opened.
+@item L2H_HTML_VERSION
+The HTML version used in the @command{latex2html} call; default unset.
 
-In general you should set @code{AFTER_SHORT_TOC_LINES} if
-@code{BEFORE_SHORT_TOC_LINES} is set, and you should set
-@code{AFTER_TOC_LINES} if @code{BEFORE_TOC_LINES} is set.
+@item L2H_L2H
+The program invoked as @command{latex2html}; default is @code{latex2html}.
 
+@item L2H_SKIP
+If set to a true value, the actual call to @command{latex2html} is skipped;
+previously generated content is reused instead.  If set to 0, the cache is not
+used at all.  If set to @samp{undef}, the cache is used for as many @TeX{}
+fragments as possible and for any remaining the command is run.  The default is
+@samp{undef}.
 
-@item BIG_RULE
-Rule used after and before the top element and before
-special elements, but not for footers and headers; default
-@code{<hr>}.
+@item L2H_TMP
+Set the directory used for temporary files.  None of the file name components
+in this directory name may start with @samp{.}; otherwise, @command{latex2html}
+will fail (because of @command{dvips}).  The default is the empty string, which
+means the current directory.
+@end vtable
 
-@cindex @code{<body>} text, customizing
-@opindex lang@r{, HTML attribute}
-@item BODYTEXT
-The @code{<body>} attributes text.  By default, sets the
-HTML @code{lang} attribute to the document language
-(@pxref{@code{@@documentlanguage}}).
 
-@item CASE_INSENSITIVE_FILENAMES
-Construct output file names as if the filesystem were case
-insensitive (@pxref{HTML Splitting}); default false.
+@node @command{tex4ht} Customization Variables
+@subsection @command{tex4ht} Customization Variables
 
-@item CHAPTER_HEADER_LEVEL
-Header formatting level used for chapter level sectioning
-commands; default @samp{2}.
+This table lists the customization variables which can be used when
+@command{tex4ht} is being used to convert @code{@@math}, @code{@@displaymath},
+@code{@@tex} and @code{@@latex} sections for HTML@.  These customization
+variables are relevant only if @code{HTML_MATH} is set to @samp{t4h}.
 
-@item CHECK_HTMLXREF
-Check that manuals which are the target of external
-cross-references (@pxref{Four and Five Arguments}) are present in
-@file{htmlxref.cnf} (@pxref{HTML Xref Configuration}); default false.
+To actually convert @code{@@tex} sections, @option{--iftex} should be used,
+and to actually convert @code{@@latex} sections, @option{--iflatex} should be
+used.
 
-@item COMPLEX_FORMAT_IN_TABLE
-If set, use tables for indentation of complex formats; default
-false.
+@vtable @code
+@item T4H_LATEX_CONVERSION
+If set, the conversion type used for @code{@@latex} sections.  Possibilities
+are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{latex} if not
+defined.
 
-@item CONTENTS_OUTPUT_LOCATION
-If set to @samp{after_top}, output the contents at the end of the @code{@@top}
-section.  If set to @samp{inline}, output the contents where the
-@code{@@contents} and similar @@-commands are located.  If set to
-@samp{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
-@samp{after_title} the tables of contents are output after the title; default
-@samp{after_top}.
+@item T4H_MATH_CONVERSION
+If set, the conversion type used for @code{@@math} and @code{@@displymath}.
+Possibilities are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{tex}
+if not defined.
 
-@item CONVERT_TO_LATEX_IN_MATH
-If set, try to convert any Texinfo @@-commands inside @code{@@math} and
-@code{@@displaymath} to @LaTeX{}, before converting the @code{@@math} or
-@code{@@displaymath} to HTML.  Default @code{undef}.  If undefined,
-set if @code{HTML_MATH} is set.
+@item T4H_TEX_CONVERSION
+If set, the conversion type used for @code{@@tex} sections.  Possibilities
+are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{tex} if not
+defined.
+@end vtable
 
-@item COPIABLE_LINKS
-If set, output copiable links for the definition commands
-(@pxref{Definition Commands}), table commands (@pxref{Two-column
-Tables}) where an index entry is defined and headings.  A link appears
-as a `@U{00B6}'
-@c pilcrow sign
-sign that appears when you hover the mouse pointer over the heading text.
 
-@item DATE_IN_HEADER
-Put the document generation date in the header; off by default.
+@node @LaTeX{} Customization Variables
+@subsection @LaTeX{} Customization Variables
 
-@item DEF_TABLE
-If set, a @code{<table>} construction for @code{@@deffn}
-and similar @@-commands is used (looking more like the @TeX{} output),
-instead of definition lists; default false.
+@cartouche
+@quotation warning
+@LaTeX{} output customization is experimental.  Nothing is decided,
+everything can change, and we would welcome any feedback.
+@end quotation
+@end cartouche
 
-@item DEFAULT_RULE
-Rule used between element, except before and after the
-top element, and before special elements, and for footers and headers;
-default @code{<hr>}.
+This table gives the customization variables which apply to @LaTeX{} output
+only.
 
-@item DO_ABOUT
-If set to 0 never do an About special element;
-if set to 1 always do an About special element;
-default 0.
-@c @xref{Output Elements Defined}.
+@vtable @code
+@item CLASS_BEGIN_USEPACKAGE
+If set, the corresponding text will replace the @LaTeX{} @code{\documentclass},
+package imports that are always output and are output right after
+@code{\documentclass}, and package imports that depend on the document encoding
+setting the input and font encoding (@code{inputenc} and @code{fontenc}).
 
-@item 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 @code{SPLIT}.  @xref{HTML Xref}, and @pxref{HTML
-Xref Configuration}.
+The text replaced is along:
+@example LaTeX
+\documentclass@{book@}
+\usepackage@{amsfonts@}
+\usepackage@{amsmath@}
+\usepackage[gen]@{eurosym@}
+\usepackage@{textcomp@}
+\usepackage@{graphicx@}
+\usepackage@{etoolbox@}
+\usepackage@{titleps@}
+\usepackage[utf8]@{inputenc@}
+\usepackage[T1]@{fontenc@}
+@end example
 
-@item EXTERNAL_DIR
-Base directory for external manuals; default none.  It is
-better to use the general external cross-reference mechanism
-(@pxref{HTML Xref Configuration}) than this variable.
+@item END_USEPACKAGE
+If set, the corresponding text will replace the package imports that depend
+on the Texinfo commands used, and the last packages imports that are always
+output and output after all the other packages imports.  The last package
+imports corresponds to @samp{\usepackage[hidelinks]@{hyperref@}}.
 
-@item EXTERNAL_CROSSREF_EXTENSION
-File extension for cross-references to other manuals.  If unset,
-based on @code{EXTENSION}.
+Here is an example of the corresponding text for a document with indices,
+@code{@@need}, @code{@@multitable}, definition commands, @code{@@cartouche},
+lists, and @code{@@float}:
+@example LaTeX
+\usepackage@{imakeidx@}
+\usepackage@{needspace@}
+\usepackage@{array@}
+\usepackage@{embrac@}
+\usepackage@{expl3@}
+\usepackage@{tabularx@}
+\usepackage[framemethod=tikz]@{mdframed@}
+\usepackage@{enumitem@}
+\usepackage@{float@}
+\usepackage[hidelinks]@{hyperref@}
+@end example
+@end vtable
 
-@item EXTRA_HEAD
-Additional text appearing within @code{<head>}; default unset.
 
-@item FOOTNOTE_END_HEADER_LEVEL
-Header formatting level used for the footnotes header with
-the `end' footnotestyle; default @samp{4}.  @xref{Footnote Styles}.
+@node Other Customization Variables
+@subsection Other Customization Variables
 
-@item FOOTNOTE_SEPARATE_HEADER_LEVEL
-Header formatting level used for the footnotes header with
-the `separate' footnotestyle; default @samp{4}.  @xref{Footnote
-Styles}.
+This table gives the remaining customization variables, which apply to
+multiple formats, or affect global behavior, or otherwise don't fit
+into the categories of the previous sections.
 
-@item HEADER_IN_TABLE
-Use tables for header formatting rather than a simple
-@code{<div>} element; default false.
+@vtable @code
+@item ASCII_DASHES_AND_QUOTES
+For Info output, when set, use plain ASCII characters to represent
+quotation marks, hyphens and dashes when these are given in the Texinfo
+source as @samp{-}, @samp{--}, @samp{---}, @samp{`}, @samp{``},
+@samp{'}, and @samp{''}, rather than UTF-8 directional quotation marks,
+en dashes, vel sim.  On by default.
 
-@item HTML_MATH
-Method to use to render @code{@@math}.  This can be unset, set to
-@samp{mathjax} (@pxref{MathJax Customization Variables}),
-set to @samp{l2h}, which uses @command{latex2html}
-(@pxref{@command{latex2html} Customization Variables}), or set to
-@samp{t4h}, which uses @command{tex4ht}
-(@pxref{@command{tex4ht} Customization Variables}).  In the default case,
-setting @code{HTML_MATH} also sets @code{CONVERT_TO_LATEX_IN_MATH}.
+@item ASCII_GLYPH
+For Info output, use ASCII output for glyph commands such as the copyright
+sign (@command{@@copyright@{@}}, becoming @samp{(C)}),
+and the bullet symbol (@command{@@bullet@{@}}, becoming @samp{*}), rather
+than other Unicode sequences.  Off by default.
 
-@item HTML_ROOT_ELEMENT_ATTRIBUTES
-Use that string for the @code{<html>} HTML document root element.
-Default undefined.
+@item ASCII_PUNCTUATION
+Avoid any unncessary or gratuitious non-ASCII, UTF-8 sequences in the
+output.  Implies both @code{ASCII_DASHES_AND_QUOTES} and @code{ASCII_GLYPH}
+and additionally affects the output of commands such as @code{@@samp} which
+output quotation marks.
 
-@item HTMLXREF_FILE
-Set the file name used for cross-references to other manuals.  If
-not defined, @file{htmlxref.cnf} is used (@pxref{HTML Xref Configuration}).
-Not defined in the default case.  If @code{TEST} is set, @code{HTMLXREF_MODE}
-is set to the default and @code{HTMLXREF_FILE} is not defined, information on
-cross-references to other manuals is not used.
+@item AUTO_MENU_DESCRIPTION_ALIGN_COLUMN
+For Info output, column at which to start a menu entry description
+provided by @code{@@nodedescription} or @code{@@nodedescriptionblock}.
+Undefined by default, in which case 45% of the fill column value is used
+(@pxref{Invoking @command{texi2any}}).
 
-If @code{HTMLXREF_MODE} is set to @samp{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 (@pxref{HTML Xref
-Configuration}).
+@item AUTO_MENU_MAX_WIDTH
+Maximum number of columns in a menu entry line in Info when adding a
+description from @code{@@nodedescription} or @code{@@nodedescriptionblock}.
+Undefined by default, in which case 10% more than the fill column value
+is used (@pxref{Invoking @command{texi2any}}).
 
-@item HTMLXREF_MODE
-How cross-references to other manuals information is determined.
-If set to @samp{none}, no information is used.  If set to @samp{file},
-the information is determined from a file path, @file{htmlxref.cnf}
-in the default case, or the value of @code{HTMLXREF_FILE}.  If not defined
-(the default) or set to any other value, search in
-directories and use all the files (@pxref{HTML Xref Configuration}).
+@item CHECK_MISSING_MENU_ENTRY
+When a @code{@@menu} block occurs in a node, check if there is a menu
+entry for all subordinate nodes in the document sectioning structure.  On
+by default.
 
-@item ICONS
-Use icons for the navigation panel; default false.
+@item CHECK_NORMAL_MENU_STRUCTURE
+Warn if the node pointers (either explicitly or automatically set)
+are not consistent with the order of node menu entries.  This is a more
+thorough structure check than that provided by
+@code{CHECK_MISSING_MENU_ENTRY}.  Off by default.
 
-@item IMAGE_LINK_PREFIX
-If set, the associated value is prepended to the image file
-links; default unset.
+@item CLOSE_QUOTE_SYMBOL
+When a closing quote is needed, e.g. for @code{@@samp} output, use
+this character; default @code{&#8217;} in DocBook.
+Undefined in the default case in HTML and set to @code{&rsquo;}
+if @code{USE_NUMERIC_ENTITY} is not set, to @code{&#8217;} if set, and
+to a quote character if @code{OUTPUT_CHARACTERS} is set and the output
+encoding includes that character.
 
-@item INDEX_ENTRY_COLON
-Symbol used between the index entry and the associated node or section;
-default is an empty string.
+The default for Info is set the same as for @code{OPEN_QUOTE_SYMBOL},
+except that the Unicode code is a closing quote (see below).
 
-@item 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.@: @samp{texi2any --html
--c INFO_JS_DIR=js @var{manual}.texi} to place files in a @samp{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.
+@item CLOSE_DOUBLE_QUOTE_SYMBOL
+When a closing double quote is needed, for @samp{@@dfn} in Info, use this
+character.  The default for Info is set the same as for
+@code{OPEN_DOUBLE_QUOTE_SYMBOL}, except that the Unicode code is a closing
+double quote (see below).
 
-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.
+@item COLLATION_LANGUAGE
+By default, @command{texi2any} sorts document indices according to the
+@dfn{Unicode Collation Algorithm} (defined in
+@uref{http://www.unicode.org/reports/tr10/, Unicode Technical Standard #10}),
+without language-specific collation tailoring.  If set, use the language
+for linguistic tailoring of index sorting.
 
-@item IGNORE_REF_TO_TOP_NODE_UP
-Ignore references to @code{TOP_NODE_UP}, the up node for the Top node.
+Currently, @command{texi2any} gives no warning if there is no support
+for linguistic tailoring due to either missing software or missing
+support for the specified language.
 
-@item INLINE_CSS_STYLE
-Put CSS directly in HTML elements rather than at the
-beginning of the output; default false.
+In Perl, the @code{Unicode::Collate::Locale} module is used for linguistic
+tailoring; therefore if this module is not installed, the variable will be
+silently ignored.
 
-@item JS_WEBLABELS
-@itemx JS_WEBLABELS_FILE
-Specify how to use a @dfn{JavaScript license web labels} page to
-give licensing information and source code for any JavaScript used
-in the HTML files for the manual.
-(See @uref{https://www.gnu.org/licenses/javascript-labels.html}).
+If @code{USE_UNICODE_COLLATION} is set to @samp{0}, there is no Unicode
+collation and so no linguistic tailoring either.
 
-With the value @samp{generate} (the default), generate a labels page
-at @code{JS_WEBLABELS_FILE}, and link to it in the HTML output files.
-Only do this if actually referencing JavaScript files (either with
-@code{HTML_MATH} set to @samp{mathjax}, or when using the experimental
-JS browsing interface when @code{INFO_JS_DIR} is set).  With this
-setting, @code{JS_WEBLABELS_FILE} must be a relative file name.
+See also the @code{DOCUMENTLANGUAGE_COLLATION} variable, described below.
 
-With the value @samp{reference}, link to the labels
-file given by @code{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.
+@item COMMAND_LINE_ENCODING
+Encoding used to decode command-line arguments.  Default is based on the locale
+encoding.  This may affect file names inserted into output files or error
+messages printed by the program.
 
-With @samp{omit}, neither generate nor link to a labels file.
+Note that some file and directory names from the command line may
+not be decoded immediately, and may not be decoded at all.
 
-@item MAX_HEADER_LEVEL
-Maximum header formatting level used (higher header
-formatting level numbers correspond to lower sectioning levels);
-default @samp{4}.
+@item CPP_LINE_DIRECTIVES
+Recognize @code{#line} directives in a ``preprocessing'' pass
+(@pxref{External Macro Processors}); on by default.
 
-@item MENU_ENTRY_COLON
-Symbol used between the menu entry and the description; default
-@samp{:}.
+@item DEBUG
+If set, debugging output is generated; default is off (zero).
+@c The integer value specifies what kinds of debugging output are
+@c generated.  It is a bitmask.  Setting it to 255 ensures having all
+@c available debugging output.
 
-@item MENU_SYMBOL
-Symbol used in front of menu entries when node names are used
-for menu entries formatting; default is undefined and set to
-@code{&bull;} if @code{USE_NUMERIC_ENTITY} is not set, and to
-@code{&#8217;} if set.
+@item DOC_ENCODING_FOR_INPUT_FILE_NAME
+If set, use the input Texinfo document encoding information for
+the encoding of input file names, such as file names specified as
+@code{@@include} or @code{@@verbatiminclude} arguments.  If unset, use
+the locale encoding instead.  Default is set, except on MS-Windows where
+the locale encoding is used by default.
 
-@item MONOLITHIC
-Output only one file including the table of contents.  Set
-by default, but only relevant when the output is not split.
+Note that this is for file names only; the default encoding or
+@code{@@documentencoding} is always used for the encoding of file
+content (@pxref{@code{@@documentencoding}}).
 
-@item NO_CSS
-Do not use CSS; default false.  @xref{HTML CSS}.
+The @code{INPUT_FILE_NAME_ENCODING} variable overrides this variable.
 
-@item NO_CUSTOM_HTML_ATTRIBUTE
-Do not output HTML with custom attributes in elements; default false.
+@item DOC_ENCODING_FOR_OUTPUT_FILE_NAME
+If set, use the input Texinfo document encoding information for the
+encoding of output file names, such as files specified with @option{--output}.
+If unset, use the locale encoding instead.  Default is unset, so files
+names are encoded using the current locale.
 
-@item NO_NUMBER_FOOTNOTE_SYMBOL
-Symbol used for footnotes if @code{NUMBER_FOOTNOTES} is false.
-Default is @code{*}.
+Note that this is for file names only; @code{OUTPUT_ENCODING_NAME}
+is used for the encoding of file content.
 
-@item NODE_NAME_IN_INDEX
-If true, use node names in index entries, otherwise prefer section names.
-If undefined, use @code{USE_NODES} value in HTML.  Default is undefined.
+The @code{OUTPUT_FILE_NAME_ENCODING} variable overrides this variable.
 
-@item PRE_BODY_CLOSE
-If set, the given text will appear at the footer of each
-HTML file; default unset.
+@vindex SystemLiteral
+@item DOCTYPE
+For DocBook, HTML, XML@.  Specifies the @code{SystemLiteral}, the
+entity's system identifier.  This is a URI which may be used to
+retrieve the entity, and identifies the canonical DTD for the
+document.  The default value is different for each of HTML, DocBook
+and XML.
 
-@item 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.
+@item DOCUMENTLANGUAGE_COLLATION
+If set, try to use the language specified in a @code{@@documentlanguage}
+directive for language-specific tailoring of index sorting.
+See also the @code{COLLATION_LANGUAGE} variable, described above.
+(@xref{@code{@@documentlanguage}}.)
 
-@item PROGRAM_NAME_IN_FOOTER
-If set, output the program name and miscellaneous related
-information in the page footers; default false.
+@item DUMP_TEXI
+For debugging.  If set, no conversion is done, only parsing and macro
+expansion.  If the option @option{--macro-expand} is set, the Texinfo
+source is also expanded to the corresponding file.  Default false.
 
-@item SECTION_NAME_IN_TITLE
-If set,  when output is split, use the argument of the chapter
-structuring command (e.g., @code{@@chapter} or @code{@@section})
-in the @code{<title>} instead of the argument to @code{@@node}.
+@item DUMP_TREE
+For debugging.  If set, the tree constructed upon parsing a Texinfo
+document is output to standard error; default false.
 
-@item 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.
+@item EPUB_CREATE_CONTAINER_FILE
+If set to 0, do not generate the EPUB output file.  Default is set
+to 1.
 
-@item SHOW_BUILTIN_CSS_RULES
-Output the built-in default CSS rules on the standard output and exit.
+@item 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 @code{TEST} or
+@code{DEBUG} is set. @xref{EPUB Output File and Directory}.
 
-@item SHOW_TITLE
-If set, output the title at the beginning of the document;
-default @samp{undef}.  If set to @samp{undef}, setting
-@code{NO_TOP_NODE_OUTPUT} also sets @code{SHOW_TITLE} for HTML.
+@item EXTENSION
+The extension added to the output file name.  The default is different
+for each output format.
 
-@item TOC_LINKS
-If set, links from headings to toc entries are created;
-default false.
+@item FORMAT_MENU
+If set to @samp{menu}, output Texinfo menus.  This is the default for
+Info.  @samp{sectiontoc} is the default setting for HTML, where instead
+of the contents of @code{@@menu} blocks being output, a list of subordinate
+sections is output in each node.  If set to @samp{nomenu}, do not output
+menus.
 
-@item 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@.
+This variable is set to @samp{nomenu} when generating DocBook, or when
+@option{--no-headers} is specified.
 
-@item TOP_NODE_FILE_TARGET
-File name used for the Top node in cross-references;
-default is @code{index.html}.
+@c document?
+@ignore
+@item HANDLER_FATAL_ERROR_LEVEL
+This variable sets the error level above which errors returned by
+user defined functions registered to be called at different stages
+are considered to be fatal errors.  You should not need to change this
+value.  Default 100.
+@end ignore
 
-@item TOP_NODE_UP_URL
-A URL used for Top node up references; the default is
-@code{undef}, in that case no Top node Up reference is generated.
-For more about the Top node pointers, @pxref{First Node}.  For 
-overriding the Up pointer name in case @code{TOP_NODE_UP_URL} is set
-and for other formats, see @code{TOP_NODE_UP} in 
-@ref{Other Customization Variables}.
+@item HIGHLIGHT_SYNTAX
+If set, @code{@@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 @code{HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE}.  Syntax
+highlighting requires an external program to generate the highlighted HTML.
+The @code{HIGHLIGHT_SYNTAX} value allows to select a specific program.  The
+possibilities are @code{highlight}, @code{pygments}, any other value standing
+for @code{source-highlight} (@pxref{Syntax Highlighting}).
 
-@cindex @code{accesskey} @subentry customization variable for
-@item USE_ACCESSKEY
-Use @code{accesskey} in cross-references; default true.
+@item HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE
+The default language used for syntax highlighting when there is no
+language information.
 
-@item USE_ISO
-Use entities for doubled single-quote characters
-(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
-(@pxref{Conventions}); default true.
+@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
+If set, spaces are ignored after an @@-command that takes braces.
+Default true, matching the @TeX{} behavior.
 
-@cindex @code{<link>} HTML tag, in @code{<head>}
-@cindex @code{<head>} HTML tag, and @code{<link>}
-@item USE_LINKS
-Generate @code{<link>} elements in the HTML @code{<head>}
-output; default true.
+@item INDEX_SPECIAL_CHARS_WARNING
+If set, warn about @samp{:} in index entry, as not all Info readers may
+be able to process these.  For Info and plaintext only.  Default false,
+because parsing problems there don't prevent navigation; readers can still
+relatively easily find their way to the node in question.
 
-@item USE_NEXT_HEADING_FOR_LONE_NODE
-If set, a node not associated to a sectioning command but
-followed by a heading command not usually associated to node
-such as @code{@@heading} before other formatted contents
-do not have its name output as a heading, under the assumption
-that the command found provides the heading.  Default true.
+@item INFO_SPECIAL_CHARS_QUOTE
+If set, whenever there are problematic characters for Info output in
+places such as node names or menu items, surround the part of the
+construct where they appear with quoting characters, as described in
+@ref{Info Format Specification}.  Default is set for Info and unset
+for plaintext.  @xref{Node Line Requirements}.
 
-@item 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
-@code{USE_NODES} value.  Default is undefined.  Note that this setting does not
-determine the link string only where the links points to, see @ref{Three
-Arguments, , xrefautomaticsectiontitle} for the link string customization.  If
-nodes and sections are systematically associated, this customization has no
-practical effect.
+@item INFO_SPECIAL_CHARS_WARNING
+If set, warn about problematic constructs for Info output (such as the
+string @samp{::}) in node names, menu items, and cross-references.
+If not defined, set unless @code{INFO_SPECIAL_CHARS_QUOTE} is set.
+Default is set for Info and not defined for plaintext. Similar warnings in
+index entries are covered by @code{INDEX_SPECIAL_CHARS_WARNING}.
 
-@item USE_REL_REV
-Use @code{rel} in cross-references; default true.
+@cindex Encoding @subentry input file names
+@item INPUT_FILE_NAME_ENCODING
+Encoding used for input file names.  This variable overrides
+any encoding from the document or current locale.  Normally, you do
+not need to set this variable, but it can be used if file names are
+in a certain character encoding on a filesystem.  An alternative is to
+set @code{DOC_ENCODING_FOR_INPUT_FILE_NAME} to @samp{0} to use the locale
+encoding.  See also @code{OUTPUT_FILE_NAME_ENCODING}.
 
-@item USE_TITLEPAGE_FOR_TITLE
-Use the full @code{@@titlepage} as the title, not a simple title string;
-default true.  Only relevant if @code{SHOW_TITLE} is set.
+@item LOCALE_ENCODING
+Locale encoding obtained from the system.  You should not need to
+explicitly set this variable.
 
-@item USE_XML_SYNTAX
-Use XML/XHTML compatible syntax.
+@item MAX_MACRO_CALL_NESTING
+The maximal number of recursive calls of @@-commands defined through
+@code{@@rmacro}; default 100000.  The purpose of this variable is to
+avoid infinite recursions.
 
-@item VERTICAL_HEAD_NAVIGATION
-If set, a vertical navigation panel is used; default false.
+@item MESSAGE_ENCODING
+Encoding used to encode messages output by @command{texi2any}.  Default is
+based on the locale encoding.
 
-@cindex Navigation panel, bottom of page
-@cindex Navigation footer
-@item 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.
+It is also used for command-line argument passed to commands called from
+@command{texi2any}.  For example, @command{latex2html} will be called from
+@command{texi2any} if @code{HTML_MATH} is set to @samp{l2h}.
 
-@item 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
-(@pxref{@code{@@float}}).  The default is off.
+@item NO_TOP_NODE_OUTPUT
+@anchor{@code{NO_TOP_NODE_OUTPUT}}
+If set do not output the Top node content.  The Top node is still
+parsed, but the content is discarded.  Not set in the default case
+for HTML@.  Set in the default case for EPUB@.  If @code{SHOW_TITLE}
+is @samp{undef}, setting @code{NO_TOP_NODE_OUTPUT} also sets
+@code{SHOW_TITLE} for HTML.
 
-@item XREF_USE_NODE_NAME_ARG
-Only relevant for cross-reference commands with no cross
-reference name (second argument).  If set to@tie{}1, use the node name
-(first) argument in cross-reference @@-commands for the text displayed
-as the hyperlink.  If set to@tie{}0, use the node name if
-@code{USE_NODES} is set, otherwise the section name.  If set to
-@samp{undef}, use the first argument in preformatted environments,
-otherwise use the node name or section name depending on
-@code{USE_NODES}.  The default is @samp{undef}.
+Setting @code{NO_TOP_NODE_OUTPUT}, which removes the Top node and adds
+a title page corresponds more to the formatting of a book.  Setting
+@code{NO_TOP_NODE_OUTPUT} to false, with @code{SHOW_TITLE} remaining
+@samp{undef}, and false, corresponds more to a document setup for browsing,
+with a direct access to the information at the Top node.
 
-@end vtable
+For DocBook, @code{NO_TOP_NODE_OUTPUT} is set to true.  Setting
+@code{NO_TOP_NODE_OUTPUT} to false causes the Top node content to be
+output.  It is not recommended to output the Top node in DocBook as
+the title and copying informations are always output.  This option
+is kept for DocBook for compatibility, as before 2022 the Top node was output
+in DocBook.  It could be removed in the future.
 
+@item NO_USE_SETFILENAME
+If set, do not use @code{@@setfilename} to set the document name;
+instead, base the output document name only on the input file name.
+The default is false.
 
-@node MathJax Customization Variables
-@subsection MathJax Customization Variables
+@item NODE_NAME_IN_MENU
+If set, use node names in menu entries, otherwise prefer section names;
+default true.
 
-This table lists the customization variables which can be used when 
-MathJax is being used, which will be the case when @code{HTML_MATH}
-is set to @samp{mathjax}.
+@item OPEN_QUOTE_SYMBOL
+When an opening quote is needed, e.g., for @samp{@@samp} output, use
+the specified character; default @code{&#8216;} for DocBook.
+Undefined in the default case in HTML and set to @code{&lsquo;}
+if @code{USE_NUMERIC_ENTITY} is not set, to @code{&#8217;} if set, and
+to a quote character if @code{OUTPUT_CHARACTERS} is set and the output
+encoding includes that character.
 
-@vtable @code
-@item MATHJAX_SCRIPT
-URL of the MathJax component file (e.g.@: @file{tex-svg.js}) you are using.
-@command{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.
+For Info, the default depends on the enabled document encoding.  If
+@option{--disable-encoding} is set or the document encoding is not UTF-8,
+@samp{'} is used.  This character usually appears
+as an undirected single quote on modern systems.  Otherwise, the Info
+output uses a Unicode left quote.
 
-@item 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 @code{MATHJAX_SCRIPT}.  `Preferred form for modification'
-means that this should not be in a `minified' form.  Used in the
-license labels page (@pxref{HTML Customization Variables List}, under
-@code{JS_WEBLABELS}).
+@item OPEN_DOUBLE_QUOTE_SYMBOL
+When an opening double quote is needed, for @samp{@@dfn} output in Info, use
+the specified character.  If @option{--disable-encoding} is set or the document
+encoding is not UTF-8, @samp{"} is used.  Otherwise, the Info output uses a
+Unicode left double quote.
 
-Again, @command{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.
-@end vtable
+@item OUTPUT_CHARACTERS
+If not set, the default, output accented and special characters in HTML, XML
+and DocBook using XML entities, and in @LaTeX{} using macros.  If set, output
+accented characters in HTML, XML, DocBook and @LaTeX{} output and special
+characters in HTML and @LaTeX{} output based on the document encoding.
+@xref{@code{@@documentencoding}}, and @ref{Inserting Accents}.
 
+@item OUTPUT_ENCODING_NAME
+Normalized encoding name used for output files.  Should be a usable
+charset name in HTML, typically one of the preferred IANA encoding
+names.  By default, if an input encoding is set (typically through
+@code{@@documentencoding}), this information is used to set the output 
+encoding name, otherwise the output encoding is based on the
+default encoding.  @xref{@code{@@documentencoding}}.
 
-@node @command{latex2html} Customization Variables
-@subsection @command{latex2html} Customization Variables
+@cindex Encoding @subentry output file names
+@item OUTPUT_FILE_NAME_ENCODING
+Encoding used for output file names.  This variable overrides
+any encoding from the document or current locale.
 
-This table lists the customization variables which can be used when 
-@command{latex2html} is being used to convert @code{@@math},
-@code{@@displaymath}, @code{@@latex} and @code{@@tex} sections for HTML@.
-These customization variables are relevant only if @code{HTML_MATH} is set to
-@samp{l2h}.
+Normally, you do not need to set this variable, but it can be used if file
+names should be created in a certain character encoding on a filesystem.
+See also @code{INPUT_FILE_NAME_ENCODING}.
 
-To actually convert @code{@@tex} sections, @option{--iftex} should be used,
-and to actually convert @code{@@latex} sections, @option{--iflatex} should be
-used.
+@item PACKAGE
+@itemx PACKAGE_VERSION
+@itemx PACKAGE_AND_VERSION
+@itemx PACKAGE_URL
+@itemx PACKAGE_NAME
+The implementation's short package name, package version, package name
+and version concatenated, package URL@:, and full package name,
+respectively.  By default, these variables are all set through
+Autoconf, Automake, and @code{configure}.
 
-@vtable @code
-@item L2H_CLEAN
-If set, the intermediate files generated in relation with @command{latex2html}
-are removed; default true.
+@item PREFIX
+The output file prefix, which is prepended to some output file names.
+By default it is set by @code{@@setfilename} or from the input file
+(@pxref{Setting the Output File Name}).  How this value is used depends on the
+value of other customization variables or command line options, such
+as whether the output is split.  The default is unset.
 
-@item L2H_FILE
-If set, the given file is used as @command{latex2html}'s init file; default
-unset.
+@item PROGRAM
+Name of the program used.  By default, it is set to the name of the
+program launched, with a trailing @samp{.pl} removed.
 
-@item L2H_HTML_VERSION
-The HTML version used in the @command{latex2html} call; default unset.
+@pindex texi-elements-by-size
+@cindex Longest nodes, finding
+@cindex Sorting nodes by size
+@item SORT_ELEMENT_COUNT
+If set, the name of a file to which a list of elements (nodes or
+sections, depending on the output format) is dumped, sorted by the
+number of lines they contain after removal of @@-commands; default
+unset.  This is used by the program @code{texi-elements-by-size} in
+the @file{util/} directory of the Texinfo source distribution
+(@pxref{texi-elements-by-size}).
 
-@item L2H_L2H
-The program invoked as @command{latex2html}; default is @code{latex2html}.
+@item SORT_ELEMENT_COUNT_WORDS
+When dumping the elements-by-size file (see preceding item), use word
+counts instead of line counts; default false.
 
-@item L2H_SKIP
-If set to a true value, the actual call to @command{latex2html} is skipped;
-previously generated content is reused instead.  If set to 0, the cache is not
-used at all.  If set to @samp{undef}, the cache is used for as many @TeX{}
-fragments as possible and for any remaining the command is run.  The default is
-@samp{undef}.
+@item TEST
+If set to true, some variables which are normally dynamically
+generated anew for each run (date, program name, version) are set to
+fixed and given values.  This is useful to compare the output to a
+reference file, as is done for the tests.  The default is false.
 
-@item L2H_TMP
-Set the directory used for temporary files.  None of the file name components
-in this directory name may start with @samp{.}; otherwise, @command{latex2html}
-will fail (because of @command{dvips}).  The default is the empty string, which
-means the current directory.
-@end vtable
+@item TEXI2DVI
+Name of the command used to produce PostScript, PDF, and DVI; default
+@samp{texi2dvi}.  @xref{@command{texi2any} Printed Output}.
 
+@cindex compatibility, with @command{texi2html}
+@item TEXI2HTML
+Generate HTML and try to be as compatible as possible with
+@command{texi2html}; default false.
 
-@node @command{tex4ht} Customization Variables
-@subsection @command{tex4ht} Customization Variables
+@item TEXINFO_DTD_VERSION
+For XML@.  Version of the DTD used in the XML output preamble.  The
+default is set based on a variable in @file{configure.ac}.
 
-This table lists the customization variables which can be used when
-@command{tex4ht} is being used to convert @code{@@math}, @code{@@displaymath},
-@code{@@tex} and @code{@@latex} sections for HTML@.  These customization
-variables are relevant only if @code{HTML_MATH} is set to @samp{t4h}.
+@item TEXTCONTENT_COMMENT
+For stripped text content output (i.e., when
+@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}).  If set,
+also output comments.  Default false.
 
-To actually convert @code{@@tex} sections, @option{--iftex} should be used,
-and to actually convert @code{@@latex} sections, @option{--iflatex} should be
-used.
+@item TOP_NODE_UP
+Up node for the Top node; default @samp{(dir)}.  This node name is 
+supposed to be already formatted for the output format.  In HTML
+can be used in attribute, so should not contain any element.  Used for
+HTML output only if @code{TOP_NODE_UP_URL} is set to override the URL@:,
+see @code{TOP_NODE_UP_URL} in @ref{HTML Customization Variables List}.  
 
-@vtable @code
-@item T4H_LATEX_CONVERSION
-If set, the conversion type used for @code{@@latex} sections.  Possibilities
-are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{latex} if not
-defined.
+@item TREE_TRANSFORMATIONS
+The associated value is a comma separated list of transformations that
+can be applied to the Texinfo tree prior to outputting the result.  If
+more than one is specified, the ordering is irrelevant; each is always
+applied at the necessary point during processing.
 
-@item T4H_MATH_CONVERSION
-If set, the conversion type used for @code{@@math} and @code{@@displymath}.
-Possibilities are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{tex}
-if not defined.
+By default, the tree transformations @samp{move_index_entries_after_items}
+and @samp{relate_index_entries_to_table_entries} are executed
+for HTML and DocBook output.
+Here's an example of updating the master menu in a document:
 
-@item T4H_TEX_CONVERSION
-If set, the conversion type used for @code{@@tex} sections.  Possibilities
-are @samp{latex}, @samp{tex} and @samp{texi}.  Set to @samp{tex} if not
-defined.
-@end vtable
+@example
+texi2any \
+  -c TREE_TRANSFORMATIONS=regenerate_master_menu \
+  -c TEXINFO_OUTPUT_FORMAT=plaintexinfo \
+  mydoc.texi \
+  -o /tmp/out
+@end example
 
+@noindent (Caveat: Since @samp{plaintexinfo} output expands
+Texinfo macros and conditionals, it's necessary to remove any such
+differences before installing the updates in the original document.
+This may be remedied in a future release.)
 
-@node @LaTeX{} Customization Variables
-@subsection @LaTeX{} Customization Variables
+The following transformations are currently supported (many are used
+in the @code{pod2texi} utility distributed with Texinfo;
+@pxref{Invoking @command{pod2texi}}):
 
-@cartouche
-@quotation warning
-@LaTeX{} output customization is experimental.  Nothing is decided,
-everything can change, and we would welcome any feedback.
-@end quotation
-@end cartouche
+@ftable @samp
+@item complete_tree_nodes_menus
+Add menu entries or whole menus for nodes associated with sections of
+any level, based on the sectioning tree.
 
-This table gives the customization variables which apply to @LaTeX{} output
-only.
+@item complete_tree_nodes_missing_menu
+Add whole menus for nodes associated with sections without menu.  The
+menus are based on the sectioning tree.
 
-@vtable @code
-@item CLASS_BEGIN_USEPACKAGE
-If set, the corresponding text will replace the @LaTeX{} @code{\documentclass},
-package imports that are always output and are output right after
-@code{\documentclass}, and package imports that depend on the document encoding
-setting the input and font encoding (@code{inputenc} and @code{fontenc}).
+@item fill_gaps_in_sectioning
+Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in
+sectioning.  For example, an @code{@@unnumberedsec} will be inserted
+if a @code{@@chapter} is followed by a @code{@@subsection}.
 
-The text replaced is along:
-@example LaTeX
-\documentclass@{book@}
-\usepackage@{amsfonts@}
-\usepackage@{amsmath@}
-\usepackage[gen]@{eurosym@}
-\usepackage@{textcomp@}
-\usepackage@{graphicx@}
-\usepackage@{etoolbox@}
-\usepackage@{titleps@}
-\usepackage[utf8]@{inputenc@}
-\usepackage[T1]@{fontenc@}
-@end example
+@item insert_nodes_for_sectioning_commands
+Insert nodes for sectioning commands lacking a corresponding node.
+
+@item move_index_entries_after_items
+In @code{@@enumerate} and @code{@@itemize}, move index entries
+appearing just before an @code{@@item} to just after the
+@code{@@item}.  Comment lines between index entries are moved too.  As
+mentioned, this is always done for HTML and DocBook output.
 
-@item END_USEPACKAGE
-If set, the corresponding text will replace the package imports that depend
-on the Texinfo commands used, and the last packages imports that are always
-output and output after all the other packages imports.  The last package
-imports corresponds to @samp{\usepackage[hidelinks]@{hyperref@}}.
+@item regenerate_master_menu
+Update the Top node master menu, either replacing the (first)
+@code{@@detailmenu} in the Top node menu, or creating it at the end of
+the Top node menu.
 
-Here is an example of the corresponding text for a document with indices,
-@code{@@need}, @code{@@multitable}, definition commands, @code{@@cartouche},
-lists, and @code{@@float}:
-@example LaTeX
-\usepackage@{imakeidx@}
-\usepackage@{needspace@}
-\usepackage@{array@}
-\usepackage@{embrac@}
-\usepackage@{expl3@}
-\usepackage@{tabularx@}
-\usepackage[framemethod=tikz]@{mdframed@}
-\usepackage@{enumitem@}
-\usepackage@{float@}
-\usepackage[hidelinks]@{hyperref@}
-@end example
-@end vtable
+@item relate_index_entries_to_table_entries
+In @code{@@table}, @code{@@vtable} and @code{@@ftable},
+reassociate the index entry information from an index @@-command
+appearing right after an @code{@@item} line with the first element of
+the @code{@@item}.  Remove the index @@-command from the tree.
 
+@end ftable
 
-@node Other Customization Variables
-@subsection Other Customization Variables
+@item USE_NODES
+Preferentially use nodes to decide where elements are separated.  If
+set to false, preferentially use sectioning to decide where elements
+are separated.  The default is true.
 
-This table gives the remaining customization variables, which apply to
-multiple formats, or affect global behavior, or otherwise don't fit
-into the categories of the previous sections.
+@item USE_NUMERIC_ENTITY
+For HTML, XML and DocBook@.  If set, use numeric entities instead of named
+entities.  By default, set to true for DocBook output.
 
-@vtable @code
-@item ASCII_DASHES_AND_QUOTES
-For Info output, when set, use plain ASCII characters to represent
-quotation marks, hyphens and dashes when these are given in the Texinfo
-source as @samp{-}, @samp{--}, @samp{---}, @samp{`}, @samp{``},
-@samp{'}, and @samp{''}, rather than UTF-8 directional quotation marks,
-en dashes, vel sim.  On by default.
+@item USE_UP_NODE_FOR_ELEMENT_UP
+Fill in up sectioning direction with node direction when there is no
+sectioning up direction.  In practice this can only happen when there
+is no @@top section.  Not set by default.
 
-@item ASCII_GLYPH
-For Info output, use ASCII output for glyph commands such as the copyright
-sign (@command{@@copyright@{@}}, becoming @samp{(C)}),
-and the bullet symbol (@command{@@bullet@{@}}, becoming @samp{*}), rather
-than other Unicode sequences.  Off by default.
+@item USE_SETFILENAME_EXTENSION
+Default is on for Info, off for other output.  If set, use exactly
+what @code{@@setfilename} gives for the output file name, including
+the extension.  You should not need to explicitly set this variable.
 
-@item ASCII_PUNCTUATION
-Avoid any unncessary or gratuitious non-ASCII, UTF-8 sequences in the
-output.  Implies both @code{ASCII_DASHES_AND_QUOTES} and @code{ASCII_GLYPH}
-and additionally affects the output of commands such as @code{@@samp} which
-output quotation marks.
+@pindex Unicode::Collate
+@item USE_UNICODE_COLLATION
+By default, @command{texi2any} sorts document indices according to
+the @dfn{Unicode Collation Algorithm} (defined in
+@uref{http://www.unicode.org/reports/tr10/, Unicode Technical Standard #10}),
+which performs a @dfn{multi-level} ordering of strings containing Unicode
+code points.  (To do this, the program uses the @code{Unicode::Collate}
+module, a standard part of Perl installations.)  However, the use of
+this algorithm incurs noticeably longer run times when processing manuals
+with large indices.
 
-@item AUTO_MENU_DESCRIPTION_ALIGN_COLUMN
-For Info output, column at which to start a menu entry description
-provided by @code{@@nodedescription} or @code{@@nodedescriptionblock}.
-Undefined by default, in which case 45% of the fill column value is used
-(@pxref{Invoking @command{texi2any}}).
+Set this variable to @samp{0} to use a simpler, faster sorting algorithm.
+@c which only uses Perl's built-in string comparison or strcmp in C
 
-@item AUTO_MENU_MAX_WIDTH
-Maximum number of columns in a menu entry line in Info when adding a
-description from @code{@@nodedescription} or @code{@@nodedescriptionblock}.
-Undefined by default, in which case 10% more than the fill column value
-is used (@pxref{Invoking @command{texi2any}}).
+You may find this useful for speeding up @command{texi2any} if you don't
+have many non-ASCII characters in index entry text, or if you don't care
+about having the indices sorted correctly, especially when working on
+the draft of a manual.
 
-@item CHECK_MISSING_MENU_ENTRY
-When a @code{@@menu} block occurs in a node, check if there is a menu
-entry for all subordinate nodes in the document sectioning structure.  On
-by default.
 
-@item CHECK_NORMAL_MENU_STRUCTURE
-Warn if the node pointers (either explicitly or automatically set)
-are not consistent with the order of node menu entries.  This is a more
-thorough structure check than that provided by
-@code{CHECK_MISSING_MENU_ENTRY}.  Off by default.
+@pindex Text::Unidecode
+@item USE_UNIDECODE
+If set to false, do not use the @code{Text::Unidecode} Perl module to
+transliterate more characters; default true.
 
-@item CLOSE_QUOTE_SYMBOL
-When a closing quote is needed, e.g. for @code{@@samp} output, use
-this character; default @code{&#8217;} in DocBook.
-Undefined in the default case in HTML and set to @code{&rsquo;}
-if @code{USE_NUMERIC_ENTITY} is not set, to @code{&#8217;} if set, and
-to a quote character if @code{OUTPUT_CHARACTERS} is set and the output
-encoding includes that character.
+@end vtable
 
-The default for Info is set the same as for @code{OPEN_QUOTE_SYMBOL},
-except that the Unicode code is a closing quote (see below).
 
-@item CLOSE_DOUBLE_QUOTE_SYMBOL
-When a closing double quote is needed, for @samp{@@dfn} in Info, use this
-character.  The default for Info is set the same as for
-@code{OPEN_DOUBLE_QUOTE_SYMBOL}, except that the Unicode code is a closing
-double quote (see below).
+@node Internationalization of Document Strings
+@nodedescription Translating program-inserted text.
+@section Internationalization of Document Strings
 
-@item COLLATION_LANGUAGE
-By default, @command{texi2any} sorts document indices according to the
-@dfn{Unicode Collation Algorithm} (defined in
-@uref{http://www.unicode.org/reports/tr10/, Unicode Technical Standard #10}),
-without language-specific collation tailoring.  If set, use the language
-for linguistic tailoring of index sorting.
+@cindex I18n, of document strings
+@cindex Internationalization of document strings
+@cindex Document strings, internationalization of
+@cindex Output document strings, internationalization of
+@cindex Translating strings in output documents
 
-Currently, @command{texi2any} gives no warning if there is no support
-for linguistic tailoring due to either missing software or missing
-support for the specified language.
+@vindex documentlanguage @r{customization variable}
+@command{texi2any} writes fixed strings into the output document at
+various places: cross-references, page footers, the help page,
+alternate text for images, and so on.  The string chosen depends on
+the value of the @code{documentlanguage} at the time of the string
+being output (@pxref{@code{@@documentlanguage}}, for the Texinfo
+command interface).
 
-In Perl, the @code{Unicode::Collate::Locale} module is used for linguistic
-tailoring; therefore if this module is not installed, the variable will be
-silently ignored.
+@pindex libintl-perl @r{Gettext implementation}
+The Gettext framework is used for those strings (@pxref{Top,,,
+gettext, Gettext}).  The @code{libintl-perl} package is used as the
+@code{gettext} implementation; more specifically, the pure Perl
+implementation is used, so Texinfo can support consistent behavior
+across all platforms and installations, which would not otherwise be
+possible.  @code{libintl-perl} is included in the Texinfo distribution
+and always installed, to ensure that it is available if needed.  It is
+also possible to use the system @code{gettext} (the choice can be made
+at build-time).
 
-If @code{USE_UNICODE_COLLATION} is set to @samp{0}, there is no Unicode
-collation and so no linguistic tailoring either.
+@vindex texinfo_document @r{Gettext domain}
+@cindex Perl format strings for translation
+The Gettext domain @samp{texinfo_document} is used for the strings.
+Translated strings are written as Texinfo, and may include
+@@-commands.  In translated strings, the varying parts of the string
+are not usually denoted by @code{%s} and the like, but by
+@samp{@{arg_name@}}.  (This convention is common for @code{gettext} in
+Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
+Format Strings, gettext, GNU Gettext}.)  For example, in the
+following, @samp{@{section@}} will be replaced by the section name:
 
-See also the @code{DOCUMENTLANGUAGE_COLLATION} variable, described below.
+@example
+see @{section@}
+@end example
 
-@item COMMAND_LINE_ENCODING
-Encoding used to decode command-line arguments.  Default is based on the locale
-encoding.  This may affect file names inserted into output files or error
-messages printed by the program.
+These Perl-style brace format strings are used for two reasons: first,
+changing the order of @code{printf} arguments is only available since
+Perl@tie{}5.8.0; second, and more importantly, the order of arguments
+is unpredictable, since @@-command expansion may lead to different
+orders depending on the output format.
 
-Note that some file and directory names from the command line may
-not be decoded immediately, and may not be decoded at all.
+The expansion of a translation string is done like this:
 
-@item CPP_LINE_DIRECTIVES
-Recognize @code{#line} directives in a ``preprocessing'' pass
-(@pxref{External Macro Processors}); on by default.
+@enumerate
+@item First, the string is translated.  The locale
+is @var{documentlanguage}@code{.}@var{documentencoding}.
 
-@item DEBUG
-If set, debugging output is generated; default is off (zero).
-@c The integer value specifies what kinds of debugging output are
-@c generated.  It is a bitmask.  Setting it to 255 ensures having all
-@c available debugging output.
+If the @var{documentlanguage} has the form @samp{ll_CC}, that is
+tried first, and then just @samp{ll}.
 
-@item DOC_ENCODING_FOR_INPUT_FILE_NAME
-If set, use the input Texinfo document encoding information for
-the encoding of input file names, such as file names specified as
-@code{@@include} or @code{@@verbatiminclude} arguments.  If unset, use
-the locale encoding instead.  Default is set, except on MS-Windows where
-the locale encoding is used by default.
+@item Next, in most cases, the string is expanded as Texinfo, and converted.
+The arguments are substituted; for example, @samp{@{arg_name@}} is replaced by
+the corresponding actual argument.
 
-Note that this is for file names only; the default encoding or
-@code{@@documentencoding} is always used for the encoding of file
-content (@pxref{@code{@@documentencoding}}).
+It is also possible for the string and the argument to be already converted.
+In that case, the arguments are simply substituted.  Similarly,
+@samp{@{arg_name@}} is replaced by the corresponding actual argument.
 
-The @code{INPUT_FILE_NAME_ENCODING} variable overrides this variable.
+@end enumerate
 
-@item DOC_ENCODING_FOR_OUTPUT_FILE_NAME
-If set, use the input Texinfo document encoding information for the
-encoding of output file names, such as files specified with @option{--output}.
-If unset, use the locale encoding instead.  Default is unset, so files
-names are encoded using the current locale.
+In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
+and @samp{@{program@}} are the arguments of the string.  Since they
+are used in @code{@@uref}, their order is not predictable.
+@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are
+substituted after the expansion:
 
-Note that this is for file names only; @code{OUTPUT_ENCODING_NAME}
-is used for the encoding of file content.
+@example
+Generated on @@emph@{@{date@}@} using
+@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.
+@end example
 
-The @code{OUTPUT_FILE_NAME_ENCODING} variable overrides this variable.
+This approach is admittedly a bit complicated.  Its usefulness is that
+it supports having translations available in different encodings for
+encodings which can be covered by @@-commands, and also specifying how
+the formatting for some commands is done, independently of the output
+format---yet still be language-dependent.  For example, the
+@samp{@@pxref} translation string can be like this:
 
-@vindex SystemLiteral
-@item DOCTYPE
-For DocBook, HTML, XML@.  Specifies the @code{SystemLiteral}, the
-entity's system identifier.  This is a URI which may be used to
-retrieve the entity, and identifies the canonical DTD for the
-document.  The default value is different for each of HTML, DocBook
-and XML.
+@example
+see @{node_file_href@} section `@{section@}' in @@cite@{@{book@}@}
+@end example
+
+@noindent
+which allows for specifying a string independently of the output
+format, while nevertheless with rich formatting it may be translated
+appropriately in many languages.
 
-@item DOCUMENTLANGUAGE_COLLATION
-If set, try to use the language specified in a @code{@@documentlanguage}
-directive for language-specific tailoring of index sorting.
-See also the @code{COLLATION_LANGUAGE} variable, described above.
-(@xref{@code{@@documentlanguage}}.)
 
-@item DUMP_TEXI
-For debugging.  If set, no conversion is done, only parsing and macro
-expansion.  If the option @option{--macro-expand} is set, the Texinfo
-source is also expanded to the corresponding file.  Default false.
+@node Invoking @command{pod2texi}
+@nodedescription Translating Perl Pod to Texinfo.
+@section Invoking @command{pod2texi}: Convert Pod to Texinfo
 
-@item DUMP_TREE
-For debugging.  If set, the tree constructed upon parsing a Texinfo
-document is output to standard error; default false.
+@pindex pod2texi
+@cindex Invoking @command{pod2texi}
+@cindex Pod, converting to Texinfo
+@cindex Perl Pod, converting to Texinfo
 
-@item EPUB_CREATE_CONTAINER_FILE
-If set to 0, do not generate the EPUB output file.  Default is set
-to 1.
+The @command{pod2texi} program translates Perl Pod documentation file(s)
+to Texinfo.  There are two basic modes of operation: generating a
+standalone manual from each input Pod, or (if @code{--base-level=1} or
+higher is given) generating Texinfo subfiles suitable for use
+with @code{@@include}.
 
-@item 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 @code{TEST} or
-@code{DEBUG} is set. @xref{EPUB Output File and Directory}.
+@c Although ordinarily this documentation in the Texinfo manual would be
+@c the best place to look, in this case we have documented all the
+@c options and examples in the @command{pod2texi} program itself, since it
+@c may be useful outside of the rest of Texinfo.  Thus, please see the
+@c output of @code{pod2texi --help}, the version on the web at
+@c @url{https://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc.
 
-@item EXTENSION
-The extension added to the output file name.  The default is different
-for each output format.
+The @command{pod2texi} program may be useful outside of the rest of Texinfo;
+thus, the invocation of @command{pod2texi} is documented in the Pod language
+using the man page format to follow the convention used in Perl standalone
+programs, with a version on the web
+@url{https://www.gnu.org/software/texinfo/manual/pod2texi.html} and a version
+included below.  The version included in the manual is also an example of
+@command{pod2texi} use, as it is converted from Pod using @command{pod2texi}.
 
-@item FORMAT_MENU
-If set to @samp{menu}, output Texinfo menus.  This is the default for
-Info.  @samp{sectiontoc} is the default setting for HTML, where instead
-of the contents of @code{@@menu} blocks being output, a list of subordinate
-sections is output in each node.  If set to @samp{nomenu}, do not output
-menus.
+@c there are issue with the perldoc-all generated files, as the perl 
documentation
+@c does not follows the Pod specification, there are anchors added
+@c using the first word in addition to the regular anchors.
+@c For an example of using @command{pod2texi} to make Texinfo out of the
+@c Perl documentation itself, see @file{contrib/perldoc-all}} in the Texinfo
+@c source distribution.
 
-This variable is set to @samp{nomenu} when generating DocBook, or when
-@option{--no-headers} is specified.
 
-@c document?
-@ignore
-@item HANDLER_FATAL_ERROR_LEVEL
-This variable sets the error level above which errors returned by
-user defined functions registered to be called at different stages
-are considered to be fatal errors.  You should not need to change this
-value.  Default 100.
-@end ignore
+@node pod2texi manual page
+@nodedescription @command{pod2texi} invocation in a manual page format.
+@include pod2texi.texi
 
-@item HIGHLIGHT_SYNTAX
-If set, @code{@@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 @code{HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE}.  Syntax
-highlighting requires an external program to generate the highlighted HTML.
-The @code{HIGHLIGHT_SYNTAX} value allows to select a specific program.  The
-possibilities are @code{highlight}, @code{pygments}, any other value standing
-for @code{source-highlight} (@pxref{Syntax Highlighting}).
 
-@item HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE
-The default language used for syntax highlighting when there is no
-language information.
+@node @command{texi2html}
+@nodedescription An ancestor of @command{texi2any}.
+@section @command{texi2html}: Ancestor of @command{texi2any}
 
-@item IGNORE_SPACE_AFTER_BRACED_COMMAND_NAME
-If set, spaces are ignored after an @@-command that takes braces.
-Default true, matching the @TeX{} behavior.
+@pindex texi2html
 
-@item INDEX_SPECIAL_CHARS_WARNING
-If set, warn about @samp{:} in index entry, as not all Info readers may
-be able to process these.  For Info and plaintext only.  Default false,
-because parsing problems there don't prevent navigation; readers can still
-relatively easily find their way to the node in question.
+@cindex Cons, Lionel
+Conceptually, the @command{texi2html} program is the parent of today's
+@command{texi2any} program.  @command{texi2html} was developed
+independently, originally by Lionel Cons in 1998; at the time,
+@command{makeinfo} could not generate HTML@.  Many other people
+contributed to @command{texi2html} over the years.
 
-@item INFO_SPECIAL_CHARS_QUOTE
-If set, whenever there are problematic characters for Info output in
-places such as node names or menu items, surround the part of the
-construct where they appear with quoting characters, as described in
-@ref{Info Format Specification}.  Default is set for Info and unset
-for plaintext.  @xref{Node Line Requirements}.
+The present @command{texi2any} uses little of the actual code of
+@command{texi2html}, and has quite a different basic approach to the
+implementation (namely, parsing the Texinfo document into a tree), but
+still, there is a family resemblance.
 
-@item INFO_SPECIAL_CHARS_WARNING
-If set, warn about problematic constructs for Info output (such as the
-string @samp{::}) in node names, menu items, and cross-references.
-If not defined, set unless @code{INFO_SPECIAL_CHARS_QUOTE} is set.
-Default is set for Info and not defined for plaintext. Similar warnings in
-index entries are covered by @code{INDEX_SPECIAL_CHARS_WARNING}.
+By design, @command{texi2any} supports nearly all the features of
+@command{texi2html} in some way.  However, we did not attempt to
+maintain strict compatibility, so no @command{texi2html} executable is
+installed by the Texinfo package.  An approximation can be run with an
+invocation like this:
 
-@cindex Encoding @subentry input file names
-@item INPUT_FILE_NAME_ENCODING
-Encoding used for input file names.  This variable overrides
-any encoding from the document or current locale.  Normally, you do
-not need to set this variable, but it can be used if file names are
-in a certain character encoding on a filesystem.  An alternative is to
-set @code{DOC_ENCODING_FOR_INPUT_FILE_NAME} to @samp{0} to use the locale
-encoding.  See also @code{OUTPUT_FILE_NAME_ENCODING}.
+@example
+texi2any --set-customization-variable TEXI2HTML=1 ...
+@end example
 
-@item LOCALE_ENCODING
-Locale encoding obtained from the system.  You should not need to
-explicitly set this variable.
+@noindent but, to emphasize, this is @emph{not} a drop-in replacement
+for the previous @command{texi2html}.  Here are the biggest differences:
 
-@item MAX_MACRO_CALL_NESTING
-The maximal number of recursive calls of @@-commands defined through
-@code{@@rmacro}; default 100000.  The purpose of this variable is to
-avoid infinite recursions.
+@itemize @bullet
+@item Most blatantly, the command line options of @command{texi2html}
+are now customization variables, for the most part.  A table of
+approximate equivalents is given below.
 
-@item MESSAGE_ENCODING
-Encoding used to encode messages output by @command{texi2any}.  Default is
-based on the locale encoding.
+@item The program-level customization API is very different in
+@command{texi2any}.
 
-It is also used for command-line argument passed to commands called from
-@command{texi2any}.  For example, @command{latex2html} will be called from
-@command{texi2any} if @code{HTML_MATH} is set to @samp{l2h}.
+@item Indices cannot be split.
 
-@item NO_TOP_NODE_OUTPUT
-@anchor{@code{NO_TOP_NODE_OUTPUT}}
-If set do not output the Top node content.  The Top node is still
-parsed, but the content is discarded.  Not set in the default case
-for HTML@.  Set in the default case for EPUB@.  If @code{SHOW_TITLE}
-is @samp{undef}, setting @code{NO_TOP_NODE_OUTPUT} also sets
-@code{SHOW_TITLE} for HTML.
+@end itemize
 
-Setting @code{NO_TOP_NODE_OUTPUT}, which removes the Top node and adds
-a title page corresponds more to the formatting of a book.  Setting
-@code{NO_TOP_NODE_OUTPUT} to false, with @code{SHOW_TITLE} remaining
-@samp{undef}, and false, corresponds more to a document setup for browsing,
-with a direct access to the information at the Top node.
+We do not intend to reimplement these
+differences.  Therefore, the route forward for authors is alter
+manuals and build processes as necessary to use the new features and
+methods of @command{texi2any}.  The @command{texi2html} maintainers
+(one of whom is the principal author of @command{texi2any}) do not
+intend to make further releases.
 
-For DocBook, @code{NO_TOP_NODE_OUTPUT} is set to true.  Setting
-@code{NO_TOP_NODE_OUTPUT} to false causes the Top node content to be
-output.  It is not recommended to output the Top node in DocBook as
-the title and copying informations are always output.  This option
-is kept for DocBook for compatibility, as before 2022 the Top node was output
-in DocBook.  It could be removed in the future.
+@cindex Options of @command{texi2html}
+@cindex Command-line options of @command{texi2html}
+Here is the table showing @command{texi2html} options and
+corresponding @command{texi2any} customization variables.
+@c (@pxref{texi2any Output Customization,, @command{texi2any} Output
+@c Customization}).
 
-@item NO_USE_SETFILENAME
-If set, do not use @code{@@setfilename} to set the document name;
-instead, base the output document name only on the input file name.
-The default is false.
+@multitable {@option{--frameset-doctype}} {@code{HTML_MATH} set to @samp{l2h}}
 
-@item NODE_NAME_IN_MENU
-If set, use node names in menu entries, otherwise prefer section names;
-default true.
+@item @option{--toc-links}            @tab @code{TOC_LINKS}
+@item @option{--short-ext}            @tab @code{EXTENSION} set to @samp{htm}
+@item @option{--prefix}               @tab @code{PREFIX}
+@item @option{--def-table}            @tab @code{DEF_TABLE}
+@item @option{--html-xref-prefix}     @tab @code{EXTERNAL_DIR}
+@item @option{--l2h}                  @tab @code{HTML_MATH} set to @samp{l2h}
+@item @option{--l2h-l2h}              @tab @code{L2H_L2H}
+@item @option{--l2h-skip}             @tab @code{L2H_SKIP}
+@item @option{--l2h-tmp}              @tab @code{L2H_TMP}
+@item @option{--l2h-file}             @tab @code{L2H_FILE}
+@item @option{--l2h-clean}            @tab @code{L2H_CLEAN}
+@item @option{--use-nodes}            @tab @code{USE_NODES}
+@item @option{--monolithic}           @tab @code{MONOLITHIC}
+@item @option{--top-file}             @tab @code{TOP_FILE}
+@item @option{--frames}               @tab no equivalent
+@item @option{--menu}                 @tab @code{FORMAT_MENU}
+@item @option{--debug}                @tab @code{DEBUG}
+@item @option{--doctype}              @tab @code{DOCTYPE}
+@item @option{--frameset-doctype}     @tab no equivalent
+@item @option{--test}                 @tab @code{TEST}
+@end multitable
 
-@item OPEN_QUOTE_SYMBOL
-When an opening quote is needed, e.g., for @samp{@@samp} output, use
-the specified character; default @code{&#8216;} for DocBook.
-Undefined in the default case in HTML and set to @code{&lsquo;}
-if @code{USE_NUMERIC_ENTITY} is not set, to @code{&#8217;} if set, and
-to a quote character if @code{OUTPUT_CHARACTERS} is set and the output
-encoding includes that character.
+@cindex @file{texi2oldapi.texi}, for @command{texi2html}
+Finally, any @command{texi2html} users seeking more detailed information can
+check the first part of the archived file @file{doc/texi2oldapi.texi} in the
+Texinfo source repository.
 
-For Info, the default depends on the enabled document encoding.  If
-@option{--disable-encoding} is set or the document encoding is not UTF-8,
-@samp{'} is used.  This character usually appears
-as an undirected single quote on modern systems.  Otherwise, the Info
-output uses a Unicode left quote.
 
-@item OPEN_DOUBLE_QUOTE_SYMBOL
-When an opening double quote is needed, for @samp{@@dfn} output in Info, use
-the specified character.  If @option{--disable-encoding} is set or the document
-encoding is not UTF-8, @samp{"} is used.  Otherwise, the Info output uses a
-Unicode left double quote.
+@node Creating and Installing Info Files
+@nodedescription Details on Info output.
+@chapter Creating and Installing Info Files
 
-@item OUTPUT_CHARACTERS
-If not set, the default, output accented and special characters in HTML, XML
-and DocBook using XML entities, and in @LaTeX{} using macros.  If set, output
-accented characters in HTML, XML, DocBook and @LaTeX{} output and special
-characters in HTML and @LaTeX{} output based on the document encoding.
-@xref{@code{@@documentencoding}}, and @ref{Inserting Accents}.
+@anchor{Creating an Info File}@c removed, merged to this node and Emacs Info 
mode
+
+This chapter gives some information on the Info output and describes how to
+install Info files.  For the creation of Info files with @command{texi2any}, 
see
+@ref{Generic Translator @command{texi2any}}, and with Emacs, @ref{Info
+Formatting}.  @xref{Info Files}, for general information about the file format.
+@xref{Info Format Specification}, for a detailed technical specification of the
+Info format.
 
-@item OUTPUT_ENCODING_NAME
-Normalized encoding name used for output files.  Should be a usable
-charset name in HTML, typically one of the preferred IANA encoding
-names.  By default, if an input encoding is set (typically through
-@code{@@documentencoding}), this information is used to set the output 
-encoding name, otherwise the output encoding is based on the
-default encoding.  @xref{@code{@@documentencoding}}.
 
-@cindex Encoding @subentry output file names
-@item OUTPUT_FILE_NAME_ENCODING
-Encoding used for output file names.  This variable overrides
-any encoding from the document or current locale.
+@node Installing an Info File
+@section Installing an Info File
+@cindex Installing an Info file
+@cindex Info files @subentry installation
+@cindex @file{dir} directory for Info installation
 
-Normally, you do not need to set this variable, but it can be used if file
-names should be created in a certain character encoding on a filesystem.
-See also @code{INPUT_FILE_NAME_ENCODING}.
+Info files are usually kept in the @file{info} directory.  You can
+read Info files using the standalone Info program or the Info reader
+built into Emacs.  (@xref{Top,,, info, Info}, for an introduction to
+Info.)
 
-@item PACKAGE
-@itemx PACKAGE_VERSION
-@itemx PACKAGE_AND_VERSION
-@itemx PACKAGE_URL
-@itemx PACKAGE_NAME
-The implementation's short package name, package version, package name
-and version concatenated, package URL@:, and full package name,
-respectively.  By default, these variables are all set through
-Autoconf, Automake, and @code{configure}.
 
-@item PREFIX
-The output file prefix, which is prepended to some output file names.
-By default it is set by @code{@@setfilename} or from the input file
-(@pxref{Setting the Output File Name}).  How this value is used depends on the
-value of other customization variables or command line options, such
-as whether the output is split.  The default is unset.
+@node Directory File
+@nodedescription The top-level menu for all Info files.
+@subsection The Directory File @file{dir}
 
-@item PROGRAM
-Name of the program used.  By default, it is set to the name of the
-program launched, with a trailing @samp{.pl} removed.
+For Info to work, the @file{info} directory must contain a file that
+serves as a top-level directory for the Info system.  By convention,
+this file is called @file{dir}.  (You can find the location of this file
+within Emacs by typing @kbd{C-h i} to enter Info and then typing
+@kbd{C-x C-f} to see the location of the @file{info} directory.)
 
-@pindex texi-elements-by-size
-@cindex Longest nodes, finding
-@cindex Sorting nodes by size
-@item SORT_ELEMENT_COUNT
-If set, the name of a file to which a list of elements (nodes or
-sections, depending on the output format) is dumped, sorted by the
-number of lines they contain after removal of @@-commands; default
-unset.  This is used by the program @code{texi-elements-by-size} in
-the @file{util/} directory of the Texinfo source distribution
-(@pxref{texi-elements-by-size}).
+The @file{dir} file is itself an Info file.  It contains the top-level
+menu for all the Info files in the system.  The menu looks like
+this:
 
-@item SORT_ELEMENT_COUNT_WORDS
-When dumping the elements-by-size file (see preceding item), use word
-counts instead of line counts; default false.
+@example
+@group
+* Menu:
+* Info:    (info).     Documentation browsing system.
+* Emacs:   (emacs).    The extensible, self-documenting
+                      text editor.
+* Texinfo: (texinfo).  With one source file, make
+                      either a printed manual using
+                      @@TeX@{@} or an Info file.
+@dots{}
+@end group
+@end example
 
-@item TEST
-If set to true, some variables which are normally dynamically
-generated anew for each run (date, program name, version) are set to
-fixed and given values.  This is useful to compare the output to a
-reference file, as is done for the tests.  The default is false.
+Each of these menu entries points to the `Top' node of the Info file
+that is named in parentheses.  (The menu entry does not need to
+specify the `Top' node, since Info goes to the `Top' node if no node
+name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
+Files}.)
 
-@item TEXI2DVI
-Name of the command used to produce PostScript, PDF, and DVI; default
-@samp{texi2dvi}.  @xref{@command{texi2any} Printed Output}.
+Thus, the @samp{Info} entry points to the `Top' node of the
+@file{info} file and the @samp{Emacs} entry points to the `Top' node
+of the @file{emacs} file.
 
-@cindex compatibility, with @command{texi2html}
-@item TEXI2HTML
-Generate HTML and try to be as compatible as possible with
-@command{texi2html}; default false.
+In each of the Info files, the `Up' pointer of the `Top' node refers
+back to the @code{dir} file.  For example, the line for the `Top'
+node of the Emacs manual looks like this in Info:
 
-@item TEXINFO_DTD_VERSION
-For XML@.  Version of the DTD used in the XML output preamble.  The
-default is set based on a variable in @file{configure.ac}.
+@example
+File: emacs  Node: Top, Up: (DIR), Next: Distrib
+@end example
 
-@item TEXTCONTENT_COMMENT
-For stripped text content output (i.e., when
-@code{TEXINFO_OUTPUT_FORMAT} is set to @code{textcontent}).  If set,
-also output comments.  Default false.
+@noindent
+In this case, the @file{dir} file name is written in uppercase
+letters---it can be written in either upper- or lowercase.  This is not
+true in general, it is a special case for @file{dir}.
 
-@item TOP_NODE_UP
-Up node for the Top node; default @samp{(dir)}.  This node name is 
-supposed to be already formatted for the output format.  In HTML
-can be used in attribute, so should not contain any element.  Used for
-HTML output only if @code{TOP_NODE_UP_URL} is set to override the URL@:,
-see @code{TOP_NODE_UP_URL} in @ref{HTML Customization Variables List}.  
+See the @file{util/dir-example} file in the Texinfo distribution for
+a large sample @code{dir} file.
 
-@item TREE_TRANSFORMATIONS
-The associated value is a comma separated list of transformations that
-can be applied to the Texinfo tree prior to outputting the result.  If
-more than one is specified, the ordering is irrelevant; each is always
-applied at the necessary point during processing.
 
-By default, the tree transformations @samp{move_index_entries_after_items}
-and @samp{relate_index_entries_to_table_entries} are executed
-for HTML and DocBook output.
-Here's an example of updating the master menu in a document:
+@node New Info File
+@nodedescription Listing a new Info file.
+@subsection Listing a New Info File
+@cindex Adding a new Info file
+@cindex Listing a new Info file
+@cindex New Info file, listing it in @file{dir} file
+@cindex Info files @subentry listing a new
+@cindex @file{dir} file listing
+
+To add a new Info file to your system, you must write a menu entry to
+add to the menu in the @file{dir} file in the @file{info} directory.
+For example, if you were adding documentation for GDB, you would write
+the following new entry:
 
 @example
-texi2any \
-  -c TREE_TRANSFORMATIONS=regenerate_master_menu \
-  -c TEXINFO_OUTPUT_FORMAT=plaintexinfo \
-  mydoc.texi \
-  -o /tmp/out
+* GDB: (gdb).           The source-level C debugger.
 @end example
 
-@noindent (Caveat: Since @samp{plaintexinfo} output expands
-Texinfo macros and conditionals, it's necessary to remove any such
-differences before installing the updates in the original document.
-This may be remedied in a future release.)
+@noindent
+The first part of the menu entry is the menu entry name, followed by a
+colon.  The second part is the name of the Info file, in parentheses,
+followed by a period.  The third part is the description.
 
-The following transformations are currently supported (many are used
-in the @code{pod2texi} utility distributed with Texinfo;
-@pxref{Invoking @command{pod2texi}}):
+The name of an Info file often has a @file{.info} extension.  Thus, the
+Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
+The Info reader programs automatically try the file name both with and
+without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
+try the @file{.inf} extension as well.}; so it is better to avoid
+clutter and not to write @samp{.info} explicitly in the menu entry.  For
+example, the GDB menu entry should use just @samp{gdb} for the file
+name, not @samp{gdb.info}.
 
-@ftable @samp
-@item complete_tree_nodes_menus
-Add menu entries or whole menus for nodes associated with sections of
-any level, based on the sectioning tree.
 
-@item complete_tree_nodes_missing_menu
-Add whole menus for nodes associated with sections without menu.  The
-menus are based on the sectioning tree.
+@node Other Info Directories
+@nodedescription How to specify Info files that are located in other 
directories.
+@subsection Info Files in Other Directories
+@cindex Installing Info in another directory
+@cindex Info installed in another directory
+@cindex Another Info directory
+@cindex @file{dir} files and Info directories
 
-@item fill_gaps_in_sectioning
-Adds empty @code{@@unnumbered...} sections in a tree to fill gaps in
-sectioning.  For example, an @code{@@unnumberedsec} will be inserted
-if a @code{@@chapter} is followed by a @code{@@subsection}.
+If an Info file is not in the @file{info} directory, there are three
+ways to specify its location:
 
-@item insert_nodes_for_sectioning_commands
-Insert nodes for sectioning commands lacking a corresponding node.
+@enumerate
+@item
+Write the file name in the @file{dir} file as the second part of the menu.
 
-@item move_index_entries_after_items
-In @code{@@enumerate} and @code{@@itemize}, move index entries
-appearing just before an @code{@@item} to just after the
-@code{@@item}.  Comment lines between index entries are moved too.  As
-mentioned, this is always done for HTML and DocBook output.
+@item
+Specify the Info directory name in the @code{INFOPATH} environment
+variable in your @file{.profile} or @file{.cshrc} initialization file.
+(Only you and others who set this environment variable will be able to
+find Info files whose location is specified this way.)
 
-@item regenerate_master_menu
-Update the Top node master menu, either replacing the (first)
-@code{@@detailmenu} in the Top node menu, or creating it at the end of
-the Top node menu.
+@item
+If you are using Emacs, list the name of the file in a second @file{dir}
+file, in its directory; and then add the name of that directory to the
+@code{Info-directory-list} variable in your personal or site
+initialization file.
 
-@item relate_index_entries_to_table_entries
-In @code{@@table}, @code{@@vtable} and @code{@@ftable},
-reassociate the index entry information from an index @@-command
-appearing right after an @code{@@item} line with the first element of
-the @code{@@item}.  Remove the index @@-command from the tree.
+This variable tells Emacs where to look for @file{dir} files (the files
+must be named @file{dir}).  Emacs merges the files named @file{dir} from
+each of the listed directories.  (In Emacs version 18, you can set the
+@code{Info-directory} variable to the name of only one
+directory.)
+@end enumerate
 
-@end ftable
+For example, to reach a test file in the @file{/home/bob/info}
+directory, you could add an entry like this to the menu in the
+standard @file{dir} file:
 
-@item USE_NODES
-Preferentially use nodes to decide where elements are separated.  If
-set to false, preferentially use sectioning to decide where elements
-are separated.  The default is true.
+@example
+* Test: (/home/bob/info/info-test).  Bob's own test file.
+@end example
 
-@item USE_NUMERIC_ENTITY
-For HTML, XML and DocBook@.  If set, use numeric entities instead of named
-entities.  By default, set to true for DocBook output.
+@noindent
+In this case, the absolute file name of the @file{info-test} file is
+written as the second part of the menu entry.
+
+@vindex INFOPATH
+@cindex Environment variable @code{INFOPATH}
+If you don't want to edit the system @file{dir} file, you can tell
+Info where to look by setting the @code{INFOPATH} environment variable
+in your shell startup file.  This works with both the Emacs and
+standalone Info readers.
+
+Emacs uses the @code{INFOPATH} environment variable to initialize the value of
+Emacs's own @code{Info-directory-list} variable.  The standalone Info reader
+merges any files named @file{dir} in any directory listed in the
+@env{INFOPATH} variable into a single menu presented to you in the node
+called @samp{(dir)Top}.
 
-@item USE_UP_NODE_FOR_ELEMENT_UP
-Fill in up sectioning direction with node direction when there is no
-sectioning up direction.  In practice this can only happen when there
-is no @@top section.  Not set by default.
+@cindex Colon, last in @env{INFOPATH}
+However you set @env{INFOPATH}, if its last character is a colon (on
+MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced
+by the default (compiled-in) path.  This gives you a way to augment
+the default path with new directories without having to list all the
+standard places.  For example (using @code{sh} syntax):
 
-@item USE_SETFILENAME_EXTENSION
-Default is on for Info, off for other output.  If set, use exactly
-what @code{@@setfilename} gives for the output file name, including
-the extension.  You should not need to explicitly set this variable.
+@example
+INFOPATH=/home/bob/info:
+export INFOPATH
+@end example
 
-@pindex Unicode::Collate
-@item USE_UNICODE_COLLATION
-By default, @command{texi2any} sorts document indices according to
-the @dfn{Unicode Collation Algorithm} (defined in
-@uref{http://www.unicode.org/reports/tr10/, Unicode Technical Standard #10}),
-which performs a @dfn{multi-level} ordering of strings containing Unicode
-code points.  (To do this, the program uses the @code{Unicode::Collate}
-module, a standard part of Perl installations.)  However, the use of
-this algorithm incurs noticeably longer run times when processing manuals
-with large indices.
+@noindent
+will search @file{/home/bob/info} first, then the standard directories.
+Leading or doubled colons are not treated specially.
 
-Set this variable to @samp{0} to use a simpler, faster sorting algorithm.
-@c which only uses Perl's built-in string comparison or strcmp in C
+@cindex @file{dir} file, creating your own
+When you create your own @file{dir} file for use with
+@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
+copying an existing @file{dir} file and replace all the text after the
+@samp{* Menu:} with your desired entries.  That way, the punctuation
+and special @kbd{CTRL-_} characters that Info needs will be present.
 
-You may find this useful for speeding up @command{texi2any} if you don't
-have many non-ASCII characters in index entry text, or if you don't care
-about having the indices sorted correctly, especially when working on
-the draft of a manual.
+As one final alternative, which works only with Emacs Info, you can
+change the @code{Info-directory-list} variable.  For example:
 
+@example
+(add-hook 'Info-mode-hook '(lambda ()
+            (add-to-list 'Info-directory-list
+                         (expand-file-name "~/info"))))
+@end example
 
-@pindex Text::Unidecode
-@item USE_UNIDECODE
-If set to false, do not use the @code{Text::Unidecode} Perl module to
-transliterate more characters; default true.
 
-@end vtable
+@node Installing Dir Entries
+@nodedescription How to specify what menu entry to add to the Info directory.
+@subsection Installing Info Directory Files
 
+When you install an Info file onto your system, you can use the program
+@code{install-info} to update the Info directory file @file{dir}.
+Normally the makefile for the package runs @code{install-info}, just
+after copying the Info file into its proper installed location.
 
-@node Internationalization of Document Strings
-@nodedescription Translating program-inserted text.
-@section Internationalization of Document Strings
 
-@cindex I18n, of document strings
-@cindex Internationalization of document strings
-@cindex Document strings, internationalization of
-@cindex Output document strings, internationalization of
-@cindex Translating strings in output documents
+@findex direntry
+In order for the Info file to work with @code{install-info}, you include
+the commands @code{@@dircategory} and
+@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
+file.  Use @code{@@direntry} to specify the menu entries to add to the
+Info directory file.  Use @code{@@dircategory} to specify a category
+for the manual, which determines which part of the Info directory to
+put it in.  @xref{Directory Category}.
 
-@vindex documentlanguage @r{customization variable}
-@command{texi2any} writes fixed strings into the output document at
-various places: cross-references, page footers, the help page,
-alternate text for images, and so on.  The string chosen depends on
-the value of the @code{documentlanguage} at the time of the string
-being output (@pxref{@code{@@documentlanguage}}, for the Texinfo
-command interface).
+Here is how these commands are used in this manual:
 
-@pindex libintl-perl @r{Gettext implementation}
-The Gettext framework is used for those strings (@pxref{Top,,,
-gettext, Gettext}).  The @code{libintl-perl} package is used as the
-@code{gettext} implementation; more specifically, the pure Perl
-implementation is used, so Texinfo can support consistent behavior
-across all platforms and installations, which would not otherwise be
-possible.  @code{libintl-perl} is included in the Texinfo distribution
-and always installed, to ensure that it is available if needed.  It is
-also possible to use the system @code{gettext} (the choice can be made
-at build-time).
+@example
+@@dircategory Texinfo documentation system
+@@direntry
+* Texinfo: (texinfo).           The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
+@dots{}
+@@end direntry
+@end example
 
-@vindex texinfo_document @r{Gettext domain}
-@cindex Perl format strings for translation
-The Gettext domain @samp{texinfo_document} is used for the strings.
-Translated strings are written as Texinfo, and may include
-@@-commands.  In translated strings, the varying parts of the string
-are not usually denoted by @code{%s} and the like, but by
-@samp{@{arg_name@}}.  (This convention is common for @code{gettext} in
-Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
-Format Strings, gettext, GNU Gettext}.)  For example, in the
-following, @samp{@{section@}} will be replaced by the section name:
+Here's what this produces in the Info file:
 
 @example
-see @{section@}
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Texinfo: (texinfo).           The GNU documentation format.
+* install-info: (texinfo)Invoking install-info. @dots{}
+@dots{}
+END-INFO-DIR-ENTRY
 @end example
 
-These Perl-style brace format strings are used for two reasons: first,
-changing the order of @code{printf} arguments is only available since
-Perl@tie{}5.8.0; second, and more importantly, the order of arguments
-is unpredictable, since @@-command expansion may lead to different
-orders depending on the output format.
+@noindent
+The @code{install-info} program sees these lines in the Info file, and
+that is how it knows what to do.
 
-The expansion of a translation string is done like this:
+Always use the @code{@@direntry} and @code{@@dircategory} commands near
+the beginning of the Texinfo input, before the first @code{@@node}
+command.  If you use them later on in the input, @code{install-info}
+will not notice them.
 
-@enumerate
-@item First, the string is translated.  The locale
-is @var{documentlanguage}@code{.}@var{documentencoding}.
+@code{install-info} will automatically reformat the description of the
+menu entries it is adding.  As a matter of convention, the description
+of the main entry (above, @samp{The GNU documentation format}) should
+start at column 32, starting at zero (as in
+@code{what-cursor-position} in Emacs).  This will make it align with
+most others.  Description for individual utilities best start in
+column 48, where possible.  For more information about formatting see
+the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
+@ref{Invoking @command{install-info}}.
 
-If the @var{documentlanguage} has the form @samp{ll_CC}, that is
-tried first, and then just @samp{ll}.
+If you use @code{@@dircategory} more than once in the Texinfo source,
+each usage specifies the `current' category; any subsequent
+@code{@@direntry} commands will add to that category.
 
-@item Next, in most cases, the string is expanded as Texinfo, and converted.
-The arguments are substituted; for example, @samp{@{arg_name@}} is replaced by
-the corresponding actual argument.
+@cindex Invoking nodes, including in dir file
+Each `Invoking' node for every program installed should have a
+corresponding @code{@@direntry}.  This lets users easily find the
+documentation for the different programs they can run, as with the
+traditional @command{man} system.
 
-It is also possible for the string and the argument to be already converted.
-In that case, the arguments are simply substituted.  Similarly,
-@samp{@{arg_name@}} is replaced by the corresponding actual argument.
 
-@end enumerate
+@node Invoking @command{install-info}
+@nodedescription @code{install-info} options.
+@subsection Invoking @command{install-info}
 
-In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
-and @samp{@{program@}} are the arguments of the string.  Since they
-are used in @code{@@uref}, their order is not predictable.
-@samp{@{date@}}, @samp{@{program_homepage@}} and @samp{@{program@}} are
-substituted after the expansion:
+@pindex install-info
+
+@code{install-info} inserts menu entries from an Info file into the
+top-level @file{dir} file in the Info system (see the previous sections
+for an explanation of how the @file{dir} file works).  @code{install-info}
+also removes menu entries from the @file{dir} file.  It's most often
+run as part of software installation, or when constructing a @file{dir} file
+for all manuals on a system.  Synopsis:
 
 @example
-Generated on @@emph@{@{date@}@} using
-@@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.
+install-info [@var{option}@dots{}] [@var{info-file} [@var{dir-file}]]
 @end example
 
-This approach is admittedly a bit complicated.  Its usefulness is that
-it supports having translations available in different encodings for
-encodings which can be covered by @@-commands, and also specifying how
-the formatting for some commands is done, independently of the output
-format---yet still be language-dependent.  For example, the
-@samp{@@pxref} translation string can be like this:
+If @var{info-file} or @var{dir-file} are not specified, the options
+(described below) that define them must be.  There are no compile-time
+defaults, and standard input is never used.  @code{install-info} can
+read only one Info file and write only one @file{dir} file per invocation.
 
-@example
-see @{node_file_href@} section `@{section@}' in @@cite@{@{book@}@}
-@end example
+@cindex @file{dir}, created by @code{install-info}
+If @var{dir-file} (however specified) does not exist,
+@code{install-info} creates it if possible (with no entries).
 
-@noindent
-which allows for specifying a string independently of the output
-format, while nevertheless with rich formatting it may be translated
-appropriately in many languages.
+@cindex Compressed dir files, reading
+@cindex XZ-compressed dir files, reading
+@cindex Bzipped dir files, reading
+@cindex Lzip-compressed dir files, reading
+@cindex LZMA-compressed dir files, reading
+@cindex Dir files, compressed
+If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip,
+Gzip}), @code{install-info} automatically uncompresses it for reading.
+And if @var{dir-file} is compressed, @code{install-info} also
+automatically leaves it compressed after writing any changes.  If
+@var{dir-file} itself does not exist, @code{install-info} tries to
+open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz},
+@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and
+@file{@var{dir-file}.lzma}, in that order.
 
+Options:
 
-@node Invoking @command{pod2texi}
-@nodedescription Translating Perl Pod to Texinfo.
-@section Invoking @command{pod2texi}: Convert Pod to Texinfo
+@table @code
+@item --add-once
+@opindex --add-once@r{, for @command{install-info}}
+Specifies that the entry or entries will only be put into a single section.
+
+@item --align=@var{column}
+@opindex --align=@var{column}@r{, for @command{install-info}}
+Specifies the column that the second and subsequent lines of menu entry's
+description will be formatted to begin at.  The default for this option is
+@samp{35}.  It is used in conjunction with the @samp{--max-width} option.
+@var{column} starts counting at 1.
+
+@item --append-new-sections
+@opindex --append-new-sections@r{, for @command{install-info}}
+Instead of alphabetizing new sections, place them at the end of the DIR file.
+
+@item --calign=@var{column}
+@opindex --calign=@var{column}@r{, for @command{install-info}}
+Specifies the column that the first line of menu entry's description will
+be formatted to begin at.  The default for this option is @samp{33}.  It is
+used in conjunction with the @samp{--max-width} option.
+When the name of the menu entry exceeds this column, entry's description
+will start on the following line.
+@var{column} starts counting at 1.
+
+@item --debug
+@opindex --debug@r{, for @command{install-info}}
+Report what is being done.
+
+@item --delete
+@opindex --delete@r{, for @command{install-info}}
+Delete the entries in @var{info-file} from @var{dir-file}.  The file
+name in the entry in @var{dir-file} must be @var{info-file} (except for
+an optional @samp{.info} in either one).  Don't insert any new entries.
+Any empty sections that result from the removal are also removed.
 
-@pindex pod2texi
-@cindex Invoking @command{pod2texi}
-@cindex Pod, converting to Texinfo
-@cindex Perl Pod, converting to Texinfo
+@item --description=@var{text}
+@opindex --description=@var{text}@r{, for @command{install-info}}
+Specify the explanatory portion of the menu entry.  If you don't specify
+a description (either via @samp{--entry}, @samp{--item} or this option),
+the description is taken from the Info file itself.
 
-The @command{pod2texi} program translates Perl Pod documentation file(s)
-to Texinfo.  There are two basic modes of operation: generating a
-standalone manual from each input Pod, or (if @code{--base-level=1} or
-higher is given) generating Texinfo subfiles suitable for use
-with @code{@@include}.
+@item --dir-file=@var{name}
+@opindex --dir-file=@var{name}@r{, for @command{install-info}}
+Specify file name of the Info directory file.  This is equivalent to
+using the @var{dir-file} argument.
 
-@c Although ordinarily this documentation in the Texinfo manual would be
-@c the best place to look, in this case we have documented all the
-@c options and examples in the @command{pod2texi} program itself, since it
-@c may be useful outside of the rest of Texinfo.  Thus, please see the
-@c output of @code{pod2texi --help}, the version on the web at
-@c @url{https://www.gnu.org/software/texinfo/manual/pod2texi.html}, etc.
+@item --dry-run
+@opindex --dry-run@r{, for @command{install-info}}
+Same as @samp{--test}.
 
-The @command{pod2texi} program may be useful outside of the rest of Texinfo;
-thus, the invocation of @command{pod2texi} is documented in the Pod language
-using the man page format to follow the convention used in Perl standalone
-programs, with a version on the web
-@url{https://www.gnu.org/software/texinfo/manual/pod2texi.html} and a version
-included below.  The version included in the manual is also an example of
-@command{pod2texi} use, as it is converted from Pod using @command{pod2texi}.
+@item --entry=@var{text}
+@opindex --entry=@var{text}@r{, for @command{install-info}}
+Insert @var{text} as an Info directory entry; @var{text} should have the
+form of an Info menu item line plus zero or more extra lines starting
+with whitespace.  If you specify more than one entry, they are all
+added.  If you don't specify any entries, they are determined from
+information in the Info file itself.
 
-@c there are issue with the perldoc-all generated files, as the perl 
documentation
-@c does not follows the Pod specification, there are anchors added
-@c using the first word in addition to the regular anchors.
-@c For an example of using @command{pod2texi} to make Texinfo out of the
-@c Perl documentation itself, see @file{contrib/perldoc-all}} in the Texinfo
-@c source distribution.
+@item --help
+@opindex --help@r{, for @command{texindex}}
+Display a usage message with basic usage and all available options,
+then exit successfully.
 
+@item --info-file=@var{file}
+@opindex --info-file=@var{file}@r{, for @command{install-info}}
+Specify Info file to install in the directory.  This is
+equivalent to using the @var{info-file} argument.
 
-@node pod2texi manual page
-@nodedescription @command{pod2texi} invocation in a manual page format.
-@include pod2texi.texi
+@item --info-dir=@var{dir}
+@opindex --info-dir=@var{dir}@r{, for @command{install-info}}
+Specify the directory where the directory file @file{dir} resides.
+Equivalent to @samp{--dir-file=@var{dir}/dir}.
 
+@item --infodir=@var{dir}
+@opindex --infodir=@var{dir}@r{, for @command{install-info}}
+Same as @samp{--info-dir}.
 
-@node @command{texi2html}
-@nodedescription An ancestor of @command{texi2any}.
-@section @command{texi2html}: Ancestor of @command{texi2any}
+@item --item=@var{text}
+@opindex --item=@var{text}@r{, for @command{install-info}}
+Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
+a menu item.
 
-@pindex texi2html
+@item --keep-old
+@opindex --keep-old@r{, for @command{install-info}}
+Do not replace pre-existing menu entries.  When @samp{--remove} is specified,
+this option means that empty sections are not removed.
 
-@cindex Cons, Lionel
-Conceptually, the @command{texi2html} program is the parent of today's
-@command{texi2any} program.  @command{texi2html} was developed
-independently, originally by Lionel Cons in 1998; at the time,
-@command{makeinfo} could not generate HTML@.  Many other people
-contributed to @command{texi2html} over the years.
+@item --max-width=@var{column}
+@opindex --max-width=@var{column}@r{, for @command{install-info}}
+Specifies the column that the menu entry's description will be word-wrapped
+at.  @var{column} starts counting at 1.
 
-The present @command{texi2any} uses little of the actual code of
-@command{texi2html}, and has quite a different basic approach to the
-implementation (namely, parsing the Texinfo document into a tree), but
-still, there is a family resemblance.
+@item --maxwidth=@var{column}
+@opindex --maxwidth=@var{column}@r{, for @command{install-info}}
+Same as @samp{--max-width}.
 
-By design, @command{texi2any} supports nearly all the features of
-@command{texi2html} in some way.  However, we did not attempt to
-maintain strict compatibility, so no @command{texi2html} executable is
-installed by the Texinfo package.  An approximation can be run with an
-invocation like this:
+@item --menuentry=@var{text}
+@opindex --menuentry=@var{text}@r{, for @command{install-info}}
+Same as @samp{--name}.
 
-@example
-texi2any --set-customization-variable TEXI2HTML=1 ...
-@end example
+@item --name=@var{text}
+@opindex --name=@var{text}@r{, for @command{install-info}}
+Specify the name portion of the menu entry.  If the @var{text} does
+not start with an asterisk @samp{*}, it is presumed to be the text
+after the @samp{*} and before the parentheses that specify the Info
+file.  Otherwise @var{text} is taken verbatim, and is taken as
+defining the text up to and including the first period (a space is
+appended if necessary).  If you don't specify the name (either via
+@samp{--entry}, @samp{--item} or this option), it is taken from the
+Info file itself.  If the Info does not contain the name, the basename
+of the Info file is used.
 
-@noindent but, to emphasize, this is @emph{not} a drop-in replacement
-for the previous @command{texi2html}.  Here are the biggest differences:
+@item --no-indent
+@opindex --no-indent@r{, for @command{install-info}}
+Suppress formatting of new entries into the @file{dir} file.
 
-@itemize @bullet
-@item Most blatantly, the command line options of @command{texi2html}
-are now customization variables, for the most part.  A table of
-approximate equivalents is given below.
+@item --quiet
+@itemx --silent
+@opindex --quiet@r{, for @command{install-info}}
+@opindex --silent@r{, for @command{install-info}}
+Suppress warnings, etc., for silent operation.
 
-@item The program-level customization API is very different in
-@command{texi2any}.
+@item --remove
+@opindex --remove@r{, for @command{install-info}}
+Same as @samp{--delete}.
 
-@item Indices cannot be split.
+@item --remove-exactly
+@opindex --remove-exactly@r{, for @command{install-info}}
+Also like @samp{--delete}, but only entries if the Info file name
+matches exactly; @code{.info} and/or @code{.gz} suffixes are
+@emph{not} ignored.
 
-@end itemize
+@item --section=@var{sec}
+@opindex --section=@var{sec}@r{, for @command{install-info}}
+Put this file's entries in section @var{sec} of the directory.  If you
+specify more than one section, all the entries are added in each of the
+sections.  If you don't specify any sections, they are determined from
+information in the Info file itself.  If the Info file doesn't specify
+a section, the menu entries are put into the Miscellaneous section.
 
-We do not intend to reimplement these
-differences.  Therefore, the route forward for authors is alter
-manuals and build processes as necessary to use the new features and
-methods of @command{texi2any}.  The @command{texi2html} maintainers
-(one of whom is the principal author of @command{texi2any}) do not
-intend to make further releases.
+@item --section @var{regex} @var{sec}
+@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}}
+Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
 
-@cindex Options of @command{texi2html}
-@cindex Command-line options of @command{texi2html}
-Here is the table showing @command{texi2html} options and
-corresponding @command{texi2any} customization variables.
-@c (@pxref{texi2any Output Customization,, @command{texi2any} Output
-@c Customization}).
+@code{install-info} tries to detect when this alternate syntax is used,
+but does not always guess correctly.  Here is the heuristic that
+@code{install-info} uses:
+@enumerate
+@item
+If the second argument to @code{--section} starts with a hyphen, the
+original syntax is presumed.
 
-@multitable {@option{--frameset-doctype}} {@code{HTML_MATH} set to @samp{l2h}}
+@item
+If the second argument to @code{--section} is a file that can be
+opened, the original syntax is presumed.
 
-@item @option{--toc-links}            @tab @code{TOC_LINKS}
-@item @option{--short-ext}            @tab @code{EXTENSION} set to @samp{htm}
-@item @option{--prefix}               @tab @code{PREFIX}
-@item @option{--def-table}            @tab @code{DEF_TABLE}
-@item @option{--html-xref-prefix}     @tab @code{EXTERNAL_DIR}
-@item @option{--l2h}                  @tab @code{HTML_MATH} set to @samp{l2h}
-@item @option{--l2h-l2h}              @tab @code{L2H_L2H}
-@item @option{--l2h-skip}             @tab @code{L2H_SKIP}
-@item @option{--l2h-tmp}              @tab @code{L2H_TMP}
-@item @option{--l2h-file}             @tab @code{L2H_FILE}
-@item @option{--l2h-clean}            @tab @code{L2H_CLEAN}
-@item @option{--use-nodes}            @tab @code{USE_NODES}
-@item @option{--monolithic}           @tab @code{MONOLITHIC}
-@item @option{--top-file}             @tab @code{TOP_FILE}
-@item @option{--frames}               @tab no equivalent
-@item @option{--menu}                 @tab @code{FORMAT_MENU}
-@item @option{--debug}                @tab @code{DEBUG}
-@item @option{--doctype}              @tab @code{DOCTYPE}
-@item @option{--frameset-doctype}     @tab no equivalent
-@item @option{--test}                 @tab @code{TEST}
-@end multitable
+@item
+Otherwise the alternate syntax is used.
+@end enumerate
 
-@cindex @file{texi2oldapi.texi}, for @command{texi2html}
-Finally, any @command{texi2html} users seeking more detailed information can
-check the first part of the archived file @file{doc/texi2oldapi.texi} in the
-Texinfo source repository.
+When the heuristic fails because your section title starts with a
+hyphen, or it happens to be a file that can be opened, the syntax
+should be changed to @samp{--regex=@var{regex} --section=@var{sec}
+--add-once}.
 
+@item --regex=@var{regex}
+@opindex  --regex=@var{regex}@r{, for @command{install-info}}
+Put this file's entries into any section that matches @var{regex}.  If
+more than one section matches, all of the entries are added in each of the
+sections.  Specify @var{regex} using basic regular expression syntax, more
+or less as used with @command{grep}, for example.
 
-@node Creating and Installing Info Files
-@nodedescription Details on Info output.
-@chapter Creating and Installing Info Files
+@item --test
+@opindex --test@r{, for @command{install-info}}
+Suppress updating of the directory file.
 
-@anchor{Creating an Info File}@c removed, merged to this node and Emacs Info 
mode
+@item --version
+@opindex --version@r{, for @command{install-info}}
+@cindex Version number, for install-info
+Display version information and exit successfully.
 
-This chapter gives some information on the Info output and describes how to
-install Info files.  For the creation of Info files with @command{texi2any}, 
see
-@ref{Generic Translator @command{texi2any}}, and with Emacs, @ref{Info
-Formatting}.  @xref{Info Files}, for general information about the file format.
-@xref{Info Format Specification}, for a detailed technical specification of the
-Info format.
+@end table
 
 
-@node Installing an Info File
-@section Installing an Info File
-@cindex Installing an Info file
-@cindex Info files @subentry installation
-@cindex @file{dir} directory for Info installation
+@node Tag and Split Files
+@section Tag Files and Split Files
 
-Info files are usually kept in the @file{info} directory.  You can
-read Info files using the standalone Info program or the Info reader
-built into Emacs.  (@xref{Top,,, info, Info}, for an introduction to
-Info.)
+@cindex Tag table
+@cindex nonsplit Info file
+@cindex split Info file
+Info files always contain a @dfn{tag table}, to be able to jump to
+nodes quickly.  Info files can be @dfn{nonsplit} (also called
+@dfn{unsplit}) or @dfn{split}.
 
+@cindex Indirect subfiles
+If the Info file contains less than about 300,000 characters the
+file should be nonsplit.  In that case, the tag table should
+appear at the end of the Info file.  If the Texinfo file contains
+more than about 300,000 characters, Texinfo processors split the
+large Info file into shorter @dfn{indirect} subfiles of about
+300,000 characters each.  With @command{texi2any}, splitting
+may be prevented by @option{--no-split}, and the default size
+of 300,000 characters may be modified with @option{--split-size}
+(@pxref{Invoking @command{texi2any}}).
 
-@node Directory File
-@nodedescription The top-level menu for all Info files.
-@subsection The Directory File @file{dir}
+When a file is split, Info itself makes use of a shortened version of
+the original file that contains just the tag table and references to
+the files that were split off.  The split-off files are called
+@dfn{indirect} files.
 
-For Info to work, the @file{info} directory must contain a file that
-serves as a top-level directory for the Info system.  By convention,
-this file is called @file{dir}.  (You can find the location of this file
-within Emacs by typing @kbd{C-h i} to enter Info and then typing
-@kbd{C-x C-f} to see the location of the @file{info} directory.)
+The split-off files have names that are created by appending @w{@samp{-1}},
+@w{@samp{-2}}, @w{@samp{-3}} and so on to the output file name, specified
+by the @code{@@setfilename} command or the input file name.  The shortened
+version of the original file continues to have the name specified by
+@code{@@setfilename} or the input file name.
 
-The @file{dir} file is itself an Info file.  It contains the top-level
-menu for all the Info files in the system.  The menu looks like
-this:
+At one stage in writing this document, for example, the Info file was saved
+as the file @file{test-texinfo} and that file looked like this:
 
 @example
 @group
-* Menu:
-* Info:    (info).     Documentation browsing system.
-* Emacs:   (emacs).    The extensible, self-documenting
-                      text editor.
-* Texinfo: (texinfo).  With one source file, make
-                      either a printed manual using
-                      @@TeX@{@} or an Info file.
+Info file: test-texinfo,    -*-Text-*-
+produced by texinfo-format-buffer
+from file: new-texinfo-manual.texinfo
+
+^_
+Indirect:
+test-texinfo-1: 102
+test-texinfo-2: 50422
+@end group
+@group
+test-texinfo-3: 101300
+^_^L
+Tag table:
+(Indirect)
+Node: overview^?104
+Node: info file^?1271
+@end group
+@group
+Node: printed manual^?4853
+Node: conventions^?6855
 @dots{}
 @end group
 @end example
 
-Each of these menu entries points to the `Top' node of the Info file
-that is named in parentheses.  (The menu entry does not need to
-specify the `Top' node, since Info goes to the `Top' node if no node
-name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
-Files}.)
+@noindent
+(But @file{test-texinfo} had far more nodes than are shown here.)  Each of
+the split-off, indirect files, @file{test-texinfo-1},
+@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
+after the line that says @samp{Indirect:}.  The tag table is listed after
+the line that says @samp{Tag table:}.
 
-Thus, the @samp{Info} entry points to the `Top' node of the
-@file{info} file and the @samp{Emacs} entry points to the `Top' node
-of the @file{emacs} file.
+In the list of indirect files, the number following the file name
+records the cumulative number of bytes in the preceding indirect
+files, not counting the file list itself, the tag table, or any
+permissions text in the first file.  In the tag table, the number
+following the node name records the location of the beginning of the
+node, in bytes from the beginning of the (unsplit) output.
 
-In each of the Info files, the `Up' pointer of the `Top' node refers
-back to the @code{dir} file.  For example, the line for the `Top'
-node of the Emacs manual looks like this in Info:
+If you are using @code{texinfo-format-buffer} to create Info files,
+you may want to run the @code{Info-validate} command.  (The
+@command{texi2any} command does such a good job on its own, you do not
+need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
+Info-validate} node-checking command on indirect files.  For
+information on how to prevent files from being split with
+@code{texinfo-format-buffer} and how to validate the structure of the nodes,
+see @ref{Using @code{Info-validate}}.
 
-@example
-File: emacs  Node: Top, Up: (DIR), Next: Distrib
-@end example
 
-@noindent
-In this case, the @file{dir} file name is written in uppercase
-letters---it can be written in either upper- or lowercase.  This is not
-true in general, it is a special case for @file{dir}.
+@node Info Format FAQ
+@section Info Format FAQ
 
-See the @file{util/dir-example} file in the Texinfo distribution for
-a large sample @code{dir} file.
+Here are some questions that have been frequently asked on
+the project mailing lists and elsewhere.
 
+@table @asis
+@item Why when I run @samp{info @var{foo}} do I get the same output as 
@samp{man @var{foo}}?
 
-@node New Info File
-@nodedescription Listing a new Info file.
-@subsection Listing a New Info File
-@cindex Adding a new Info file
-@cindex Listing a new Info file
-@cindex New Info file, listing it in @file{dir} file
-@cindex Info files @subentry listing a new
-@cindex @file{dir} file listing
+Check that the Info manuals are installed.  Not all GNU/Linux
+distributions install all the Info manuals by default.  This is
+regrettable, as often the Info manual provides more information than
+the provided man page.
 
-To add a new Info file to your system, you must write a menu entry to
-add to the menu in the @file{dir} file in the @file{info} directory.
-For example, if you were adding documentation for GDB, you would write
-the following new entry:
+@item Why not use HTML instead of Info?
 
-@example
-* GDB: (gdb).           The source-level C debugger.
-@end example
+Manuals are rarely written in the Info format itself, but are
+generated from Texinfo source by the @command{texi2any} program.
+@command{texi2any} can generate HTML as well as Info from Texinfo
+source. You can also access and download HTML manuals from the GNU
+website (@uref{https://www.gnu.org/manual/manual.html}).  Additionally,
+some GNU/Linux distributions provide packages for the installation
+of HTML manuals.
 
-@noindent
-The first part of the menu entry is the menu entry name, followed by a
-colon.  The second part is the name of the Info file, in parentheses,
-followed by a period.  The third part is the description.
+Info still has some advantages over HTML for locally installed
+documentation.  The Info browsers support index lookup and support
+for links between locally installed manuals in multiple locations.
+It's important to have documentation installed locally on your machine
+rather than relying on the Internet; this makes accessing documentation
+more reliable, and ensures it matches installed versions of packages.
+It's hoped that support for browsing locally installed Texinfo
+documentation in some form of HTML can be improved in the future.
 
-The name of an Info file often has a @file{.info} extension.  Thus, the
-Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
-The Info reader programs automatically try the file name both with and
-without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
-try the @file{.inf} extension as well.}; so it is better to avoid
-clutter and not to write @samp{.info} explicitly in the menu entry.  For
-example, the GDB menu entry should use just @samp{gdb} for the file
-name, not @samp{gdb.info}.
 
+@item Why provide the command-line @command{info} program when the Emacs Info 
reader is better?
 
-@node Other Info Directories
-@nodedescription How to specify Info files that are located in other 
directories.
-@subsection Info Files in Other Directories
-@cindex Installing Info in another directory
-@cindex Info installed in another directory
-@cindex Another Info directory
-@cindex @file{dir} files and Info directories
+The Emacs Info reader can display images, and fully supports using
+a mouse.  There are not many differences among the Info readers
+besides that.  Command-line @command{info} can be configured
+to change the default key bindings, as well as change the color
+of cross-references and search results, and to enable mouse
+scrolling support.  You should not need to be experienced with
+the Emacs editor to use @command{info}.  (Some recommend another
+program called @command{pinfo}, but this lacks in important
+features like index lookup.)
 
-If an Info file is not in the @file{info} directory, there are three
-ways to specify its location:
+Some prefer to be able to scroll through the entire manual at once (as
+happens with man pages), rather than being limited to a single `node'
+of content at once.  Of course, there is no accounting for taste,
+but a single, unstructured block of text becomes more awkward as a
+manual becomes longer and more complicated.  (However, if you really
+want to, you can view an info manual all at once in the @command{less}
+pager with @samp{info @var{foo} | less}.)
 
-@enumerate
-@item
-Write the file name in the @file{dir} file as the second part of the menu.
+@item Why do I have `see' appearing in front of all of my links?
 
-@item
-Specify the Info directory name in the @code{INFOPATH} environment
-variable in your @file{.profile} or @file{.cshrc} initialization file.
-(Only you and others who set this environment variable will be able to
-find Info files whose location is specified this way.)
+By default, Emacs Info mode either changes the marker @samp{*note} for
+cross-references to `see', or hides it completely.  Command-line
+@command{info} does the same if @code{hide-note-references} is set.
+Unfortunately, there is no way to do this reliably, as both the @code{@@pxref}
+and @code{@@ref} commands in Texinfo output this marker in the Info
+output, and the `see' text is only appropriate for @code{@@pxref}.
 
-@item
-If you are using Emacs, list the name of the file in a second @file{dir}
-file, in its directory; and then add the name of that directory to the
-@code{Info-directory-list} variable in your personal or site
-initialization file.
+@item Yes, but how do I get a plain link, with no extra markup?
 
-This variable tells Emacs where to look for @file{dir} files (the files
-must be named @file{dir}).  Emacs merges the files named @file{dir} from
-each of the listed directories.  (In Emacs version 18, you can set the
-@code{Info-directory} variable to the name of only one
-directory.)
-@end enumerate
+You can't.  Info is a plain text format that is displayed mostly as-is
+in the viewers, and without the @samp{*note} text there would be nothing
+to mark text as a link.
 
-For example, to reach a test file in the @file{/home/bob/info}
-directory, you could add an entry like this to the menu in the
-standard @file{dir} file:
+For output formats such as HTML, you can use the @code{@@link} command
+to produce a plain link.  @xref{@code{@@link}}.  This does not produce
+a working cross-reference in Info output or in a printed copy of the
+manual, though.
 
-@example
-* Test: (/home/bob/info/info-test).  Bob's own test file.
-@end example
 
-@noindent
-In this case, the absolute file name of the @file{info-test} file is
-written as the second part of the menu entry.
+@item Why do lines containing links appear mysteriously short?
 
-@vindex INFOPATH
-@cindex Environment variable @code{INFOPATH}
-If you don't want to edit the system @file{dir} file, you can tell
-Info where to look by setting the @code{INFOPATH} environment variable
-in your shell startup file.  This works with both the Emacs and
-standalone Info readers.
+This due to Emacs (or @command{info} with @code{hide-note-references}
+set to @samp{On}) hiding @samp{*note} strings, as mentioned above.
 
-Emacs uses the @code{INFOPATH} environment variable to initialize the value of
-Emacs's own @code{Info-directory-list} variable.  The standalone Info reader
-merges any files named @file{dir} in any directory listed in the
-@env{INFOPATH} variable into a single menu presented to you in the node
-called @samp{(dir)Top}.
+@item Can the Info format be extended to support fonts, colors or reflowable 
text?
 
-@cindex Colon, last in @env{INFOPATH}
-However you set @env{INFOPATH}, if its last character is a colon (on
-MS-DOS/MS-Windows systems, use a semicolon instead), this is replaced
-by the default (compiled-in) path.  This gives you a way to augment
-the default path with new directories without having to list all the
-standard places.  For example (using @code{sh} syntax):
+Any extension would be incompatible with existing Info-viewing programs.
+Extra markup added to Info files would be displayed to the user, making
+files ugly and unreadable.
+
+When Texinfo files are processed into Info files, information about
+which Texinfo commands were used to markup text is lost.  Moreover,
+it is not possible to reliably detect whether text can be reflowed
+(e.g.@: a paragraph of prose), or whether line breaks should be kept
+(e.g.@: a code sample, or poem).
+
+Info's core purpose is to display documentation on text terminals.
+If you want more, you are recommended to use the HTML output from
+@command{texi2any} instead.
+
+@end table
+
+
+@node Generating HTML
+@nodedescription Details on HTML output.
+@chapter Generating HTML
+
+@cindex Generating HTML
+@cindex Outputting HTML
 
-@example
-INFOPATH=/home/bob/info:
-export INFOPATH
-@end example
+@command{texi2any} generates Info output by default, but given the
+@option{--html} option, it will generate HTML, for web browsers and
+other programs.  This chapter gives some details on such HTML output.
 
-@noindent
-will search @file{/home/bob/info} first, then the standard directories.
-Leading or doubled colons are not treated specially.
+@command{texi2any} has many user-definable customization variables
+with which you can influence the HTML output.  @xref{HTML Output
+Advanced Customization}.  In particular, there is support for syntax
+highlighting in @code{@@example} (@pxref{Syntax Highlighting}). You can also
+write so-called @dfn{initialization files}, or @dfn{init files} for short, to
+modify almost every aspect of HTML output formatting.  Initialization files
+contain code and are loaded by @option{--init-file} (@pxref{Invoking
+@command{texi2any}}).
 
-@cindex @file{dir} file, creating your own
-When you create your own @file{dir} file for use with
-@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
-copying an existing @file{dir} file and replace all the text after the
-@samp{* Menu:} with your desired entries.  That way, the punctuation
-and special @kbd{CTRL-_} characters that Info needs will be present.
+Some initialization files are maintained with Texinfo and installed
+in the default case.  For example, @file{chm.pm} produces the intermediate
+compressed HTML Help format files that can be subsequently converted to
+the CHM format.
 
-As one final alternative, which works only with Emacs Info, you can
-change the @code{Info-directory-list} variable.  For example:
+The documentation of @command{texi2any} HTML output adaptation using
+customization files is in a separate manual.  @xref{,,, texi2any_api, GNU
+Texinfo @command{texi2any} Output Customization}.
 
-@example
-(add-hook 'Info-mode-hook '(lambda ()
-            (add-to-list 'Info-directory-list
-                         (expand-file-name "~/info"))))
-@end example
 
+@node HTML Translation
+@nodedescription Details of the HTML output.
+@section HTML Translation
 
-@node Installing Dir Entries
-@nodedescription How to specify what menu entry to add to the Info directory.
-@subsection Installing Info Directory Files
+@cindex HTML translation
 
-When you install an Info file onto your system, you can use the program
-@code{install-info} to update the Info directory file @file{dir}.
-Normally the makefile for the package runs @code{install-info}, just
-after copying the Info file into its proper installed location.
+The HTML generated by @command{texi2any} generates standard HTML
+output.  The output is intentionally quite plain for maximum portability
+and accessibility.
 
+You can customize the output via CSS (@pxref{HTML CSS}) or other
+means (@pxref{Customization Variables}).  If you cannot accomplish
+a reasonable customization, feel free to report that.
 
-@findex direntry
-In order for the Info file to work with @code{install-info}, you include
-the commands @code{@@dircategory} and
-@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
-file.  Use @code{@@direntry} to specify the menu entries to add to the
-Info directory file.  Use @code{@@dircategory} to specify a category
-for the manual, which determines which part of the Info directory to
-put it in.  @xref{Directory Category}.
+@cindex Navigation bar, in HTML output
+@strong{Navigation bar:} By default, a navigation bar is inserted at the
+start of each node, analogous to Info output.  If the
+@samp{--no-headers} option is used, the navigation bar is only
+inserted at the beginning of split files.  Header @code{<link>} elements
+in split output support Info-like navigation with browsers which implement
+this feature.
 
-Here is how these commands are used in this manual:
+@cindex Escaping to HTML
+@cindex Raw HTML
+@strong{Raw HTML}: @command{texi2any} will include segments of Texinfo
+source between @code{@@ifhtml} and @code{@@end ifhtml} in the HTML
+output (but not any of the other conditionals, by default).  Source
+between @code{@@html} and @code{@@end html} is passed without change
+to the output (i.e., suppressing the normal escaping of input
+@samp{<}, @samp{>} and @samp{&} characters which have special
+significance in HTML)@.  @xref{Conditional Commands}.
 
-@example
-@@dircategory Texinfo documentation system
-@@direntry
-* Texinfo: (texinfo).           The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. @dots{}
-@dots{}
-@@end direntry
-@end example
+@cindex HTML output, browser compatibility of
+@strong{Standards}:
+It is intentionally not our goal, and not even always possible, to pass
+through every conceivable validation test without any diagnostics.
+Different validation tests have different goals, often about pedantic
+enforcement of some standard or another.  Our overriding goal is to
+help users, not blindly comply with standards.
 
-Here's what this produces in the Info file:
+Please report output from an
+error-free run of @command{texi2any} which has @emph{practical} browser
+or EPUB reader portability problems as a bug (@pxref{Reporting Bugs}).
 
-@example
-INFO-DIR-SECTION Texinfo documentation system
-START-INFO-DIR-ENTRY
-* Texinfo: (texinfo).           The GNU documentation format.
-* install-info: (texinfo)Invoking install-info. @dots{}
-@dots{}
-END-INFO-DIR-ENTRY
-@end example
+In practice, the HTML produced by @command{texi2any} is slowly adjusted
+over time towards the latest HTML standard, while also trying to keep
+compatibility with earlier produced HTML.  We use transitional markup
+and try to be slow enough to give time for the diverse HTML readers
+to adjust (and for standards to reincorporate useful features that were
+dropped@dots{}).
 
-@noindent
-The @code{install-info} program sees these lines in the Info file, and
-that is how it knows what to do.
 
-Always use the @code{@@direntry} and @code{@@dircategory} commands near
-the beginning of the Texinfo input, before the first @code{@@node}
-command.  If you use them later on in the input, @code{install-info}
-will not notice them.
+@node HTML Splitting
+@nodedescription How HTML output is split.
+@section HTML Splitting
+@cindex Split HTML output
+@cindex HTML output, split
 
-@code{install-info} will automatically reformat the description of the
-menu entries it is adding.  As a matter of convention, the description
-of the main entry (above, @samp{The GNU documentation format}) should
-start at column 32, starting at zero (as in
-@code{what-cursor-position} in Emacs).  This will make it align with
-most others.  Description for individual utilities best start in
-column 48, where possible.  For more information about formatting see
-the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
-@ref{Invoking @command{install-info}}.
+When splitting output at nodes (which is the default),
+@command{texi2any} writes HTML output into (basically) one output file
+per Texinfo source @code{@@node}.
 
-If you use @code{@@dircategory} more than once in the Texinfo source,
-each usage specifies the `current' category; any subsequent
-@code{@@direntry} commands will add to that category.
+Each output file name is the node name with spaces replaced by
+@samp{-}'s and special characters changed to @samp{_} followed by
+their code point in hex (@pxref{HTML Xref}).  This is to make it
+portable and easy to use as a file name.  In the unusual case of two
+different nodes having the same name after this treatment, they are
+written consecutively to the same file, with HTML anchors so each can
+be referred to independently.
 
-@cindex Invoking nodes, including in dir file
-Each `Invoking' node for every program installed should have a
-corresponding @code{@@direntry}.  This lets users easily find the
-documentation for the different programs they can run, as with the
-traditional @command{man} system.
+If @command{texi2any} is run on a system which does not distinguish
+case in file names, nodes which are the same except for case (e.g.,
+@samp{index} and @samp{Index}) will also be folded into the same
+output file with anchors.  You can also pretend to be on a case
+insensitive filesystem by setting the customization variable
+@code{CASE_INSENSITIVE_FILENAMES}.
 
+It is also possible to split at chapters or sections with
+@option{--split} (@pxref{Invoking @command{texi2any}}).  In that case,
+the file names are constructed after the name of the node associated
+with the relevant sectioning command.  Also, unless
+@option{--no-node-files} is specified, a redirection file is output
+for every node in order to more reliably support cross-references to
+that manual (@pxref{HTML Xref}).
 
-@node Invoking @command{install-info}
-@nodedescription @code{install-info} options.
-@subsection Invoking @command{install-info}
+When splitting, the HTML output files are written into a subdirectory.  The
+subdirectory name is derived from the base name (that
+is, any extension is removed), with @code{_html} postpended. For example, HTML
+output for @file{gcc.texi} would be written into a subdirectory
+named @samp{gcc_html/}.  The subdirectory name is based on @code{@@setfilename}
+or on the input file name (@pxref{Setting the Output File Name}).
 
-@pindex install-info
+@noindent In any case, the top-level output file within the directory
+is always named @samp{index.html}.
 
-@code{install-info} inserts menu entries from an Info file into the
-top-level @file{dir} file in the Info system (see the previous sections
-for an explanation of how the @file{dir} file works).  @code{install-info}
-also removes menu entries from the @file{dir} file.  It's most often
-run as part of software installation, or when constructing a @file{dir} file
-for all manuals on a system.  Synopsis:
+Monolithic output (@code{--no-split}) is named according to
+@code{@@setfilename}, if present (with any @samp{.info} extension replaced
+with @samp{.html}), @code{--output} (the argument is used literally), or
+based on the input file name as a last resort
+(@pxref{Setting the Output File Name}).
 
-@example
-install-info [@var{option}@dots{}] [@var{info-file} [@var{dir-file}]]
-@end example
 
-If @var{info-file} or @var{dir-file} are not specified, the options
-(described below) that define them must be.  There are no compile-time
-defaults, and standard input is never used.  @code{install-info} can
-read only one Info file and write only one @file{dir} file per invocation.
+@node HTML CSS
+@nodedescription Influencing HTML output with Cascading Style Sheets.
+@section HTML CSS
+@cindex HTML, and CSS
+@cindex CSS, and HTML output
+@cindex Cascading Style Sheets, and HTML output
 
-@cindex @file{dir}, created by @code{install-info}
-If @var{dir-file} (however specified) does not exist,
-@code{install-info} creates it if possible (with no entries).
+Cascading Style Sheets (CSS) is an Internet standard for
+influencing the display of HTML documents: see
+@uref{http://www.w3.org/Style/CSS/}.
 
-@cindex Compressed dir files, reading
-@cindex XZ-compressed dir files, reading
-@cindex Bzipped dir files, reading
-@cindex Lzip-compressed dir files, reading
-@cindex LZMA-compressed dir files, reading
-@cindex Dir files, compressed
-If any input file is compressed with @code{gzip} (@pxref{Top,,, gzip,
-Gzip}), @code{install-info} automatically uncompresses it for reading.
-And if @var{dir-file} is compressed, @code{install-info} also
-automatically leaves it compressed after writing any changes.  If
-@var{dir-file} itself does not exist, @code{install-info} tries to
-open @file{@var{dir-file}.gz}, @file{@var{dir-file}.xz},
-@file{@var{dir-file}.bz2}, @file{@var{dir-file}.lz}, and
-@file{@var{dir-file}.lzma}, in that order.
+By default, some CSS code is included to better implement the
+appearance of some Texinfo environments.  For example:
 
-Options:
+@example
+pre.display @{ font-family:inherit @}
+@end example
 
-@table @code
-@item --add-once
-@opindex --add-once@r{, for @command{install-info}}
-Specifies that the entry or entries will only be put into a single section.
+The above tells the web browser to use the same font as the main
+document inside @samp{<pre>} elements used for @code{@@display} environments.
+By default, the HTML @samp{<pre>} command uses a monospaced font.
 
-@item --align=@var{column}
-@opindex --align=@var{column}@r{, for @command{install-info}}
-Specifies the column that the second and subsequent lines of menu entry's
-description will be formatted to begin at.  The default for this option is
-@samp{35}.  It is used in conjunction with the @samp{--max-width} option.
-@var{column} starts counting at 1.
+Please see the reference above for a full explanation of CSS.
 
-@item --append-new-sections
-@opindex --append-new-sections@r{, for @command{install-info}}
-Instead of alphabetizing new sections, place them at the end of the DIR file.
+You can influence the CSS in the HTML output with two
+@command{texi2any} options: @option{--css-include=@var{file}} and
+@option{--css-ref=@var{url}}.
 
-@item --calign=@var{column}
-@opindex --calign=@var{column}@r{, for @command{install-info}}
-Specifies the column that the first line of menu entry's description will
-be formatted to begin at.  The default for this option is @samp{33}.  It is
-used in conjunction with the @samp{--max-width} option.
-When the name of the menu entry exceeds this column, entry's description
-will start on the following line.
-@var{column} starts counting at 1.
+The option @option{--css-ref=@var{url}} adds to each output HTML file
+a @samp{<link>} tag referencing a CSS at the given @var{url}.  This
+allows using external style sheets.
 
-@item --debug
-@opindex --debug@r{, for @command{install-info}}
-Report what is being done.
+The option @option{--css-include=@var{file}} includes the contents
+@var{file} in the HTML output, as you might expect.  However, the
+details are somewhat tricky, as described in the following, to provide
+maximum flexibility.
 
-@item --delete
-@opindex --delete@r{, for @command{install-info}}
-Delete the entries in @var{info-file} from @var{dir-file}.  The file
-name in the entry in @var{dir-file} must be @var{info-file} (except for
-an optional @samp{.info} in either one).  Don't insert any new entries.
-Any empty sections that result from the removal are also removed.
+@cindex @samp{@@charset} specification, in CSS files
+The CSS file first line may be a @samp{@@charset} directive.  If present,
+this directive is used to determine the encoding of the CSS file.  The
+line is not copied into the output.
 
-@item --description=@var{text}
-@opindex --description=@var{text}@r{, for @command{install-info}}
-Specify the explanatory portion of the menu entry.  If you don't specify
-a description (either via @samp{--entry}, @samp{--item} or this option),
-the description is taken from the Info file itself.
+@cindex @samp{@@import} specifications, in CSS files
+The CSS file may begin with so-called @samp{@@import} directives,
+which link to external CSS specifications for browsers to use when
+interpreting the document.  Again, a full description is beyond our
+scope here, but we'll describe how they work syntactically, so we can
+explain how they are handled.
 
-@item --dir-file=@var{name}
-@opindex --dir-file=@var{name}@r{, for @command{install-info}}
-Specify file name of the Info directory file.  This is equivalent to
-using the @var{dir-file} argument.
+@cindex Comments, in CSS files
+There can be more than one @samp{@@import}, but they have to come
+first in the file, with only whitespace and comments interspersed, no normal
+definitions.  Comments in CSS files are delimited by @samp{/* ... */}, as in
+C@.  An @samp{@@import} directive must be in one of these two forms:
 
-@item --dry-run
-@opindex --dry-run@r{, for @command{install-info}}
-Same as @samp{--test}.
+@example
+@@import url(http://example.org/foo.css);
+@@import "http://example.net/bar.css";;
+@end example
 
-@item --entry=@var{text}
-@opindex --entry=@var{text}@r{, for @command{install-info}}
-Insert @var{text} as an Info directory entry; @var{text} should have the
-form of an Info menu item line plus zero or more extra lines starting
-with whitespace.  If you specify more than one entry, they are all
-added.  If you don't specify any entries, they are determined from
-information in the Info file itself.
+The crucial characters are the @samp{@@} at the beginning and
+the semicolon terminating the directive.  When reading the CSS
+file, any such @samp{@@}-directive is simply copied into the
+output, as follows:
 
-@item --help
-@opindex --help@r{, for @command{texindex}}
-Display a usage message with basic usage and all available options,
-then exit successfully.
+@itemize
+@item If @var{file} contains only normal CSS declarations, it is
+included after the default CSS, thus overriding it.
 
-@item --info-file=@var{file}
-@opindex --info-file=@var{file}@r{, for @command{install-info}}
-Specify Info file to install in the directory.  This is
-equivalent to using the @var{info-file} argument.
+@item If @var{file} begins with @samp{@@import} specifications (see
+below), then the @samp{import}'s are included first (they have to come
+first, according to the standard), and then the default CSS is
+included.  If you need to override the default CSS from an
+@samp{@@import}, you can do so with the @samp{!@: important} CSS
+construct, as in:
+@example
+pre.example @{ font-size: inherit ! important @}
+@end example
 
-@item --info-dir=@var{dir}
-@opindex --info-dir=@var{dir}@r{, for @command{install-info}}
-Specify the directory where the directory file @file{dir} resides.
-Equivalent to @samp{--dir-file=@var{dir}/dir}.
+@item If @var{file} contains both @samp{@@import} and inline CSS
+specifications, the @samp{@@import}'s are included first, then
+default CSS, and lastly the inline CSS from @var{file}.
 
-@item --infodir=@var{dir}
-@opindex --infodir=@var{dir}@r{, for @command{install-info}}
-Same as @samp{--info-dir}.
+@item Any @@-directive other than @samp{@@import} and @samp{@@charset}
+is treated as a CSS declaration, meaning the default CSS is included
+and then the rest of the file is prepended.
+@end itemize
 
-@item --item=@var{text}
-@opindex --item=@var{text}@r{, for @command{install-info}}
-Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
-a menu item.
+If the CSS file is malformed or erroneous, the output
+is unspecified.  The meaning of the CSS file is not interpreted in
+any way; the special @samp{@@} and @samp{;} characters are looked for
+the text is blindly copied into the output.  Comments in the CSS
+file may or may not be included in the output.
 
-@item --keep-old
-@opindex --keep-old@r{, for @command{install-info}}
-Do not replace pre-existing menu entries.  When @samp{--remove} is specified,
-this option means that empty sections are not removed.
+In the default case, classes are added to the HTML elements and CSS rules
+associated to these classes are output at the beginning of each HTML file.  Set
+the @code{NO_CSS} customization variable to prevent classes to be added and CSS
+to be used. Set @code{INLINE_CSS_STYLE} to have CSS code put in HTML
+elements in the @code{style} attribute rather than at the beginning of
+the output.
 
-@item --max-width=@var{column}
-@opindex --max-width=@var{column}@r{, for @command{install-info}}
-Specifies the column that the menu entry's description will be word-wrapped
-at.  @var{column} starts counting at 1.
+Since @command{texi2any} only inserts CSS code needed by the HTML
+actually output, the full list of CSS code potentially inserted is
+not visible in the output document.  To get the full list of CSS rules, call
+@command{texi2any} with the @code{SHOW_BUILTIN_CSS_RULES} customization
+variable set to output the built-in default CSS rules on the standard output
+and exit, like:
+@example
+texi2any -c SHOW_BUILTIN_CSS_RULES=1
+@end example
 
-@item --maxwidth=@var{column}
-@opindex --maxwidth=@var{column}@r{, for @command{install-info}}
-Same as @samp{--max-width}.
 
-@item --menuentry=@var{text}
-@opindex --menuentry=@var{text}@r{, for @command{install-info}}
-Same as @samp{--name}.
+@node @code{@@documentdescription}
+@nodedescription Document summary for the HTML output.
+@section @code{@@documentdescription}: Summary Text
+@anchor{documentdescription}@c old name
 
-@item --name=@var{text}
-@opindex --name=@var{text}@r{, for @command{install-info}}
-Specify the name portion of the menu entry.  If the @var{text} does
-not start with an asterisk @samp{*}, it is presumed to be the text
-after the @samp{*} and before the parentheses that specify the Info
-file.  Otherwise @var{text} is taken verbatim, and is taken as
-defining the text up to and including the first period (a space is
-appended if necessary).  If you don't specify the name (either via
-@samp{--entry}, @samp{--item} or this option), it is taken from the
-Info file itself.  If the Info does not contain the name, the basename
-of the Info file is used.
+@cindex Document description
+@cindex Description of document
+@cindex Summary of document
+@cindex Abstract of document
+@cindex @code{<meta>} HTML tag, and document description
+@findex documentdescription
 
-@item --no-indent
-@opindex --no-indent@r{, for @command{install-info}}
-Suppress formatting of new entries into the @file{dir} file.
+When producing HTML output for a document, a @samp{<meta>} element
+is written in the @samp{<head>} to give some idea of the
+content of the document.  By default, this @dfn{description} is the
+title of the document, taken from the @code{@@settitle} command
+(@pxref{@code{@@settitle}}).  To change this, use the
+@code{@@documentdescription} environment, as in:
 
-@item --quiet
-@itemx --silent
-@opindex --quiet@r{, for @command{install-info}}
-@opindex --silent@r{, for @command{install-info}}
-Suppress warnings, etc., for silent operation.
+@example
+@@documentdescription
+descriptive text.
+@@end documentdescription
+@end example
 
-@item --remove
-@opindex --remove@r{, for @command{install-info}}
-Same as @samp{--delete}.
+@noindent
+This will produce the following output in the @samp{<head>} of the HTML:
 
-@item --remove-exactly
-@opindex --remove-exactly@r{, for @command{install-info}}
-Also like @samp{--delete}, but only entries if the Info file name
-matches exactly; @code{.info} and/or @code{.gz} suffixes are
-@emph{not} ignored.
+@example
+<meta name=description content="descriptive text.">
+@end example
 
-@item --section=@var{sec}
-@opindex --section=@var{sec}@r{, for @command{install-info}}
-Put this file's entries in section @var{sec} of the directory.  If you
-specify more than one section, all the entries are added in each of the
-sections.  If you don't specify any sections, they are determined from
-information in the Info file itself.  If the Info file doesn't specify
-a section, the menu entries are put into the Miscellaneous section.
 
-@item --section @var{regex} @var{sec}
-@opindex --section @var{regex} @var{sec}@r{, for @command{install-info}}
-Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
+@node Generating EPUB
+@nodedescription Details on the EPUB output.
+@section Generating EPUB
 
-@code{install-info} tries to detect when this alternate syntax is used,
-but does not always guess correctly.  Here is the heuristic that
-@code{install-info} uses:
-@enumerate
-@item
-If the second argument to @code{--section} starts with a hyphen, the
-original syntax is presumed.
+@cindex EPUB, generating
+@cindex Generating EPUB
+@cindex Outputting EPUB
 
-@item
-If the second argument to @code{--section} is a file that can be
-opened, the original syntax is presumed.
+EPUB is a format designed for reading electronic books on portable
+devices.  @command{texi2any} generated EPUB 3.2 in 2022.  An EPUB
+file is a ZIP archive container, holding informative files as
+well as the manual rendered in HTML.
 
-@item
-Otherwise the alternate syntax is used.
-@end enumerate
+@cindex @code{Archive::Zip}, for EPUB file output
+@vindex EPUB_CREATE_CONTAINER_FILE @subentry @r{avoiding} @code{Archive::Zip} 
@r{dependency}
+The generation of the EPUB file depends on the @code{Archive::Zip}
+Perl module being installed.  This dependency is checked at runtime.
+In the default case, trying to output EPUB without this dependency raises an
+error.  However, if the EPUB output file is not generated, with the
+customization variable @code{EPUB_CREATE_CONTAINER_FILE} set to 0, it is
+not an error if @code{Archive::Zip} is not installed.
 
-When the heuristic fails because your section title starts with a
-hyphen, or it happens to be a file that can be opened, the syntax
-should be changed to @samp{--regex=@var{regex} --section=@var{sec}
---add-once}.
+The @command{texi2any} tests related to EPUB generation do not require the
+installation of @code{Archive::Zip}, as they set
+@code{EPUB_CREATE_CONTAINER_FILE} to 0 and keep the directory containing
+the files and directories needed for the EPUB file by setting the
+@code{EPUB_KEEP_CONTAINER_FOLDER} customization variable to 1.
 
-@item --regex=@var{regex}
-@opindex  --regex=@var{regex}@r{, for @command{install-info}}
-Put this file's entries into any section that matches @var{regex}.  If
-more than one section matches, all of the entries are added in each of the
-sections.  Specify @var{regex} using basic regular expression syntax, more
-or less as used with @command{grep}, for example.
 
-@item --test
-@opindex --test@r{, for @command{install-info}}
-Suppress updating of the directory file.
+@node EPUB Output File and Directory
+@nodedescription Use syntax highlighting in code excerpts.
+@subsection Container Directory and Output Files
 
-@item --version
-@opindex --version@r{, for @command{install-info}}
-@cindex Version number, for install-info
-Display version information and exit successfully.
+@cindex Container directory for EPUB
+@cindex EPUB Container directory
+A directory containing the files and directories needed for the
+EPUB format is created when outputting EPUB@.  The name of this
+container directory is derived from the base name of the input file (that
+is, any extension is removed), with @code{_epub_package} postpended.
+If an output directory is specified, with @option{--output},
+or with the @code{SUBDIR} customization variable,
+the container directory is created in that directory instead of
+the current directory.  At the beginning of a new run, the container
+directory and all its contents are removed.  The container directory
+is also removed after the final EPUB file has been generated in the
+default case.
 
-@end table
+The HTML files produced from the Texinfo manual are output in subdirectories
+of the container directory.  Image files referred to from the Texinfo manual,
+if found, are copied to subdirectories of the container directory.
 
+@cindex EPUB output file
+The EPUB output file is a ZIP archive of the container directory.
+The file name is derived from the base name, with the @code{.epub}
+extension postpended.  If an output file is specified, with
+@option{--output}, or with the @code{OUTFILE} customization function,
+this file name is used instead.  The output EPUB file is never placed
+in the directory specified by @option{--output} or @code{SUBDIR};
+only the container directory is placed there, as explained just above.
 
-@node Tag and Split Files
-@section Tag Files and Split Files
+The EPUB output file is not generated if the customization variable
+@code{EPUB_CREATE_CONTAINER_FILE} is set to 0.  The container directory
+is left after the final EPUB file has been generated if
+@code{EPUB_KEEP_CONTAINER_FOLDER} is set.
 
-@cindex Tag table
-@cindex nonsplit Info file
-@cindex split Info file
-Info files always contain a @dfn{tag table}, to be able to jump to
-nodes quickly.  Info files can be @dfn{nonsplit} (also called
-@dfn{unsplit}) or @dfn{split}.
+@xref{Invoking @command{texi2any}}.
 
-@cindex Indirect subfiles
-If the Info file contains less than about 300,000 characters the
-file should be nonsplit.  In that case, the tag table should
-appear at the end of the Info file.  If the Texinfo file contains
-more than about 300,000 characters, Texinfo processors split the
-large Info file into shorter @dfn{indirect} subfiles of about
-300,000 characters each.  With @command{texi2any}, splitting
-may be prevented by @option{--no-split}, and the default size
-of 300,000 characters may be modified with @option{--split-size}
-(@pxref{Invoking @command{texi2any}}).
 
-When a file is split, Info itself makes use of a shortened version of
-the original file that contains just the tag table and references to
-the files that were split off.  The split-off files are called
-@dfn{indirect} files.
+@node EPUB Cross-References
+@nodedescription Cross-references in HTML output.
+@subsection EPUB Cross-References
 
-The split-off files have names that are created by appending @w{@samp{-1}},
-@w{@samp{-2}}, @w{@samp{-3}} and so on to the output file name, specified
-by the @code{@@setfilename} command or the input file name.  The shortened
-version of the original file continues to have the name specified by
-@code{@@setfilename} or the input file name.
+The EPUB format does not support references from an EPUB file to
+another EPUB file.  Therefore any references to ``external'' Texinfo
+manuals should resolve to an external URL@:.  @command{texi2any}
+produces these links with HTML cross-reference configuration
+(@pxref{HTML Xref Configuration}).  Since the links in the
+resulting EPUB are incorrect if no information is found for the
+cross-references, @command{texi2any} issues a warning by default for
+missing cross-references information.  If these warnings are unwanted,
+set @code{CHECK_HTMLXREF} to 0.
 
-At one stage in writing this document, for example, the Info file was saved
-as the file @file{test-texinfo} and that file looked like this:
 
-@example
-@group
-Info file: test-texinfo,    -*-Text-*-
-produced by texinfo-format-buffer
-from file: new-texinfo-manual.texinfo
+@node EPUB HTML
+@subsection HTML Generated for EPUB
 
-^_
-Indirect:
-test-texinfo-1: 102
-test-texinfo-2: 50422
-@end group
-@group
-test-texinfo-3: 101300
-^_^L
-Tag table:
-(Indirect)
-Node: overview^?104
-Node: info file^?1271
-@end group
-@group
-Node: printed manual^?4853
-Node: conventions^?6855
-@dots{}
-@end group
-@end example
+The HTML generated for EPUB is XHTML conformant, UTF-8 encoded, and
+formatted without the usual HTML navigation headers and footers.
+Most of these features are enabled with customization variables, such as
+@code{USE_XML_SYNTAX} or @code{OUTPUT_FILE_NAME_ENCODING}.  Some
+features of printed output are used in EPUB@.  In particular, the Top
+node does not appear in the EPUB output, while a title page is
+generated.  This is obtained by setting @code{NO_TOP_NODE_OUTPUT}.
 
-@noindent
-(But @file{test-texinfo} had far more nodes than are shown here.)  Each of
-the split-off, indirect files, @file{test-texinfo-1},
-@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
-after the line that says @samp{Indirect:}.  The tag table is listed after
-the line that says @samp{Tag table:}.
+The @code{OUTFILE} and @code{SUBDIR} customization variables values
+correspond initially to the EPUB directory container and/or the
+EPUB output file (@pxref{EPUB Output File and Directory}).  These
+customization variables values are undefined or reset to the
+locations in the container directory where the XHTML files are output
+for the HTML generation.  It is mentioned here because resetting
+customization variables is unusual; however, the variables reset are
+used internally for the conversion, and should not interact with any
+customization set by the user.
 
-In the list of indirect files, the number following the file name
-records the cumulative number of bytes in the preceding indirect
-files, not counting the file list itself, the tag table, or any
-permissions text in the first file.  In the tag table, the number
-following the node name records the location of the beginning of the
-node, in bytes from the beginning of the (unsplit) output.
+@xref{HTML Customization Variables List}.
 
-If you are using @code{texinfo-format-buffer} to create Info files,
-you may want to run the @code{Info-validate} command.  (The
-@command{texi2any} command does such a good job on its own, you do not
-need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
-Info-validate} node-checking command on indirect files.  For
-information on how to prevent files from being split with
-@code{texinfo-format-buffer} and how to validate the structure of the nodes,
-see @ref{Using @code{Info-validate}}.
 
+@node Syntax Highlighting
+@section Code Examples Syntax Highlighting in HTML
+@cindex @command{source-highlight}
 
-@node Info Format FAQ
-@section Info Format FAQ
+@cartouche
+@quotation warning
+Source highlighting is experimental, feedback is welcomed.
+@end quotation
+@end cartouche
 
-Here are some questions that have been frequently asked on
-the project mailing lists and elsewhere.
+Support for source code syntax highlighting is available in
+@command{texi2any} for the HTML output, with the help of external software.
+This feature is turned on by setting @code{HIGHLIGHT_SYNTAX}.  Source code
+highlighting is set up for @code{@@example} blocks.  The language
+specified for syntax highlighting is the first argument on the 
@code{@@example} line
+(@pxref{@code{@@example}}), or @code{HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE} if set
+and there is no first argument.
 
-@table @asis
-@item Why when I run @samp{info @var{foo}} do I get the same output as 
@samp{man @var{foo}}?
+The @code{HIGHLIGHT_SYNTAX} value determines the command used for highlighting:
+@table @code
+@item highlight
+Use @command{highlight} from
+@url{http://www.andre-simon.de/doku/highlight/en/highlight.php};
+@item pygments
+Use @command{pygmentize} from @url{https://pygments.org/};
+@item anything else
+Use @command{source-highlight} (@pxref{,,,source-highlight, GNU 
Source-highlight}).
+@end table
 
-Check that the Info manuals are installed.  Not all GNU/Linux
-distributions install all the Info manuals by default.  This is
-regrettable, as often the Info manual provides more information than
-the provided man page.
+@xref{Other Customization Variables}.
 
-@item Why not use HTML instead of Info?
 
-Manuals are rarely written in the Info format itself, but are
-generated from Texinfo source by the @command{texi2any} program.
-@command{texi2any} can generate HTML as well as Info from Texinfo
-source. You can also access and download HTML manuals from the GNU
-website (@uref{https://www.gnu.org/manual/manual.html}).  Additionally,
-some GNU/Linux distributions provide packages for the installation
-of HTML manuals.
+@node HTML Xref
+@section HTML Cross-references
+@cindex HTML cross-references
+@cindex Cross-references, in HTML output
 
-Info still has some advantages over HTML for locally installed
-documentation.  The Info browsers support index lookup and support
-for links between locally installed manuals in multiple locations.
-It's important to have documentation installed locally on your machine
-rather than relying on the Internet; this makes accessing documentation
-more reliable, and ensures it matches installed versions of packages.
-It's hoped that support for browsing locally installed Texinfo
-documentation in some form of HTML can be improved in the future.
+Cross-references between Texinfo manuals in HTML format become standard
+HTML @code{<a>} links.  This section describes the algorithm used,
+so that Texinfo can cooperate with other programs, such as
+@command{texi2html}, by writing mutually compatible HTML files.
 
+This algorithm may or may not be used for links @emph{within} HTML
+output for a Texinfo file.  Since no issues of compatibility arise in
+such cases, we do not need to specify this.
 
-@item Why provide the command-line @command{info} program when the Emacs Info 
reader is better?
+We try to support references to such ``external'' manuals in both
+monolithic and split forms.  A @dfn{monolithic} (mono) manual is
+entirely contained in one file, and a @dfn{split} manual has a file
+for each node.  (@xref{HTML Splitting}.)
 
-The Emacs Info reader can display images, and fully supports using
-a mouse.  There are not many differences among the Info readers
-besides that.  Command-line @command{info} can be configured
-to change the default key bindings, as well as change the color
-of cross-references and search results, and to enable mouse
-scrolling support.  You should not need to be experienced with
-the Emacs editor to use @command{info}.  (Some recommend another
-program called @command{pinfo}, but this lacks in important
-features like index lookup.)
+@cindex Dumas, Patrice
+The algorithm was primarily devised by Patrice Dumas in 2003--04.
 
-Some prefer to be able to scroll through the entire manual at once (as
-happens with man pages), rather than being limited to a single `node'
-of content at once.  Of course, there is no accounting for taste,
-but a single, unstructured block of text becomes more awkward as a
-manual becomes longer and more complicated.  (However, if you really
-want to, you can view an info manual all at once in the @command{less}
-pager with @samp{info @var{foo} | less}.)
+@menu
+* Link Basics:       HTML Xref Link Basics.
+* Node Expansion:    HTML Xref Node Name Expansion.
+* Command Expansion: HTML Xref Command Expansion.
+* 8-bit Expansion:   HTML Xref 8-bit Character Expansion.
+* Mismatch:          HTML Xref Mismatch.
+* Configuration:     HTML Xref Configuration.
+@end menu
 
-@item Why do I have `see' appearing in front of all of my links?
 
-By default, Emacs Info mode either changes the marker @samp{*note} for
-cross-references to `see', or hides it completely.  Command-line
-@command{info} does the same if @code{hide-note-references} is set.
-Unfortunately, there is no way to do this reliably, as both the @code{@@pxref}
-and @code{@@ref} commands in Texinfo output this marker in the Info
-output, and the `see' text is only appropriate for @code{@@pxref}.
+@node HTML Xref Link Basics
+@subsection HTML Cross-reference Link Basics
+@cindex HTML cross-references @subentry link basics
 
-@item Yes, but how do I get a plain link, with no extra markup?
+For our purposes, an HTML link consists of four components: a host
+name, a directory part, a file part, and a target part.  We
+always assume the @code{http} protocol.  For example:
 
-You can't.  Info is a plain text format that is displayed mostly as-is
-in the viewers, and without the @samp{*note} text there would be nothing
-to mark text as a link.
+@example
+http://@var{host}/@var{dir}/@var{file}.html#@var{target}
+@end example
 
-For output formats such as HTML, you can use the @code{@@link} command
-to produce a plain link.  @xref{@code{@@link}}.  This does not produce
-a working cross-reference in Info output or in a printed copy of the
-manual, though.
+The information to construct a link comes from the node name and
+manual name in the cross-reference command in the Texinfo source
+(@pxref{Cross References}), and from @dfn{external information}
+(@pxref{HTML Xref Configuration}).
 
+We now consider each part in turn.
 
-@item Why do lines containing links appear mysteriously short?
+The @var{host} is hardwired to be the local host.  This could either
+be the literal string @samp{localhost}, or, according to the rules for
+HTML links, the @samp{http://localhost/} could be omitted entirely.
 
-This due to Emacs (or @command{info} with @code{hide-note-references}
-set to @samp{On}) hiding @samp{*note} strings, as mentioned above.
+The @var{dir} and @var{file} parts are more complicated, and depend on
+the relative split/mono nature of both the manual being processed and
+the manual that the cross-reference refers to.  The underlying idea is
+that there is one directory for Texinfo manuals in HTML, and a given
+@var{manual} is either available as a monolithic file
+@file{@var{manual}.html}, or a split subdirectory
+@file{@var{manual}_html/*.html}.  Here are the cases:
 
-@item Can the Info format be extended to support fonts, colors or reflowable 
text?
+@itemize @bullet
+@item
+If the present manual is split, and the referent manual is also split,
+the directory is @samp{../@var{referent}_html/} and the file is the
+expanded node name (described later).
 
-Any extension would be incompatible with existing Info-viewing programs.
-Extra markup added to Info files would be displayed to the user, making
-files ugly and unreadable.
+@item
+If the present manual is split, and the referent manual is mono, the
+directory is @samp{../} and the file is @file{@var{referent}.html}.
 
-When Texinfo files are processed into Info files, information about
-which Texinfo commands were used to markup text is lost.  Moreover,
-it is not possible to reliably detect whether text can be reflowed
-(e.g.@: a paragraph of prose), or whether line breaks should be kept
-(e.g.@: a code sample, or poem).
+@item
+If the present manual is mono, and the referent manual is split, the
+directory is @file{@var{referent}_html/} and the file is the expanded node
+name.
 
-Info's core purpose is to display documentation on text terminals.
-If you want more, you are recommended to use the HTML output from
-@command{texi2any} instead.
+@item
+If the present manual is mono, and the referent manual is also mono,
+the directory is @file{./} (or just the empty string), and the file is
+@file{@var{referent}.html}.
 
-@end table
+@end itemize
 
+Another rule, that only holds for file names, is that base file names
+are truncated to 245 characters, to allow for an extension to be
+appended and still comply with the 255-character limit which is common
+to many filesystems.  Although technically this can be changed with
+the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other
+Customization Variables}), doing so would make cross-manual references
+to such nodes invalid.
 
-@node Generating HTML
-@nodedescription Details on HTML output.
-@chapter Generating HTML
+Any directory part in the file name argument of the source cross
+reference command is ignored.  Thus, @code{@@xref@{,,,../foo@}} and
+@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name.  This
+is because any such attempted hardwiring of the directory is very
+unlikely to be useful for all the output formats that use the manual
+name.
 
-@cindex Generating HTML
-@cindex Outputting HTML
+Finally, the @var{target} part is always the expanded node name.
 
-@command{texi2any} generates Info output by default, but given the
-@option{--html} option, it will generate HTML, for web browsers and
-other programs.  This chapter gives some details on such HTML output.
+Whether the present manual is split or mono is determined by user
+option; @command{texi2any} defaults to split, with the
+@option{--no-split} option overriding this.
 
-@command{texi2any} has many user-definable customization variables
-with which you can influence the HTML output.  @xref{Customization
-Variables}.  In particular, there is support for syntax highlighting in
-@code{@@example} (@pxref{Syntax Highlighting}). You can also write so-called
-@dfn{initialization files}, or @dfn{init files} for short, to modify almost
-every aspect of HTML output formatting.  Initialization files contain code and
-are loaded by @option{--init-file} (@pxref{Invoking @command{texi2any}}).
+Whether the referent manual is split or mono, however, is another bit
+of the external information (@pxref{HTML Xref Configuration}).  By
+default, @command{texi2any} uses the same form of the referent manual
+as the present manual.
 
-Some initialization files are maintained with Texinfo and installed
-in the default case.  For example, @file{chm.pm} produces the intermediate
-compressed HTML Help format files that can be subsequently converted to
-the CHM format.
+Thus, there can be a mismatch between the format of the referent
+manual that the generating software assumes, and the format it's
+actually present in.  @xref{HTML Xref Mismatch}.
 
-The documentation of @command{texi2any} HTML output adaptation using
-customization files is in a separate manual.  @xref{,,, texi2any_api, GNU
-Texinfo @command{texi2any} Output Customization}.
 
+@node HTML Xref Node Name Expansion
+@subsection HTML Cross-reference Node Name Expansion
+@cindex HTML cross-references @subentry node name expansion
+@cindex node name expansion, in HTML cross-references
+@cindex expansion, of node names in HTML cross-references
 
-@node HTML Translation
-@nodedescription Details of the HTML output.
-@section HTML Translation
+As mentioned in the previous section, the key part of the HTML cross
+reference algorithm is the conversion of node names in the Texinfo
+source into strings suitable for XHTML identifiers and file names.  The
+restrictions are similar for each: plain ASCII letters, numbers, and
+the @samp{-} and @samp{_} characters are all that can be used.
+(Although HTML anchors can contain most characters, XHTML is more
+restrictive.)
 
-@cindex HTML translation
+Cross-references in Texinfo can refer either to nodes, anchors
+(@pxref{@code{@@anchor}}) or float labels (@pxref{@code{@@float}}).
+However, anchors and float labels are treated identically
+to nodes in this context, so we'll continue to say ``node'' names for
+simplicity.
 
-The HTML generated by @command{texi2any} generates standard HTML
-output.  The output is intentionally quite plain for maximum portability
-and accessibility.
+A special exception: the Top node (@pxref{The Top Node}) is always
+mapped to the file @file{index.html}, to match web server software.
+However, the HTML @emph{target} is @samp{Top}.  Thus (in the split case):
 
-You can customize the output via CSS (@pxref{HTML CSS}) or other
-means (@pxref{Customization Variables}).  If you cannot accomplish
-a reasonable customization, feel free to report that.
+@example
+@@xref@{Top,,, emacs, The GNU Emacs Manual@}.
+@result{} <a href="../emacs_html/index.html#Top">
+@end example
 
-@cindex Navigation bar, in HTML output
-@strong{Navigation bar:} By default, a navigation bar is inserted at the
-start of each node, analogous to Info output.  If the
-@samp{--no-headers} option is used, the navigation bar is only
-inserted at the beginning of split files.  Header @code{<link>} elements
-in split output support Info-like navigation with browsers which implement
-this feature.
+@enumerate
+@item
+The standard ASCII letters (a-z and A-Z) are not modified.  All other
+characters may be changed as specified below.
 
-@cindex Escaping to HTML
-@cindex Raw HTML
-@strong{Raw HTML}: @command{texi2any} will include segments of Texinfo
-source between @code{@@ifhtml} and @code{@@end ifhtml} in the HTML
-output (but not any of the other conditionals, by default).  Source
-between @code{@@html} and @code{@@end html} is passed without change
-to the output (i.e., suppressing the normal escaping of input
-@samp{<}, @samp{>} and @samp{&} characters which have special
-significance in HTML)@.  @xref{Conditional Commands}.
+@item
+The standard ASCII numbers (0-9) are not modified except when a number
+is the first character of the node name.  In that case, see below.
 
-@cindex HTML output, browser compatibility of
-@strong{Standards}:
-It is intentionally not our goal, and not even always possible, to pass
-through every conceivable validation test without any diagnostics.
-Different validation tests have different goals, often about pedantic
-enforcement of some standard or another.  Our overriding goal is to
-help users, not blindly comply with standards.
+@item
+Multiple consecutive space, tab and newline characters are transformed
+into just one space.
 
-Please report output from an
-error-free run of @command{texi2any} which has @emph{practical} browser
-or EPUB reader portability problems as a bug (@pxref{Reporting Bugs}).
+@item
+Leading and trailing spaces are removed.
 
-In practice, the HTML produced by @command{texi2any} is slowly adjusted
-over time towards the latest HTML standard, while also trying to keep
-compatibility with earlier produced HTML.  We use transitional markup
-and try to be slow enough to give time for the diverse HTML readers
-to adjust (and for standards to reincorporate useful features that were
-dropped@dots{}).
+@item
+After the above has been applied, each remaining space character is
+converted into a @samp{-} character.
 
+@item
+Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
+where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
+This includes @samp{_}, which is mapped to @samp{_005f}.
 
-@node HTML Splitting
-@nodedescription How HTML output is split.
-@section HTML Splitting
-@cindex Split HTML output
-@cindex HTML output, split
+@item
+If the node name does not begin with a letter, the literal string
+@samp{g_t} is prefixed to the result.  (Due to the rules above, that
+string can never occur otherwise; it is an arbitrary choice, standing
+for ``GNU Texinfo''.)  This is necessary because XHTML requires that
+identifiers begin with a letter.
 
-When splitting output at nodes (which is the default),
-@command{texi2any} writes HTML output into (basically) one output file
-per Texinfo source @code{@@node}.
+@end enumerate
 
-Each output file name is the node name with spaces replaced by
-@samp{-}'s and special characters changed to @samp{_} followed by
-their code point in hex (@pxref{HTML Xref}).  This is to make it
-portable and easy to use as a file name.  In the unusual case of two
-different nodes having the same name after this treatment, they are
-written consecutively to the same file, with HTML anchors so each can
-be referred to independently.
+For example:
 
-If @command{texi2any} is run on a system which does not distinguish
-case in file names, nodes which are the same except for case (e.g.,
-@samp{index} and @samp{Index}) will also be folded into the same
-output file with anchors.  You can also pretend to be on a case
-insensitive filesystem by setting the customization variable
-@code{CASE_INSENSITIVE_FILENAMES}.
+@example
+@@node A  node --- with _'%
+@result{} A-node-_002d_002d_002d-with-_005f_0027_0025
+@end example
 
-It is also possible to split at chapters or sections with
-@option{--split} (@pxref{Invoking @command{texi2any}}).  In that case,
-the file names are constructed after the name of the node associated
-with the relevant sectioning command.  Also, unless
-@option{--no-node-files} is specified, a redirection file is output
-for every node in order to more reliably support cross-references to
-that manual (@pxref{HTML Xref}).
+Example translations of common characters:
 
-When splitting, the HTML output files are written into a subdirectory.  The
-subdirectory name is derived from the base name (that
-is, any extension is removed), with @code{_html} postpended. For example, HTML
-output for @file{gcc.texi} would be written into a subdirectory
-named @samp{gcc_html/}.  The subdirectory name is based on @code{@@setfilename}
-or on the input file name (@pxref{Setting the Output File Name}).
+@itemize @bullet
+@item @samp{_} @result{} @samp{_005f}
+@item @samp{-} @result{} @samp{_002d}
+@item @samp{A  node} @result{} @samp{A-node}
+@end itemize
 
-@noindent In any case, the top-level output file within the directory
-is always named @samp{index.html}.
+On case-folding computer systems, nodes differing only by case will be
+mapped to the same file.  In particular, as mentioned above, Top
+always maps to the file @file{index.html}.  Thus, on a case-folding
+system, Top and a node named `Index' will both be written to
+@file{index.html}.  Fortunately, the targets serve to distinguish
+these cases, since HTML target names are always case-sensitive,
+independent of operating system.
 
-Monolithic output (@code{--no-split}) is named according to
-@code{@@setfilename}, if present (with any @samp{.info} extension replaced
-with @samp{.html}), @code{--output} (the argument is used literally), or
-based on the input file name as a last resort
-(@pxref{Setting the Output File Name}).
 
+@node HTML Xref Command Expansion
+@subsection HTML Cross-reference Command Expansion
+@cindex HTML cross-references @subentry command expansion
+
+Node names may contain @@-commands (@pxref{Node Line Requirements}).
+This section describes how they are handled.
 
-@node HTML CSS
-@nodedescription Influencing HTML output with Cascading Style Sheets.
-@section HTML CSS
-@cindex HTML, and CSS
-@cindex CSS, and HTML output
-@cindex Cascading Style Sheets, and HTML output
+First, comments are removed.
 
-Cascading Style Sheets (CSS) is an Internet standard for
-influencing the display of HTML documents: see
-@uref{http://www.w3.org/Style/CSS/}.
+Next, any @code{@@value} commands (@pxref{@code{@@set @@value}}) and
+macro invocations (@pxref{Invoking Macros}) are fully expanded.
 
-By default, some CSS code is included to better implement the
-appearance of some Texinfo environments.  For example:
+Then, for the following commands, the command name and braces are removed,
+and the text of the argument is recursively transformed:
 
 @example
-pre.display @{ font-family:inherit @}
+@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
+@@emph @@env @@file @@i @@indicateurl @@kbd @@key
+@@samp @@sansserif @@sc @@slanted @@strong @@sub @@sup
+@@t @@U @@var @@verb @@w
 @end example
 
-The above tells the web browser to use the same font as the main
-document inside @samp{<pre>} elements used for @code{@@display} environments.
-By default, the HTML @samp{<pre>} command uses a monospaced font.
+In addition, the following commands are replaced by constant text, as
+shown below.  If any of these commands have non-empty arguments, as in
+@code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
+In this table, `(space)' means a space character and `(nothing)' means
+the empty string.  The notation `U+@var{hhhh}' means Unicode code
+point @var{hhhh} (in hex, as usual).
 
-Please see the reference above for a full explanation of CSS.
+There are further transformations of many of these expansions to yield
+the final file or other target name, such as space characters to
+@samp{-}, etc., according to the other rules.
 
-You can influence the CSS in the HTML output with two
-@command{texi2any} options: @option{--css-include=@var{file}} and
-@option{--css-ref=@var{url}}.
+@multitable @columnfractions .3 .5
+@item @code{@@(newline)}        @tab (space)
+@item @code{@@(space)}          @tab (space)
+@item @code{@@(tab)}            @tab (space)
+@item @code{@@!}                @tab @samp{!}
+@item @code{@@*}                @tab (space)
+@item @code{@@-}                @tab (nothing)
+@item @code{@@.}                @tab @samp{.}
+@item @code{@@:}                @tab (nothing)
+@item @code{@@?}                @tab @samp{?}
+@item @code{@@@@}               @tab @samp{@@}
+@item @code{@@@{}               @tab @samp{@{}
+@item @code{@@@}}               @tab @samp{@}}
+@item @code{@@LaTeX}            @tab @samp{LaTeX}
+@item @code{@@TeX}              @tab @samp{TeX}
+@item @code{@@arrow}            @tab U+2192
+@item @code{@@bullet}           @tab U+2022
+@item @code{@@comma}            @tab @samp{,}
+@item @code{@@copyright}        @tab U+00A9
+@item @code{@@dots}             @tab U+2026
+@item @code{@@enddots}          @tab @samp{...}
+@item @code{@@equiv}            @tab U+2261
+@item @code{@@error}            @tab @samp{error-->}
+@item @code{@@euro}             @tab U+20AC
+@item @code{@@exclamdown}       @tab U+00A1
+@item @code{@@expansion}        @tab U+21A6
+@item @code{@@geq}              @tab U+2265
+@item @code{@@leq}              @tab U+2264
+@item @code{@@minus}            @tab U+2212
+@item @code{@@ordf}             @tab U+00AA
+@item @code{@@ordm}             @tab U+00BA
+@item @code{@@point}            @tab U+22C6
+@item @code{@@pounds}           @tab U+00A3
+@item @code{@@print}            @tab U+22A3
+@item @code{@@questiondown}     @tab U+00BF
+@item @code{@@registeredsymbol} @tab U+00AE
+@item @code{@@result}           @tab U+21D2
+@item @code{@@textdegree}       @tab U+00B0
+@item @code{@@tie}              @tab (space)
+@end multitable
 
-The option @option{--css-ref=@var{url}} adds to each output HTML file
-a @samp{<link>} tag referencing a CSS at the given @var{url}.  This
-allows using external style sheets.
+Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like),
+are likewise replaced by their Unicode values.  Normal quotation
+@emph{characters} (e.g., ASCII ` and ') are not altered.
+@xref{Inserting Quotation Marks}.
 
-The option @option{--css-include=@var{file}} includes the contents
-@var{file} in the HTML output, as you might expect.  However, the
-details are somewhat tricky, as described in the following, to provide
-maximum flexibility.
+Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and
+@code{@@image} commands are replaced by their first argument.  (For
+these commands, all subsequent arguments are optional, and ignored
+here.)  @xref{@code{@@acronym}}, and @ref{@code{@@email}}, and @ref{Images}.
 
-@cindex @samp{@@charset} specification, in CSS files
-The CSS file first line may be a @samp{@@charset} directive.  If present,
-this directive is used to determine the encoding of the CSS file.  The
-line is not copied into the output.
+Accents are handled according to the next section.
 
-@cindex @samp{@@import} specifications, in CSS files
-The CSS file may begin with so-called @samp{@@import} directives,
-which link to external CSS specifications for browsers to use when
-interpreting the document.  Again, a full description is beyond our
-scope here, but we'll describe how they work syntactically, so we can
-explain how they are handled.
+Any other command is an error, and the result is unspecified.
 
-@cindex Comments, in CSS files
-There can be more than one @samp{@@import}, but they have to come
-first in the file, with only whitespace and comments interspersed, no normal
-definitions.  Comments in CSS files are delimited by @samp{/* ... */}, as in
-C@.  An @samp{@@import} directive must be in one of these two forms:
 
-@example
-@@import url(http://example.org/foo.css);
-@@import "http://example.net/bar.css";;
-@end example
+@node HTML Xref 8-bit Character Expansion
+@subsection HTML Cross-reference 8-bit Character Expansion
+@cindex HTML cross-references @subentry 8-bit character expansion
+@cindex 8-bit characters, in HTML cross-references
+@cindex Expansion of 8-bit characters in HTML cross-references
+@cindex Transliteration of 8-bit characters in HTML cross-references
 
-The crucial characters are the @samp{@@} at the beginning and
-the semicolon terminating the directive.  When reading the CSS
-file, any such @samp{@@}-directive is simply copied into the
-output, as follows:
+Usually, characters other than plain 7-bit ASCII are transformed into
+the corresponding Unicode code point(s) in Normalization Form@tie{}C,
+which uses precomposed characters where available.  (This is the
+normalization form recommended by the W3C and other bodies.)  This
+holds when that code point is @code{0xffff} or less, as it almost
+always is.
 
-@itemize
-@item If @var{file} contains only normal CSS declarations, it is
-included after the default CSS, thus overriding it.
+These will then be further transformed by the rules above into the
+string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex.
+
+For example, combining this rule and the previous section:
 
-@item If @var{file} begins with @samp{@@import} specifications (see
-below), then the @samp{import}'s are included first (they have to come
-first, according to the standard), and then the default CSS is
-included.  If you need to override the default CSS from an
-@samp{@@import}, you can do so with the @samp{!@: important} CSS
-construct, as in:
 @example
-pre.example @{ font-size: inherit ! important @}
+@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
+@result{} A-TeX-B_0306-_22C6_002e_002e_002e
 @end example
 
-@item If @var{file} contains both @samp{@@import} and inline CSS
-specifications, the @samp{@@import}'s are included first, then
-default CSS, and lastly the inline CSS from @var{file}.
+Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
+turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
+with a breve accent, which does not exist as a pre-accented Unicode
+character, therefore expands to @samp{B_0306} (B with combining
+breve).
 
-@item Any @@-directive other than @samp{@@import} and @samp{@@charset}
-is treated as a CSS declaration, meaning the default CSS is included
-and then the rest of the file is prepended.
-@end itemize
+When the Unicode code point is above @code{0xffff}, the transformation
+is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by
+six hex digits.  Since Unicode has declared that their highest code
+point is @code{0x10ffff}, this is sufficient.  (We felt it was better
+to define this extra escape than to always use six hex digits, since
+the first two would nearly always be zeros.)
 
-If the CSS file is malformed or erroneous, the output
-is unspecified.  The meaning of the CSS file is not interpreted in
-any way; the special @samp{@@} and @samp{;} characters are looked for
-the text is blindly copied into the output.  Comments in the CSS
-file may or may not be included in the output.
+This method works fine if the node name consists mostly of ASCII
+characters and contains only few 8-bit ones.  But if the document is
+written in a language whose script is not based on the Latin alphabet
+(for example, Ukrainian), it will create file names consisting almost
+entirely of @samp{_@var{xxxx}} notations, which is inconvenient and
+all but unreadable.  To handle such cases, @command{texi2any} offers
+the @option{--transliterate-file-names} command line option.  This
+option enables @dfn{transliteration} of node names into ASCII
+characters for the purposes of file name creation and referencing.
+The transliteration is based on phonetic principles, which makes the
+generated file names more easily understandable.
 
-In the default case, classes are added to the HTML elements and CSS rules
-associated to these classes are output at the beginning of each HTML file.  Set
-the @code{NO_CSS} customization variable to prevent classes to be added and CSS
-to be used. Set @code{INLINE_CSS_STYLE} to have CSS code put in HTML
-elements in the @code{style} attribute rather than at the beginning of
-the output.
+@cindex Normalization Form C, Unicode
+For the definition of Unicode Normalization Form@tie{}C, see Unicode
+report UAX#15, @uref{http://www.unicode.org/reports/tr15/}.  Many
+related documents and implementations are available elsewhere on the
+web.
 
-Since @command{texi2any} only inserts CSS code needed by the HTML
-actually output, the full list of CSS code potentially inserted is
-not visible in the output document.  To get the full list of CSS rules, call
-@command{texi2any} with the @code{SHOW_BUILTIN_CSS_RULES} customization
-variable set to output the built-in default CSS rules on the standard output
-and exit, like:
-@example
-texi2any -c SHOW_BUILTIN_CSS_RULES=1
-@end example
 
+@node HTML Xref Mismatch
+@subsection HTML Cross-reference Mismatch
+@cindex HTML cross-references @subentry mismatch
+@cindex Mismatched HTML cross-reference source and target
 
-@node @code{@@documentdescription}
-@nodedescription Document summary for the HTML output.
-@section @code{@@documentdescription}: Summary Text
-@anchor{documentdescription}@c old name
+As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
+software may need to guess whether a given manual being cross-referenced is 
available in split or monolithic form---and, inevitably,
+it might guess wrong.  However, when the @emph{referent} manual is
+generated, it is possible to handle at least some mismatches.
 
-@cindex Document description
-@cindex Description of document
-@cindex Summary of document
-@cindex Abstract of document
-@cindex @code{<meta>} HTML tag, and document description
-@findex documentdescription
+In the case where we assume the referent is split, but it is actually
+available in mono, the only recourse would be to generate a
+@file{manual_html/} subdirectory full of HTML files which redirect back to
+the monolithic @file{manual.html}.  Since this is essentially the same
+as a split manual in the first place, it's not very appealing.
 
-When producing HTML output for a document, a @samp{<meta>} element
-is written in the @samp{<head>} to give some idea of the
-content of the document.  By default, this @dfn{description} is the
-title of the document, taken from the @code{@@settitle} command
-(@pxref{@code{@@settitle}}).  To change this, use the
-@code{@@documentdescription} environment, as in:
+On the other hand, in the case where we assume the referent is mono,
+but it is actually available in split, it is possible to use
+JavaScript to redirect from the putatively monolithic
+@file{manual.html} to the different @file{manual_html/node.html} files.
+Here's an example:
 
 @example
-@@documentdescription
-descriptive text.
-@@end documentdescription
+function redirect() @{
+  switch (location.hash) @{
+    case "#Node1":
+      location.replace("manual_html/Node1.html#Node1"); break;
+    case "#Node2" :
+      location.replace("manual_html/Node2.html#Node2"); break;
+    @dots{}
+    default:;
+  @}
+@}
 @end example
 
-@noindent
-This will produce the following output in the @samp{<head>} of the HTML:
+Then, in the @code{<body>} tag of @file{manual.html}:
 
 @example
-<meta name=description content="descriptive text.">
+<body onLoad="redirect();">
 @end example
 
+Once again, this is something the software which generated the
+@emph{referent} manual has to do in advance, it's not something the
+software generating the cross-reference in the present manual can
+control.
+
 
-@node Generating EPUB
-@nodedescription Details on the EPUB output.
-@section Generating EPUB
+@node HTML Xref Configuration
+@nodedescription @file{htmlxref.cnf}.
+@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf}
 
-@cindex EPUB, generating
-@cindex Generating EPUB
-@cindex Outputting EPUB
+@pindex htmlxref.cnf
+@cindex HTML cross-references @subentry configuration
+@cindex Cross-reference configuration, for HTML
+@cindex Configuration, for HTML cross-manual references
 
-EPUB is a format designed for reading electronic books on portable
-devices.  @command{texi2any} generated EPUB 3.2 in 2022.  An EPUB
-file is a ZIP archive container, holding informative files as
-well as the manual rendered in HTML.
+@command{texi2any} reads a file named @file{htmlxref.cnf} to gather
+information for cross-references to other manuals in HTML output.  It
+is looked for in the following directories:
 
-@cindex @code{Archive::Zip}, for EPUB file output
-@vindex EPUB_CREATE_CONTAINER_FILE @subentry @r{avoiding} @code{Archive::Zip} 
@r{dependency}
-The generation of the EPUB file depends on the @code{Archive::Zip}
-Perl module being installed.  This dependency is checked at runtime.
-In the default case, trying to output EPUB without this dependency raises an
-error.  However, if the EPUB output file is not generated, with the
-customization variable @code{EPUB_CREATE_CONTAINER_FILE} set to 0, it is
-not an error if @code{Archive::Zip} is not installed.
+@table @file
+@item ./
+(the current directory)
 
-The @command{texi2any} tests related to EPUB generation do not require the
-installation of @code{Archive::Zip}, as they set
-@code{EPUB_CREATE_CONTAINER_FILE} to 0 and keep the directory containing
-the files and directories needed for the EPUB file by setting the
-@code{EPUB_KEEP_CONTAINER_FOLDER} customization variable to 1.
+@item ./.texinfo/
+(under the current directory)
 
+@item ~/.texinfo/
+(where @code{~} is the current user's home directory)
 
-@node EPUB Output File and Directory
-@nodedescription Use syntax highlighting in code excerpts.
-@subsection Container Directory and Output Files
+@item @var{sysconfdir}/texinfo/
+(where @var{sysconfdir} is the system configuration directory
+specified at compile-time, e.g., @file{/usr/local/etc})
 
-@cindex Container directory for EPUB
-@cindex EPUB Container directory
-A directory containing the files and directories needed for the
-EPUB format is created when outputting EPUB@.  The name of this
-container directory is derived from the base name of the input file (that
-is, any extension is removed), with @code{_epub_package} postpended.
-If an output directory is specified, with @option{--output},
-or with the @code{SUBDIR} customization variable,
-the container directory is created in that directory instead of
-the current directory.  At the beginning of a new run, the container
-directory and all its contents are removed.  The container directory
-is also removed after the final EPUB file has been generated in the
-default case.
+@item @var{datadir}/texinfo/
+(likewise specified at compile time, e.g., @file{/usr/local/share})
+@end table
 
-The HTML files produced from the Texinfo manual are output in subdirectories
-of the container directory.  Image files referred to from the Texinfo manual,
-if found, are copied to subdirectories of the container directory.
+All files found are used, with earlier entries overriding later ones.
+The Texinfo distribution includes a default file which handles many
+GNU manuals; it is installed in the last of the above directories,
+i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}.
 
-@cindex EPUB output file
-The EPUB output file is a ZIP archive of the container directory.
-The file name is derived from the base name, with the @code{.epub}
-extension postpended.  If an output file is specified, with
-@option{--output}, or with the @code{OUTFILE} customization function,
-this file name is used instead.  The output EPUB file is never placed
-in the directory specified by @option{--output} or @code{SUBDIR};
-only the container directory is placed there, as explained just above.
+The @code{HTMLXREF_MODE} customization variable can be set to modify how the
+files are found.  For instance, if set to @samp{none}, no external information
+is used.  @code{HTMLXREF_FILE} sets the file name to something else than
+@file{htmlxref.cnf}.  @pxref{HTML Customization Variables List}.
 
-The EPUB output file is not generated if the customization variable
-@code{EPUB_CREATE_CONTAINER_FILE} is set to 0.  The container directory
-is left after the final EPUB file has been generated if
-@code{EPUB_KEEP_CONTAINER_FOLDER} is set.
+The file is line-oriented.  Lines consisting only of whitespace are
+ignored.  Comments are indicated with a @samp{#} at the beginning of a
+line, optionally preceded by whitespace.  Since @samp{#} can occur in
+URLs (like almost any character), it does not otherwise start a
+comment.
 
-@xref{Invoking @command{texi2any}}.
+Each non-blank non-comment line must be either a @dfn{variable
+assignment} or @dfn{manual information}.
 
+A variable assignment line looks like this:
 
-@node EPUB Cross-References
-@nodedescription Cross-references in HTML output.
-@subsection EPUB Cross-References
+@example
+@var{varname} = @var{varvalue}
+@end example
 
-The EPUB format does not support references from an EPUB file to
-another EPUB file.  Therefore any references to ``external'' Texinfo
-manuals should resolve to an external URL@:.  @command{texi2any}
-produces these links with HTML cross-reference configuration
-(@pxref{HTML Xref Configuration}).  Since the links in the
-resulting EPUB are incorrect if no information is found for the
-cross-references, @command{texi2any} issues a warning by default for
-missing cross-references information.  If these warnings are unwanted,
-set @code{CHECK_HTMLXREF} to 0.
+Whitespace around the @samp{=} is optional and ignored.  The
+@var{varname} should consist of letters; case is significant.  The
+@var{varvalue} is an arbitrary string, continuing to the end of the
+line.  Variables are then referenced with @samp{$@{@var{varname}@}};
+variable references can occur in the @var{varvalue}.
 
+A manual information line looks like this:
 
-@node EPUB HTML
-@subsection HTML Generated for EPUB
+@example
+@var{manual} @var{keyword} @var{urlprefix}
+@end example
 
-The HTML generated for EPUB is XHTML conformant, UTF-8 encoded, and
-formatted without the usual HTML navigation headers and footers.
-Most of these features are enabled with customization variables, such as
-@code{USE_XML_SYNTAX} or @code{OUTPUT_FILE_NAME_ENCODING}.  Some
-features of printed output are used in EPUB@.  In particular, the Top
-node does not appear in the EPUB output, while a title page is
-generated.  This is obtained by setting @code{NO_TOP_NODE_OUTPUT}.
+@noindent
+with @var{manual} the short identifier for a manual, @var{keyword}
+being one of: @code{mono}, @code{node}, @code{section},
+@code{chapter}, and @var{urlprefix} described below.  Variable
+references can occur only in the @var{urlprefix}.  For example (used
+in the canonical @file{htmlxref.cnf}):
 
-The @code{OUTFILE} and @code{SUBDIR} customization variables values
-correspond initially to the EPUB directory container and/or the
-EPUB output file (@pxref{EPUB Output File and Directory}).  These
-customization variables values are undefined or reset to the
-locations in the container directory where the XHTML files are output
-for the HTML generation.  It is mentioned here because resetting
-customization variables is unusual; however, the variables reset are
-used internally for the conversion, and should not interact with any
-customization set by the user.
+@example
+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/
+@end example
 
-@xref{HTML Customization Variables List}.
+@cindex monolithic manuals, for HTML cross-references
+If the keyword is @code{mono}, @var{urlprefix} gives the host,
+directory, and file name for @var{manual} as one monolithic file.
+
+@cindex split manuals, for HTML cross-references
+If the keyword is @code{node}, @code{section}, or @code{chapter},
+@var{urlprefix} gives the host and directory for @var{manual} split
+into nodes, sections, or chapters, respectively.
 
+When available, @command{texi2any} will use the ``corresponding''
+value for cross-references between manuals.  That is, when generating
+monolithic output (@option{--no-split}), the @code{mono} URL will be
+used, when generating output that is split by node, the @code{node}
+URL will be used, etc.  However, if a manual is not available in that
+form, anything that is available can be used.  Here is the search
+order for each style:
 
-@node Syntax Highlighting
-@section Code Examples Syntax Highlighting in HTML
-@cindex @command{source-highlight}
+@example
+node    @result{} node,    section, chapter, mono
+section @result{} section, chapter, node,    mono
+chapter @result{} chapter, section, node,    mono
+mono    @result{} mono,    chapter, section, node
+@end example
 
-@cartouche
-@quotation warning
-Source highlighting is experimental, feedback is welcomed.
-@end quotation
-@end cartouche
+@opindex --node-files@r{, and HTML cross-references}
+These section- and chapter-level cross-manual references can succeed
+only when the target manual was created using @option{--node-files};
+this is the default for split output.
 
-Support for source code syntax highlighting is available in
-@command{texi2any} for the HTML output, with the help of external software.
-This feature is turned on by setting @code{HIGHLIGHT_SYNTAX}.  Source code
-highlighting is set up for @code{@@example} blocks.  The language
-specified for syntax highlighting is the first argument on the 
@code{@@example} line
-(@pxref{@code{@@example}}), or @code{HIGHLIGHT_SYNTAX_DEFAULT_LANGUAGE} if set
-and there is no first argument.
+If you have additions or corrections to the @file{htmlxref.cnf}
+distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
+usual.  You can get the latest version from
+@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
 
-The @code{HIGHLIGHT_SYNTAX} value determines the command used for highlighting:
-@table @code
-@item highlight
-Use @command{highlight} from
-@url{http://www.andre-simon.de/doku/highlight/en/highlight.php};
-@item pygments
-Use @command{pygmentize} from @url{https://pygments.org/};
-@item anything else
-Use @command{source-highlight} (@pxref{,,,source-highlight, GNU 
Source-highlight}).
-@end table
 
-@xref{Other Customization Variables}.
+@node HTML Output Advanced Customization
+@section HTML Output Advanced Customization
 
+Many user-definable customization variables can influence
+the HTML output.  @xref{HTML Customization Variables List} for the full list.
+The possibility offered by the customization variables, ranging from
+overall document structure and type for HTML language used to specific
+constructs formatting should cover most needs not already satisfied
+by CSS customization (@pxref{HTML CSS}).  If more control is ever needed,
+it needs to be achieved through the use of initialization files and
+is described in a separate manual (@pxref{,,, texi2any_api, GNU
+Texinfo @command{texi2any} Output Customization}).
 
-@node HTML Xref
-@section HTML Cross-references
-@cindex HTML cross-references
-@cindex Cross-references, in HTML output
+@node HTML Output Structure Customization
+@subsection HTML Output Structure Customization
 
-Cross-references between Texinfo manuals in HTML format become standard
-HTML @code{<a>} links.  This section describes the algorithm used,
-so that Texinfo can cooperate with other programs, such as
-@command{texi2html}, by writing mutually compatible HTML files.
+In the default case, the HTML output is tailored for online viewing with
+a direct access to the information at the Top node.  For an output more
+similar to a book, set @code{NO_TOP_NODE_OUTPUT} to remove the Top node.
+If @code{SHOW_TITLE} is @samp{undef}, the default,
+setting @code{NO_TOP_NODE_OUTPUT} also sets @code{SHOW_TITLE} to
+output a title at the beginning of the document.  In the default case
+the full @code{@@titlepage} is used for the title, unset
+@code{USE_TITLEPAGE_FOR_TITLE} to get a simple title string.
+If @code{SHOW_TITLE} is set, it is possible to output the table of contents
+at the end of the title by setting @code{CONTENTS_OUTPUT_LOCATION} to
+@samp{after_title}.
 
-This algorithm may or may not be used for links @emph{within} HTML
-output for a Texinfo file.  Since no issues of compatibility arise in
-such cases, we do not need to specify this.
+In the default case, a list of subordinate sections is output in each node
+for navigation, corresponding to @code{FORMAT_MENU} set to @samp{sectiontoc}.
+The table of contents are output at the end of the @code{@@top}
+section, to have the main location for navigation in the whole document
+early on, corresponding to @code{CONTENTS_OUTPUT_LOCATION} set to
+samp @code{after_top}.  To use menus instead to navigate in the document
+(@pxref{Menus}), set @code{FORMAT_MENU} to @samp{menu}.
 
-We try to support references to such ``external'' manuals in both
-monolithic and split forms.  A @dfn{monolithic} (mono) manual is
-entirely contained in one file, and a @dfn{split} manual has a file
-for each node.  (@xref{HTML Splitting}.)
+If menus are used for navigation, the tables of contents are not
+needed at the end of the @code{@@top} section as
+there should already be a master menu (@pxref{Master Menu Parts}).
+To output the table of contents at the end of the document or to a separate
+file, if output is split, set @code{CONTENTS_OUTPUT_LOCATION}
+to @samp{separate_element}.  It is also possible to set
+@code{CONTENTS_OUTPUT_LOCATION} to @samp{inline}, in that case the
+the tables of content are output where
+the corresponding @@-command, for example @code{@@contents}, is set.
 
-@cindex Dumas, Patrice
-The algorithm was primarily devised by Patrice Dumas in 2003--04.
+A special @dfn{About} element explaining how to navigate can be added by
+setting @code{DO_ABOUT}, set to 0 in the default case (no About element).
 
-@menu
-* Link Basics:       HTML Xref Link Basics.
-* Node Expansion:    HTML Xref Node Name Expansion.
-* Command Expansion: HTML Xref Command Expansion.
-* 8-bit Expansion:   HTML Xref 8-bit Character Expansion.
-* Mismatch:          HTML Xref Mismatch.
-* Configuration:     HTML Xref Configuration.
-@end menu
+If non-split, in the default case, the special elements such as the About
+element or the tables of contents are output in the same file as the
+manual nodes and sections.  If you prefer such special elements to be separate,
+set @code{MONOLITHIC} to 0 to output special elements to separate files.  As
+already described, the table of contents location may also be tuned with
+@code{CONTENTS_OUTPUT_LOCATION}.
 
+An experimental JavaScript browsing interface to the manual can be added, by
+setting @code{INFO_JS_DIR} value to the directory to place the code for this
+interface as e.g.@: @samp{texi2any --html -c INFO_JS_DIR=js @var{manual}.texi}
+to place files in a @samp{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.
 
-@node HTML Xref Link Basics
-@subsection HTML Cross-reference Link Basics
-@cindex HTML cross-references @subentry link basics
+@anchor{JavaScript license web labels}
+@cindex JavaScript license web labels page
+@vindex JS_WEBLABELS
+@vindex JS_WEBLABELS_FILE
+In the default case, a @dfn{JavaScript license web labels page} is setup
+to give licensing information and source code for any JavaScript used in
+the HTML files for the manual
+(See @uref{https://www.gnu.org/licenses/javascript-labels.html}).  To avoid
+generating a JavaScript license web labels page, set @code{JS_WEBLABELS}
+to @samp{omit}.  With @code{JS_WEBLABELS} set to @samp{generate}, the default,
+generate a labels page at @code{JS_WEBLABELS_FILE}, @file{js_licenses.html}
+in the default case, and link to it in the HTML output files.  With
+@code{JS_WEBLABELS} set to @samp{reference}, link to the labels file given by
+@code{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.
+Labels files are generated for @code{INFO_JS_DIR} and with @code{HTML_MATH}
+set to @samp{mathjax} (@pxref{MathJax scripts}).
 
-For our purposes, an HTML link consists of four components: a host
-name, a directory part, a file part, and a target part.  We
-always assume the @code{http} protocol.  For example:
+The @code{@@node} @@-commands are usually followed by a sectioning command,
+which provides a heading for the node.  In the default case, a node not
+associated to a sectioning command but followed by a command like
+@code{@@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
+@code{USE_NEXT_HEADING_FOR_LONE_NODE} to 0.
 
-@example
-http://@var{host}/@var{dir}/@var{file}.html#@var{target}
-@end example
 
-The information to construct a link comes from the node name and
-manual name in the cross-reference command in the Texinfo source
-(@pxref{Cross References}), and from @dfn{external information}
-(@pxref{HTML Xref Configuration}).
+@node File Names and Links Customization for HTML
+@subsection File Names and Links Customization for HTML
 
-We now consider each part in turn.
+@c file names
 
-The @var{host} is hardwired to be the local host.  This could either
-be the literal string @samp{localhost}, or, according to the rules for
-HTML links, the @samp{http://localhost/} could be omitted entirely.
+@vindex PREFIX
+@vindex SUBDIR
+@vindex EXTENSION
+It is possible to specify the output file names with more control than
+merely the command line option @option{--output} (@pxref{Invoking
+@command{texi2any}}). The @code{PREFIX} customization
+variable overrides the base name of the file given by @code{@@setfilename} or
+the file name and should not contain any directory components.  To alter
+intermediate directories, use the @code{SUBDIR} customization variable.
+Finally, the extension may also be overriden by the customization variable
+@code{EXTENSION}.  This variable should be @code{undef} if no extension is to
+be added.  If @code{CASE_INSENSITIVE_FILENAMES} is set, 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.
 
-The @var{dir} and @var{file} parts are more complicated, and depend on
-the relative split/mono nature of both the manual being processed and
-the manual that the cross-reference refers to.  The underlying idea is
-that there is one directory for Texinfo manuals in HTML, and a given
-@var{manual} is either available as a monolithic file
-@file{@var{manual}.html}, or a split subdirectory
-@file{@var{manual}_html/*.html}.  Here are the cases:
+@vindex TOP_FILE
+Furthermore, the customization variables @code{TOP_FILE} override
+the output file name for the top element.  This is, in general,
+only taken into account when output is split.
 
-@itemize @bullet
-@item
-If the present manual is split, and the referent manual is also split,
-the directory is @samp{../@var{referent}_html/} and the file is the
-expanded node name (described later).
+If @code{USE_ACCESSKEY} is set, the default, the @code{accesskey} attribute
+is used in navigation.  Keyboards shortcuts are set for selected directions
+only, with @kbd{n} for links to next node or section, @kbd{p} for links to
+previous previous node or section and @kbd{u} for up directions links.
+Similarly, if the @code{USE_REL_REV} customization variable is set, the
+default, the @code{rel} attribute is used in navigation to define the
+relationship between the current page and the linked resource.  For example,
+the @samp{contents} @code{rel} attribute is set for a link to the table of
+contents, the @samp{next} @code{rel} attribute is set for a link to the next
+node or section.
 
-@item
-If the present manual is split, and the referent manual is mono, the
-directory is @samp{../} and the file is @file{@var{referent}.html}.
+@c internal links
 
-@item
-If the present manual is mono, and the referent manual is split, the
-directory is @file{@var{referent}_html/} and the file is the expanded node
-name.
+Internal links customization is specific of link type:
+@table @emph
+@item cross-reference command link
+@vindex XREF_USE_NODE_NAME_ARG
+If the second argument of a cross-reference command is set, it is displayed
+as hyperlink text (@pxref{Two Arguments}).  Otherwise the
+@code{XREF_USE_NODE_NAME_ARG} customization variable is used to determine the
+hyperlink text.  If set to@tie{}1, use the node name (first) argument in
+cross-reference @@-commands for the text displayed as the hyperlink.  If set
+to@tie{}0, use the node name if @code{USE_NODES} is set, otherwise the section
+name.  If set to @samp{undef}, use the first argument in preformatted
+environments, otherwise use the node name or section name depending on
+@code{USE_NODES}.  The default is @samp{undef}.
 
-@item
-If the present manual is mono, and the referent manual is also mono,
-the directory is @file{./} (or just the empty string), and the file is
-@file{@var{referent}.html}.
+@item link to float
+@vindex XREF_USE_FLOAT_LABEL
+If @code{XREF_USE_FLOAT_LABEL} is set (default is off), use the float label
+instead of the type followed by the float number (@pxref{@code{@@float}}).
 
-@end itemize
+@item link to index entries root commands
+@vindex NODE_NAME_IN_INDEX
+In @code{@@printindex} formatting, two links are output, a link to the index
+entry and a link to the root @@-command containing the index entry.
+The @code{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 prefer section names.  If undefined, use
+@code{USE_NODES} value to determine which root @@-command to prefer.
+Default is undefined.
 
-Another rule, that only holds for file names, is that base file names
-are truncated to 245 characters, to allow for an extension to be
-appended and still comply with the 255-character limit which is common
-to many filesystems.  Although technically this can be changed with
-the @code{BASEFILENAME_LENGTH} customization variable (@pxref{Other
-Customization Variables}), doing so would make cross-manual references
-to such nodes invalid.
+@item menu links
+@vindex NODE_NAME_IN_MENU
+In the default case, node names are used in menu entries links.  Set
+@code{NODE_NAME_IN_MENU} to false to use section names instead.
 
-Any directory part in the file name argument of the source cross
-reference command is ignored.  Thus, @code{@@xref@{,,,../foo@}} and
-@code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name.  This
-is because any such attempted hardwiring of the directory is very
-unlikely to be useful for all the output formats that use the manual
-name.
+@item Table of contents links
+@vindex SHORT_TOC_LINK_TO_TOC
+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
+@code{SHORT_TOC_LINK_TO_TOC} to 0 to link to the sectioning commands instead.
 
-Finally, the @var{target} part is always the expanded node name.
+@vindex TOC_LINKS
+If @code{TOC_LINKS} if set, links from headings to toc entries are created;
+default false.
 
-Whether the present manual is split or mono is determined by user
-option; @command{texi2any} defaults to split, with the
-@option{--no-split} option overriding this.
+@item Top node up direction link
+@vindex IGNORE_REF_TO_TOP_NODE_UP
+In the default case, no Top node Up reference is generated.  It is possible
+to ignore references to the Top node Up appearing in other cross-references
+by setting @code{IGNORE_REF_TO_TOP_NODE_UP}.  @code{IGNORE_REF_TO_TOP_NODE_UP}
+is not set in the default case.
 
-Whether the referent manual is split or mono, however, is another bit
-of the external information (@pxref{HTML Xref Configuration}).  By
-default, @command{texi2any} uses the same form of the referent manual
-as the present manual.
+@vindex TOP_NODE_UP_URL
+@vindex 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
+@code{TOP_NODE_UP_URL} to the URL used for Top node up references.
+If @code{TOP_NODE_UP_URL} is set, the @code{TOP_NODE_UP} customization
+variable value is used for the hyperlink text, with @samp{(dir)} as default.
 
-Thus, there can be a mismatch between the format of the referent
-manual that the generating software assumes, and the format it's
-actually present in.  @xref{HTML Xref Mismatch}.
+For example, for GNU @url{http://www.gnu.org/manual/} collects
+links to most GNU manuals, therefore @code{TOP_NODE_UP_URL} is
+best  specified as  @code{/manual/} if the manual
+will be installed on @code{www.gnu.org}.
 
+@xref{First Node} for more about the Top node pointers.
 
-@node HTML Xref Node Name Expansion
-@subsection HTML Cross-reference Node Name Expansion
-@cindex HTML cross-references @subentry node name expansion
-@cindex node name expansion, in HTML cross-references
-@cindex expansion, of node names in HTML cross-references
+@item images links
+@vindex IMAGE_LINK_PREFIX
+If @code{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.
+@end table
 
-As mentioned in the previous section, the key part of the HTML cross
-reference algorithm is the conversion of node names in the Texinfo
-source into strings suitable for XHTML identifiers and file names.  The
-restrictions are similar for each: plain ASCII letters, numbers, and
-the @samp{-} and @samp{_} characters are all that can be used.
-(Although HTML anchors can contain most characters, XHTML is more
-restrictive.)
+@c Cross references
 
-Cross-references in Texinfo can refer either to nodes, anchors
-(@pxref{@code{@@anchor}}) or float labels (@pxref{@code{@@float}}).
-However, anchors and float labels are treated identically
-to nodes in this context, so we'll continue to say ``node'' names for
-simplicity.
+Cross-references between HTML manuals are specified precisely
+(@pxref{HTML Xref}).  Customization of manual locations is already provided
+through the @file{htmlxref.cnf} file (@pxref{HTML Xref Configuration}).
 
-A special exception: the Top node (@pxref{The Top Node}) is always
-mapped to the file @file{index.html}, to match web server software.
-However, the HTML @emph{target} is @samp{Top}.  Thus (in the split case):
+@vindex CHECK_HTMLXREF
+Defaults are used for cross-reference target manual not
+found through HTML Xref Configuration (@pxref{HTML Xref Link Basics}).  If
+you want to add all the manuals referred to to an HTML Xref configuration file,
+set @code{CHECK_HTMLXREF} to get a message for each external manual not in the
+HTML Xref configuration files.  This could be relevant, for example, if you
+know that no manual is installed locally.
 
-@example
-@@xref@{Top,,, emacs, The GNU Emacs Manual@}.
-@result{} <a href="../emacs_html/index.html#Top">
-@end example
+@vindex HTMLXREF_MODE
+@vindex HTMLXREF_FILE
+@vindex EXTERNAL_CROSSREF_SPLIT
+Customization variables can specify more precisely the HTML Xref Configuration.
+In the default case, the file name used for HTML Xref configuration
+is searched for in directories, and all the files found are used.
+The @code{HTMLXREF_MODE} customization variable can be set to modify how
+cross-references to other manuals information is determined.
+If @code{HTMLXREF_MODE} is set to @samp{file}, the file name is directly used
+as the source of information.  If @code{HTMLXREF_MODE} is set to @samp{none}
+no information is used.  The default case is obtained with @code{HTMLXREF_MODE}
+not defined or set to any other value.  The @code{HTMLXREF_FILE} customization
+variable sets the file used for HTML Xref configuration to another value than
+the default, @file{htmlxref.cnf}.  In the default case, the distant manual
+is considered to be split or monolithic based on the splitting of the manual
+being output.  It is possible to set it explicitely, instead, with
+@code{EXTERNAL_CROSSREF_SPLIT}.
 
-@enumerate
-@item
-The standard ASCII letters (a-z and A-Z) are not modified.  All other
-characters may be changed as specified below.
+It also is possible to set customization variables to modify how
+cross-references are output in various other ways.  In general, this 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 produced using
+corresponding customization.  It is therefore, in general, better to use HTML
+Xref Configuration only.
 
-@item
-The standard ASCII numbers (0-9) are not modified except when a number
-is the first character of the node name.  In that case, see below.
+The file name used for the Top node in cross-references is set to
+the @code{TOP_NODE_FILE_TARGET} customization variable value; default is
+@file{index.html}.  A base directory for external manuals is specified
+with @code{EXTERNAL_DIR}, in the default case there is none.  Similarly,
+the file extension for cross-references to other manuals is set with
+@code{EXTERNAL_CROSSREF_EXTENSION}, which, if unset, is based
+on @code{EXTENSION}.  In the default case, the base file names are truncated
+to 245 characters (@pxref{HTML Xref Link Basics}).  The maximum length of a
+base file name is changed by setting @code{BASEFILENAME_LENGTH}.
 
-@item
-Multiple consecutive space, tab and newline characters are transformed
-into just one space.
 
-@item
-Leading and trailing spaces are removed.
+@node Customization of Navigation and Headers
+@subsection Customization of Navigation and Headers
 
-@item
-After the above has been applied, each remaining space character is
-converted into a @samp{-} character.
+Headers with a navigation panel are output in the default case.  if
+@option{--no-headers} is used or the customization variable @code{HEADERS}
+is unset, the navigation bar is only inserted at the beginning of
+split files.
 
-@item
-Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
-where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
-This includes @samp{_}, which is mapped to @samp{_005f}.
+In the default case, @code{<link>} elements are generated in the
+HTML @code{<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 @code{USE_LINKS} to avoid those elements.
 
-@item
-If the node name does not begin with a letter, the literal string
-@samp{g_t} is prefixed to the result.  (Due to the rules above, that
-string can never occur otherwise; it is an arbitrary choice, standing
-for ``GNU Texinfo''.)  This is necessary because XHTML requires that
-identifiers begin with a letter.
+The @code{<title>} and the document description in @code{<head>}
+are based on @code{@@settitle} (@pxref{@code{@@settitle}}).
+If the manual is split, the node name is also added to this HTML title.
+If @code{SECTION_NAME_IN_TITLE} is set, the argument of the associated
+chapter structuring command is used instead of the node name.
 
-@end enumerate
+When output is split at nodes (@pxref{HTML Splitting}), the
+@code{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.
 
-For example:
+The appearance of the navigation panel is affected by the following
+customization variables, false in the default case:
 
-@example
-@@node A  node --- with _'%
-@result{} A-node-_002d_002d_002d-with-_005f_0027_0025
-@end example
+@vtable @code
+@item DATE_IN_HEADER
+Put the document generation date in the header.
 
-Example translations of common characters:
+@item HEADER_IN_TABLE
+Use tables for header formatting rather than a simple @samp{<div>}.
 
-@itemize @bullet
-@item @samp{_} @result{} @samp{_005f}
-@item @samp{-} @result{} @samp{_002d}
-@item @samp{A  node} @result{} @samp{A-node}
-@end itemize
+@item ICONS
+Use icons for the navigation panel.
 
-On case-folding computer systems, nodes differing only by case will be
-mapped to the same file.  In particular, as mentioned above, Top
-always maps to the file @file{index.html}.  Thus, on a case-folding
-system, Top and a node named `Index' will both be written to
-@file{index.html}.  Fortunately, the targets serve to distinguish
-these cases, since HTML target names are always case-sensitive,
-independent of operating system.
+@item PROGRAM_NAME_IN_FOOTER
+If set, output the program name and miscellaneous related information in the
+page footers.
 
+@item VERTICAL_HEAD_NAVIGATION
+If set, a vertical navigation panel is used.
+@end vtable
 
-@node HTML Xref Command Expansion
-@subsection HTML Cross-reference Command Expansion
-@cindex HTML cross-references @subentry command expansion
+Setting @code{ICONS} is necessary but not sufficient to get icons for direction
+buttons since no button image is specified in the default case.
+The @code{ACTIVE_ICONS} and @code{PASSIVE_ICONS} customization
+variables need to be set in addition.  This requires using an
+initialization file (@pxref{Invoking @command{texi2any}}).
+@xref{,,, texi2any_api, GNU Texinfo @command{texi2any} Output Customization}.
 
-Node names may contain @@-commands (@pxref{Node Line Requirements}).
-This section describes how they are handled.
 
-First, comments are removed.
+@node General Customization of HTML Code
+@subsection General Customization of HTML Code
 
-Next, any @code{@@value} commands (@pxref{@code{@@set @@value}}) and
-macro invocations (@pxref{Invoking Macros}) are fully expanded.
+The generated HTML code may be modified in two way.  Firstly by specifying
+broad features of the generated HTML and secondly by inserting
+some HTML code in a few specific places.
 
-Then, for the following commands, the command name and braces are removed,
-and the text of the argument is recursively transformed:
+In the default case, HTML is generated, but it is also possible to
+generate XML compatible code, by setting @code{USE_XML_SYNTAX}.  The main
+difference is that @samp{/>} instead of @samp{>} closes elements with an
+opening element, but no closing element, such as @code{<img>} or @code{<link>}
+(also called @dfn{void elements}).
+To set the @dfn{DOCTYPE}, set the @code{DOCTYPE} customization variable.
+The default is the HTML5 DTD-less simple DOCTYPE.
 
-@example
-@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
-@@emph @@env @@file @@i @@indicateurl @@kbd @@key
-@@samp @@sansserif @@sc @@slanted @@strong @@sub @@sup
-@@t @@U @@var @@verb @@w
-@end example
+In the default case, entities are used for doubled single-quote characters
+(@pxref{Inserting Quotation Marks}), and @samp{---} and @samp{--}
+(@pxref{Conventions}).  Set @code{USE_ISO} to @samp{0} in the unlikely case
+that you want a simpler formatting.
+In the default case, textual entities are used when possible.  Set
+@code{USE_NUMERIC_ENTITY} to use numeric entities only.
+Set @code{OUTPUT_CHARACTERS} to output accented characters based on
+the output encoding instead of entities.
 
-In addition, the following commands are replaced by constant text, as
-shown below.  If any of these commands have non-empty arguments, as in
-@code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
-In this table, `(space)' means a space character and `(nothing)' means
-the empty string.  The notation `U+@var{hhhh}' means Unicode code
-point @var{hhhh} (in hex, as usual).
+In the default case, 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, it is
+possible to set @code{NO_CUSTOM_HTML_ATTRIBUTE} to prevent custom attributes to
+be output.
 
-There are further transformations of many of these expansions to yield
-the final file or other target name, such as space characters to
-@samp{-}, etc., according to the other rules.
+To change the HTML code for breaks (horizontal rule) inserted in various
+contexts, set @code{DEFAULT_RULE},
+used for most horizontal separators output in the resulting HTML,
+and set @code{BIG_RULE} for the wider separator sometime used.
 
-@multitable @columnfractions .3 .5
-@item @code{@@(newline)}        @tab (space)
-@item @code{@@(space)}          @tab (space)
-@item @code{@@(tab)}            @tab (space)
-@item @code{@@!}                @tab @samp{!}
-@item @code{@@*}                @tab (space)
-@item @code{@@-}                @tab (nothing)
-@item @code{@@.}                @tab @samp{.}
-@item @code{@@:}                @tab (nothing)
-@item @code{@@?}                @tab @samp{?}
-@item @code{@@@@}               @tab @samp{@@}
-@item @code{@@@{}               @tab @samp{@{}
-@item @code{@@@}}               @tab @samp{@}}
-@item @code{@@LaTeX}            @tab @samp{LaTeX}
-@item @code{@@TeX}              @tab @samp{TeX}
-@item @code{@@arrow}            @tab U+2192
-@item @code{@@bullet}           @tab U+2022
-@item @code{@@comma}            @tab @samp{,}
-@item @code{@@copyright}        @tab U+00A9
-@item @code{@@dots}             @tab U+2026
-@item @code{@@enddots}          @tab @samp{...}
-@item @code{@@equiv}            @tab U+2261
-@item @code{@@error}            @tab @samp{error-->}
-@item @code{@@euro}             @tab U+20AC
-@item @code{@@exclamdown}       @tab U+00A1
-@item @code{@@expansion}        @tab U+21A6
-@item @code{@@geq}              @tab U+2265
-@item @code{@@leq}              @tab U+2264
-@item @code{@@minus}            @tab U+2212
-@item @code{@@ordf}             @tab U+00AA
-@item @code{@@ordm}             @tab U+00BA
-@item @code{@@point}            @tab U+22C6
-@item @code{@@pounds}           @tab U+00A3
-@item @code{@@print}            @tab U+22A3
-@item @code{@@questiondown}     @tab U+00BF
-@item @code{@@registeredsymbol} @tab U+00AE
-@item @code{@@result}           @tab U+21D2
-@item @code{@@textdegree}       @tab U+00B0
-@item @code{@@tie}              @tab (space)
-@end multitable
+Copiable links are output for link targets for the definition commands
+(@pxref{Definition Commands}), table commands (@pxref{Two-column
+Tables}) where an index entry is defined and headings.  A link appears
+as a `@U{00B6}'
+@c pilcrow sign
+sign that appears when you hover the mouse pointer over the heading text.
+Unset @code{COPIABLE_LINKS} to prevent copiable links output.
 
-Quotation mark @@-commands (@code{@@quotedblright@{@}} and the like),
-are likewise replaced by their Unicode values.  Normal quotation
-@emph{characters} (e.g., ASCII ` and ') are not altered.
-@xref{Inserting Quotation Marks}.
+@c Arguments are HTML content to be inserted at certain points in the output.
 
-Any @code{@@acronym}, @code{@@abbr}, @code{@@email}, and
-@code{@@image} commands are replaced by their first argument.  (For
-these commands, all subsequent arguments are optional, and ignored
-here.)  @xref{@code{@@acronym}}, and @ref{@code{@@email}}, and @ref{Images}.
+@vindex HTML_ROOT_ELEMENT_ATTRIBUTES
+@vindex EXTRA_HEAD
+@vindex AFTER_BODY_OPEN
+@cindex @code{<head>} block, adding to
+@vindex BODYTEXT
+You can set @code{HTML_ROOT_ELEMENT_ATTRIBUTES} to add attributes to
+the @code{<html>} element.
+You can define the variable @code{EXTRA_HEAD} to add text within the
+@code{<head>} HTML element.  Similarly, the value of
+@code{AFTER_BODY_OPEN} is added just after @code{<body>} is output.
+These variables are empty by default.
+@cindex @code{<body>} tag, attributes of
+The @code{<body>} element attributes may be set by defining the
+customization variable @code{BODYTEXT}.
 
-Accents are handled according to the next section.
+@vindex PRE_BODY_CLOSE
+You can define the variable @code{PRE_BODY_CLOSE} to add text just
+before the HTML @code{</body>} element.  Nothing is added by default.
 
-Any other command is an error, and the result is unspecified.
+Similarly, the following variables allow for some useful control of the
+formatting of table of contents and short table of contents:
 
+@vtable @code
+@item BEFORE_TOC_LINES
+Inserted before the table of contents text.
 
-@node HTML Xref 8-bit Character Expansion
-@subsection HTML Cross-reference 8-bit Character Expansion
-@cindex HTML cross-references @subentry 8-bit character expansion
-@cindex 8-bit characters, in HTML cross-references
-@cindex Expansion of 8-bit characters in HTML cross-references
-@cindex Transliteration of 8-bit characters in HTML cross-references
+@item AFTER_TOC_LINES
+Inserted after the table of contents text.
 
-Usually, characters other than plain 7-bit ASCII are transformed into
-the corresponding Unicode code point(s) in Normalization Form@tie{}C,
-which uses precomposed characters where available.  (This is the
-normalization form recommended by the W3C and other bodies.)  This
-holds when that code point is @code{0xffff} or less, as it almost
-always is.
+@item BEFORE_SHORT_TOC_LINES
+Inserted before the short table of contents text.
 
-These will then be further transformed by the rules above into the
-string @samp{_@var{hhhh}}, where @var{hhhh} is the code point in hex.
+@item AFTER_SHORT_TOC_LINES
+Inserted after the short table of contents text.
 
-For example, combining this rule and the previous section:
+@end vtable
+At the time of writing, these variables default values are set to
+@code{<div>} elements opening and closing for tables of contents.
 
+@ignore
+Could be an example, but would need either to specify as command-line
+arguments, which would be cumbersome, or requires knowing about init
+files
+@c output valid XHTML XML 1.0 Document
 @example
-@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
-@result{} A-TeX-B_0306-_22C6_002e_002e_002e
+texinfo_set_from_init_file('HTML_ROOT_ELEMENT_ATTRIBUTES',
+                           'xmlns="http://www.w3.org/1999/xhtml";');
+texinfo_set_from_init_file('NO_CUSTOM_HTML_ATTRIBUTE', 1);
+texinfo_set_from_init_file('USE_XML_SYNTAX', 1);
+texinfo_set_from_init_file('DOCTYPE', '<?xml version="1.0" 
encoding="UTF-8"?>'."\n"
+                                      .'<!DOCTYPE html>');
+texinfo_set_from_init_file('USE_NUMERIC_ENTITY', 1);
+texinfo_set_from_init_file('OUTPUT_ENCODING_NAME', 'utf-8');
 @end example
 
-Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
-turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
-with a breve accent, which does not exist as a pre-accented Unicode
-character, therefore expands to @samp{B_0306} (B with combining
-breve).
-
-When the Unicode code point is above @code{0xffff}, the transformation
-is @samp{__@var{xxxxxx}}, that is, two leading underscores followed by
-six hex digits.  Since Unicode has declared that their highest code
-point is @code{0x10ffff}, this is sufficient.  (We felt it was better
-to define this extra escape than to always use six hex digits, since
-the first two would nearly always be zeros.)
-
-This method works fine if the node name consists mostly of ASCII
-characters and contains only few 8-bit ones.  But if the document is
-written in a language whose script is not based on the Latin alphabet
-(for example, Ukrainian), it will create file names consisting almost
-entirely of @samp{_@var{xxxx}} notations, which is inconvenient and
-all but unreadable.  To handle such cases, @command{texi2any} offers
-the @option{--transliterate-file-names} command line option.  This
-option enables @dfn{transliteration} of node names into ASCII
-characters for the purposes of file name creation and referencing.
-The transliteration is based on phonetic principles, which makes the
-generated file names more easily understandable.
+@end ignore
 
-@cindex Normalization Form C, Unicode
-For the definition of Unicode Normalization Form@tie{}C, see Unicode
-report UAX#15, @uref{http://www.unicode.org/reports/tr15/}.  Many
-related documents and implementations are available elsewhere on the
-web.
+@node Specific Customization of HTML Formatting
+@subsection Specific Customization of HTML Formatting
 
+@c The appearance of specific construct is customizable.
 
-@node HTML Xref Mismatch
-@subsection HTML Cross-reference Mismatch
-@cindex HTML cross-references @subentry mismatch
-@cindex Mismatched HTML cross-reference source and target
+@c Header levels
 
-As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
-software may need to guess whether a given manual being cross-referenced is 
available in split or monolithic form---and, inevitably,
-it might guess wrong.  However, when the @emph{referent} manual is
-generated, it is possible to handle at least some mismatches.
+In HTML, heading levels translate to @samp{<h@var{n}>} elements
+where @var{n} is the heading level.  The following header levels are
+customizable:
 
-In the case where we assume the referent is split, but it is actually
-available in mono, the only recourse would be to generate a
-@file{manual_html/} subdirectory full of HTML files which redirect back to
-the monolithic @file{manual.html}.  Since this is essentially the same
-as a split manual in the first place, it's not very appealing.
+@vtable @code
+@item CHAPTER_HEADER_LEVEL
+Header formatting level used for chapter level sectioning
+commands; default @samp{2}.
 
-On the other hand, in the case where we assume the referent is mono,
-but it is actually available in split, it is possible to use
-JavaScript to redirect from the putatively monolithic
-@file{manual.html} to the different @file{manual_html/node.html} files.
-Here's an example:
+@item COMPLEX_FORMAT_IN_TABLE
+If set, use tables for indentation of complex formats; default
+false.
 
-@example
-function redirect() @{
-  switch (location.hash) @{
-    case "#Node1":
-      location.replace("manual_html/Node1.html#Node1"); break;
-    case "#Node2" :
-      location.replace("manual_html/Node2.html#Node2"); break;
-    @dots{}
-    default:;
-  @}
-@}
-@end example
+@item FOOTNOTE_END_HEADER_LEVEL
+@itemx FOOTNOTE_SEPARATE_HEADER_LEVEL
+Header formatting level used for the footnotes header with
+the `end' footnotestyle or for the `separate' footnotestyle; default @samp{4}.
+@xref{Footnote Styles}.
 
-Then, in the @code{<body>} tag of @file{manual.html}:
+@item MAX_HEADER_LEVEL
+Maximum header formatting level used (higher header
+formatting level numbers correspond to lower sectioning levels);
+default @samp{4}.
 
-@example
-<body onLoad="redirect();">
-@end example
+@end vtable
 
-Once again, this is something the software which generated the
-@emph{referent} manual has to do in advance, it's not something the
-software generating the cross-reference in the present manual can
-control.
 
+@c Menu  Options for the output of @@menu, as well as indices.
+@c Output of other constructs
 
-@node HTML Xref Configuration
-@nodedescription @file{htmlxref.cnf}.
-@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf}
+The appearance of various constructs may be modified by setting:
+@vtable @code
+@item DEF_TABLE
+If set, a @code{<table>} construction for @code{@@deffn}
+and similar @@-commands is used (looking more like the @TeX{} output),
+instead of definition lists; default false.
 
-@pindex htmlxref.cnf
-@cindex HTML cross-references @subentry configuration
-@cindex Cross-reference configuration, for HTML
-@cindex Configuration, for HTML cross-manual references
+@item INDEX_ENTRY_COLON
+Symbol used between the index entry and the associated node or section;
+default is an empty string.
 
-@command{texi2any} reads a file named @file{htmlxref.cnf} to gather
-information for cross-references to other manuals in HTML output.  It
-is looked for in the following directories:
+@item MENU_ENTRY_COLON
+Symbol used between the menu entry and the description; default
+@samp{:}.
 
-@table @file
-@item ./
-(the current directory)
+@item MENU_SYMBOL
+Symbol used in front of menu entries when node names are used
+for menu entries formatting; default is undefined and set to
+@code{&bull;} if @code{USE_NUMERIC_ENTITY} is not set, and to
+@code{&#8217;} if set.
 
-@item ./.texinfo/
-(under the current directory)
+@item NUMBER_FOOTNOTES
+@itemx NO_NUMBER_FOOTNOTE_SYMBOL
+In the default case footnotes are numbered.  With
+@option{--no-number-footnotes} or if @code{NUMBER_FOOTNOTES} is set to 0, a
+@samp{*} is used instead, or the @code{NO_NUMBER_FOOTNOTE_SYMBOL} customization
+variable value, if set.
 
-@item ~/.texinfo/
-(where @code{~} is the current user's home directory)
+@item 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.
+@end vtable
 
-@item @var{sysconfdir}/texinfo/
-(where @var{sysconfdir} is the system configuration directory
-specified at compile-time, e.g., @file{/usr/local/etc})
+@c proposal to be removed
+@c AVOID_MENU_REDUNDANCY
 
-@item @var{datadir}/texinfo/
-(likewise specified at compile time, e.g., @file{/usr/local/share})
-@end table
 
-All files found are used, with earlier entries overriding later ones.
-The Texinfo distribution includes a default file which handles many
-GNU manuals; it is installed in the last of the above directories,
-i.e., @file{@var{datadir}/texinfo/htmlxref.cnf}.
+@node HTML Customization for Math
+@subsection HTML Customization for Math
 
-The @code{HTMLXREF_MODE} customization variable can be set to modify how the
-files are found.  For instance, if set to @samp{none}, no external information
-is used.  @code{HTMLXREF_FILE} sets the file name to something else than
-@file{htmlxref.cnf}.  @pxref{HTML Customization Variables List}.
+Diverse methods can be used to render math in HTML (@pxref{Inserting Math}).
+The is controlled by the @code{HTML_MATH} customization variable
+value.  In the default case, the customization variable is unset
+and the HTML output is only emphasized.  Better options for
+displaying properly formatted mathematics may be selected.  Some of
+these options also translate @code{@@tex} if @option{--iftex} is set,
+and @code{@@latex} sections if @option{--iflatex} is set.
 
-The file is line-oriented.  Lines consisting only of whitespace are
-ignored.  Comments are indicated with a @samp{#} at the beginning of a
-line, optionally preceded by whitespace.  Since @samp{#} can occur in
-URLs (like almost any character), it does not otherwise start a
-comment.
+@table @code
+@item l2h
+Use the @command{latex2html} program to produce
+image files for mathematical material.
 
-Each non-blank non-comment line must be either a @dfn{variable
-assignment} or @dfn{manual information}.
+@command{latex2html} will process @LaTeX{} math in math commands,
+including @TeX{} math compatible with @LaTeX{}.
+@command{latex2html} is used to translates @code{@@tex}
+and @code{@@latex} sections to HTML if the corresponding sections
+are not ignored.  Note that @command{latex2html} can only process @LaTeX{},
+including when processing @code{@@tex} sections.
 
-A variable assignment line looks like this:
+Processing with @command{latex2html} should leave files in the
+output directory, with @samp{-l2h} in their name, in particular
+a cache file to avoid redoing translation HTML if already done.
 
-@example
-@var{varname} = @var{varvalue}
-@end example
+@xref{@command{latex2html} Customization Variables}.
 
-Whitespace around the @samp{=} is optional and ignored.  The
-@var{varname} should consist of letters; case is significant.  The
-@var{varvalue} is an arbitrary string, continuing to the end of the
-line.  Variables are then referenced with @samp{$@{@var{varname}@}};
-variable references can occur in the @var{varvalue}.
+@item mathjax
+@anchor{MathJax scripts}
+Inserts references in the output files to MathJax scripts to format the
+material.  The MathJax option requires JavaScript
+to be enabled in the browser to work.
 
-A manual information line looks like this:
+MathJax handles @LaTeX{} math, including @TeX{}
+math compatible with @LaTeX{} commonly used.  Some specific constructs
+(for example some uses of @code{\text}) are not supported, but this should
+not be a practical issue.
 
-@example
-@var{manual} @var{keyword} @var{urlprefix}
-@end example
+If math commands are actually processed, a JavaScript license web label is
+generated for MathJax scripts (@pxref{JavaScript license web labels}).
 
-@noindent
-with @var{manual} the short identifier for a manual, @var{keyword}
-being one of: @code{mono}, @code{node}, @code{section},
-@code{chapter}, and @var{urlprefix} described below.  Variable
-references can occur only in the @var{urlprefix}.  For example (used
-in the canonical @file{htmlxref.cnf}):
+@xref{MathJax Customization Variables}.
 
-@example
-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/
-@end example
+@item t4h
+Use the @command{tex4ht} to produce HTML for mathematical material.
 
-@cindex monolithic manuals, for HTML cross-references
-If the keyword is @code{mono}, @var{urlprefix} gives the host,
-directory, and file name for @var{manual} as one monolithic file.
+@command{tex4ht} will process @LaTeX{} math in math commands,
+including @TeX{} math compatible with @LaTeX{}.
+@command{tex4ht} is used to translates @code{@@tex} and @code{@@latex}
+sections to HTML if the sections are not ignored.  The @code{@@tex} sections
+are processed in @TeX{} mode, while the @code{@@latex} sections are
+processed as @LaTeX{}.
 
-@cindex split manuals, for HTML cross-references
-If the keyword is @code{node}, @code{section}, or @code{chapter},
-@var{urlprefix} gives the host and directory for @var{manual} split
-into nodes, sections, or chapters, respectively.
+Processing with @command{tex4ht} should leave files in the
+output directory, with @samp{_tex4ht} in their name.
 
-When available, @command{texi2any} will use the ``corresponding''
-value for cross-references between manuals.  That is, when generating
-monolithic output (@option{--no-split}), the @code{mono} URL will be
-used, when generating output that is split by node, the @code{node}
-URL will be used, etc.  However, if a manual is not available in that
-form, anything that is available can be used.  Here is the search
-order for each style:
+@xref{@command{tex4ht} Customization Variables}.
 
-@example
-node    @result{} node,    section, chapter, mono
-section @result{} section, chapter, node,    mono
-chapter @result{} chapter, section, node,    mono
-mono    @result{} mono,    chapter, section, node
-@end example
+@end table
 
-@opindex --node-files@r{, and HTML cross-references}
-These section- and chapter-level cross-manual references can succeed
-only when the target manual was created using @option{--node-files};
-this is the default for split output.
+In the default case, with @code{CONVERT_TO_LATEX_IN_MATH} undefined,
+setting @code{HTML_MATH} also sets @code{CONVERT_TO_LATEX_IN_MATH}.
+In that case Texinfo @@-commands inside @code{@@math} and @code{@@displaymath}
+are converted to @LaTeX{}, before converting the @code{@@math} or
+@code{@@displaymath} to HTML.
 
-If you have additions or corrections to the @file{htmlxref.cnf}
-distributed with Texinfo, please email @email{bug-texinfo@@gnu.org} as
-usual.  You can get the latest version from
-@url{http://ftpmirror.gnu.org/@/texinfo/@/htmlxref.cnf}.
 
 
 @node @@-Command Details