1 Overview 2 Loading Initialization Files and Search Paths 3 Init File Basics 4 Simple formatting customization 5 Simple headers customizations 6 User Defined Functions 7 Error Reporting, Customization and Paths Manipulation with Converter 8 Customizing Output-Related Names 9 Init File Calling at Different Stages 10 Formatting HTML Output 11 Customization and Use of Formatting Functions 12 Tree Element Conversion Customization 13 Output Units Conversion Functions 14 Shared Conversion State 15 Translations in Output and Customization 16 Customizing Footnotes, Tables of Contents and About 17 Customizing HTML Footers, Headers and Navigation Panels 18 Beginning and Ending Files 19 Titlepage, CSS and Redirection Files Appendix A Specific Functions for Specific Elements Appendix B Functions Index Appendix C Variables Index Appendix D General Index 1 Overview 2 Loading Initialization Files and Search Paths 3 Init File Basics 3.1 Init File Namespace 3.2 Getting Build Constants 3.3 Managing Customization Variables 3.3.1 Setting Main Program String Variables 3.3.2 Modifying Main Program Array Variables 3.3.3 Setting Converter Variables in Main Program 3.3.4 Getting Main Program Variables Values 3.4 Init File Loading Error Reporting 4 Simple formatting customization 4.1 Init File Expansion Contexts: Normal, Preformatted, Code, String, Math 4.2 Simple Customization for Commands Without Arguments 4.3 Simple Customization for Simple Commands with Braces 4.3.1 Customization of Commands Converting to Uppercase 4.3.2 Simple Output Customization for Simple Commands with Braces 4.4 Simple Customization of Accent Commands 4.5 Simple Customization of Containers 5 Simple headers customizations 5.1 Output Units 5.2 Directions 5.2.1 Output Unit Direction Information Type 5.2.2 Direction Strings 5.3 Direction Strings Customization 5.4 Simple Navigation Panel Customization 6 User Defined Functions 6.1 User Defined Functions are Registered 6.2 Converter Object and Conversion Functions 7 Error Reporting, Customization and Paths Manipulation with Converter 7.1 Error Reporting in User Defined Functions 7.2 Setting and Getting Conversion Customization Variables 7.3 Encoding and Decoding File Path Strings 7.3.1 Encoding File Path Strings 7.3.2 Decoding File Path Strings 7.4 Protection of URLs 8 Customizing Output-Related Names 8.1 Customizing Output File Names 8.2 Customizing Output Target Names 8.3 Customizing External Node Output Names 8.4 Customizing Special Elements Output Names 9 Init File Calling at Different Stages 10 Formatting HTML Output 10.1 Specific HTML Constructs Formatting Functions 10.1.1 Formatting HTML Element with Classes 10.1.2 Closing Lone HTML Element 10.1.3 Substituting Non Breaking Space 10.2 Converter General Information 10.3 Getting Conversion Context 10.3.1 Conversion in String Context 10.3.2 Conversion in Preformatted Context 10.3.3 Other Dynamic Information 10.4 Converting Texinfo Trees 10.4.1 Texinfo Tree Conversion Functions 10.4.2 Setting the Context for Conversion 10.4.3 Conversion to Plain Text 10.4.4 Texinfo Tree Elements in User Defined Functions 10.4.5 Output Units in User Defined Functions 11 Customization and Use of Formatting Functions 11.1 Registering Specific Formating Functions 11.2 Basic Formatting Customization 12 Tree Element Conversion Customization 12.1 Command Tree Element Conversion 12.1.1 Command Tree Element Conversion Functions 12.1.2 Command Tree Element Opening Functions 12.1.3 Heading Commands Formatting 12.1.4 Target Tree Element Link 12.1.5 Specific Formatting for Indices 12.1.6 Image Formatting 12.2 Type Tree Element Conversion 12.2.1 Type Tree Element Conversion Functions 12.2.2 Type Tree Element Opening Functions 12.2.3 Text Tree Elements Conversion 12.2.4 Inline Text Containers Paragraph and Preformatted Formatting 13 Output Units Conversion Functions 14 Shared Conversion State 14.1 Define, Get and Set Shared Conversion State 14.2 Shared Conversion State in Default Formatting 15 Translations in Output and Customization 15.1 Internationalization of Strings Function 15.2 Translated Strings Customization 15.3 Translation Contexts 16 Customizing Footnotes, Tables of Contents and About 16.1 Special Units Information Customization 16.2 Customizing Footnotes 16.3 Contents and Short Table of Contents Customization 16.4 About Special Output Unit Customization 16.5 Special Unit Body Formatting Functions 17 Customizing HTML Footers, Headers and Navigation Panels 17.1 Navigation Panel Button Formatting 17.2 Navigation Panel and Navigation Header Formatting 17.3 Element Header and Footer Formatting 17.4 Element Counters in Files 18 Beginning and Ending Files 18.1 Customizing HTML File Beginning 18.2 Customizing HTML File End 18.3 Associating Information to an Output File 19 Titlepage, CSS and Redirection Files 19.1 HTML Title Page Customization 19.2 CSS Customization 19.2.1 Customization of CSS Rules, Imports and Selectors 19.2.2 Customizing the CSS Lines 19.3 Customizing Node Redirection Pages Appendix A Specific Functions for Specific Elements Appendix B Functions Index Appendix C Variables Index Appendix D General Index GNU Texinfo ‘texi2any’ Output Customization ******************************************* 1 Overview ********** Warning: All of this information, with the exception of command-line options and search directories associated with command line options (see Loading Init Files), may become obsolete in a future Texinfo release. Right now, the "API" described in this chapter is immature, so we must keep open the possibility of incompatible, possibly major, changes. Of course we try to avoid incompatible changes, but it is not a promise. This manual describes how to customize the ‘texi2any’ HTML output. Although some of the features here can technically be used with other output formats, it's not especially useful to do so, so we'll write the documentation as if HTML were the target format. Most of the customizations are only available for HTML. The conversion of Texinfo to HTML is done in two steps. After reading command-line options and init files, input Texinfo code is parsed into a Texinfo tree and information is gathered on the document structure. This first step can only be customized to a certain extent, by using the command-line options and setting customization variables (see (texinfo)Global Customization Variables). The Texinfo tree describes a Texinfo document in a structured way which makes it easy to go through the tree and format @-commands and other containers. The second step is the “conversion” step done in a converter. The HTML converter takes a Texinfo tree as input and transforms it to HTML. The code that is used to go through the tree cannot be customized, but the conversion of tree elements can be fully customized. 2 Loading Initialization Files and Search Paths *********************************************** Warning: The ‘texi2any-config.pm’ file related paths and even the use of ‘texi2any-config.pm’ files is not definitive. You can write so-called “initialization files”, or “init files” for short, to modify almost every aspect of output formatting. The program loads init files named ‘texi2any-config.pm’ each time it is run. The directories lookup is based on the XDG Base Directory Specification (https://specifications.freedesktop.org/basedir-spec/latest/) with defaults based on installation directories. The ‘texi2any-config.pm’ files are looked for in the following directories: ‘DATADIR/texi2any/’ (where DATADIR is the system data directory specified at compile-time, e.g., ‘/usr/local/share’) ‘XDG_CONFIG_DIRS/texi2any’ (for each directory in the ‘:’ delimited ‘XDG_CONFIG_DIRS’ environment variable, in reverse order) ‘SYSCONFDIR/xdg/texi2any/’ (where SYSCONFDIR is specified at compile time, e.g., ‘/usr/local/etc’) ‘~/.config/texi2any/’ (where ‘~’ is the current user's home directory, only if ‘XDG_CONFIG_HOME’ is not set) ‘XDG_CONFIG_HOME/texi2any’ (with ‘XDG_CONFIG_HOME’ an environment variable) ‘./.texi2any/’ (under the current directory) ‘./’ (the current directory) All ‘texi2any-config.pm’ files found are loaded, in the above order. Thus, ‘./texi2any-config.pm’ can override entries in, say, ‘DATADIR/texi2any/texi2any-config.pm’. However, the most common way to load an initialization file path is with the ‘--init-file’ option, explicitly specifying the file path to be loaded. If the initialization file path contains directories, it is loaded if found. Otherwise, if the file path is a simple file name, the following directories are searched, in the following order by default. Only the first file found is used: 1. The current directory ‘./’; 2. ‘./.texi2any/’ under the current directory; 3. ‘XDG_CONFIG_HOME/texi2any’ if the ‘XDG_CONFIG_HOME’ environment is set, otherwise ‘~/.config/texi2any/’ where ‘~’ is the current user's home directory; 4. ‘SYSCONFDIR/xdg/texi2any/’ where SYSCONFDIR is the system configuration directory specified at compile-time, e.g., ‘/usr/local/etc’; 5. if the environment variable ‘XDG_CONFIG_DIRS’ is set, ‘DIRECTORY/texi2any’ for each DIRECTORY in the ‘:’ delimited ‘XDG_CONFIG_DIRS’ environment variable value; 6. ‘DATADIR/texi2any/’ Where DATADIR is the system data directory specified at compile time, e.g., ‘/usr/local/share’; 7. ‘./.texinfo/init/’ under the current directory; 8. ‘XDG_CONFIG_HOME/texinfo/init’ if the ‘XDG_CONFIG_HOME’ environment is set, otherwise ‘~/.config/texinfo/init/’ where ‘~’ is the current user's home directory; 9. ‘SYSCONFDIR/xdg/texinfo/init/’ with SYSCONFDIR as above; 10. if the environment variable ‘XDG_CONFIG_DIRS’ is set, ‘DIRECTORY/texinfo/init’ for each DIRECTORY in the ‘:’ delimited ‘XDG_CONFIG_DIRS’ environment variable value; 11. ‘DATADIR/texinfo/init/’ with DATADIR as above. 12. ‘DATADIR/texinfo/ext/’ with DATADIR as above. The ‘DATADIR/texinfo/ext/’ directory contains the init files directly loaded from ‘texi2any’ code. When loaded from ‘texi2any’ code directly, init files are only searched for in that directory, being considered as part of the program and not as user customization. Since the directory is also in the list of directories searched for init files loaded by the ‘--init-file’ option, those init files can also be loaded as regular user specified init files. Additional directories may be prepended to the list with the ‘--conf-dir’ option (see (texinfo)Invoking texi2any). 3 Init File Basics ****************** Init files are written in Perl, and by convention have extension ‘.init’ or ‘.pm’. Several init files are included in the Texinfo distribution, and can serve as a good model for writing your own. Another example is the ‘Texinfo::Convert::HTML’ module which implements almost all the Texinfo HTML function described in this manual for the conversion to HTML(1). In ‘Texinfo::Convert::HTML’ the API may not be followed strictly for performance reasons, in that case there should always be a ‘API info:’ comment which shows what the API conformant code should be. The Licenses conditions of the diverse files used as example should be taken into account when reusing code. ---------- Footnotes ---------- (1) The ‘Texinfo::Convert::HTML’ module also implements the HTML converter which go through the tree and call user defined functions. 3.1 Init File Namespace ======================= Initialization file are loaded from the main program in the ‘Texinfo::Config’ namespace. This means that the namespace of the main program and the namespace of initialization files are distinct, which minimizes the chance of a name clash. It is possible to start init files with: package Texinfo::Config; It is not required, but it may help some debugging tools determine in which namespace the code is run. In the ‘Texinfo::Config’ namespace, the functions names beginning with ‘texinfo_’, ‘GNUT_’ and ‘_GNUT_’ are reserved. User defined functions in init files should never begin with those prefixes. The HTML converter is not available directly in the init files namespace, instead it is passed to functions defined in init files that are registered as functions to be called from the converter. See User Defined Functions. 3.2 Getting Build Constants =========================== Some constants are set independently of the output format for a Texinfo build. They are available through ‘Texinfo::Common::get_build_constant’: -- Function: $VALUE = Texinfo::Common::get_build_constant ($NAME) Retrieve build constant $NAME value. Defined build constants: ‘PACKAGE’ ‘PACKAGE_CONFIG’ ‘PACKAGE_AND_VERSION’ ‘PACKAGE_AND_VERSION_CONFIG’ ‘PACKAGE_NAME’ ‘PACKAGE_NAME_CONFIG’ ‘PACKAGE_VERSION’ ‘PACKAGE_VERSION_CONFIG’ ‘PACKAGE_URL’ ‘PACKAGE_URL_CONFIG’ Texinfo package name and versions. Values of build constants without ‘_CONFIG’ appended are set by configure. Similar customization variables exist with the same value set in the default case from the main program, with values that can be modified. The values of the build constants with ‘_CONFIG’ appended are duplicate of the values of the build constants without ‘_CONFIG’(1). ---------- Footnotes ---------- (1) They are set to correspond to macro set in the C code. In the C code there are no macros with the names without ‘_CONFIG’ appended as they would clash with the names of the customization options. 3.3 Managing Customization Variables ==================================== The basic operations on customization variables are to set and retrieve their values. The customization variables also valid in the main program out of the HTML converter are handled differently if their associated values are strings or arrays. Conversely, customization variables only relevant for the conversion phase set in the main program are always set by associating a string, an array reference or a hash references to customization variables in the same way. This section describes customization variables set in the main program. These variables are in general passed to converters. It is also possible to set customization variables in the converters only, not in the main program. This is explained later on (see Conversion Customization Variables). 3.3.1 Setting Main Program String Variables ------------------------------------------- To set the value of a string customization variable from an initialization file, use ‘texinfo_set_from_init_file’: -- Function: texinfo_set_from_init_file ($variable_name, $variable_value) $VARIABLE_NAME is a string containing the name of the variable you want to set, and $VARIABLE_VALUE is the value to which you want to set it. $VARIABLE_VALUE may be ‘undef’. For example, texinfo_set_from_init_file('documentlanguage', 'fr'); overrides the ‘@documentlanguage’ from the document. It would be overridden by ‘--document-language’ on the command line. Another example: texinfo_set_from_init_file('SPLIT', 'chapter'); overrides the default splitting of the document. It would be overridden by ‘--split’ on the command line. A final example: texinfo_set_from_init_file('NO_CSS', 1); overrides the default value for ‘NO_CSS’. It would be overridden by ‘--set-init-variable NO_CSS=1’ on the command line. Setting the output format cannot be done by setting the customization variable ‘TEXINFO_OUTPUT_FORMAT’. This customization variable sets the output format in the main program, but not from init files as additional code needs to be run. Instead, call the ‘texinfo_set_format_from_init_file’ function: -- Function: texinfo_set_format_from_init_file ($output_format) $OUTPUT_FORMAT is the output format; sets the output format, without overriding formats set from the command line. Any output format can be set, but since only HTML can be customized, the main use of ‘texinfo_set_format_from_init_file’ is to set the format to ‘html’, such that HTML is generated instead of Info in the default case. For the customization variables associated with @-commands, see (texinfo)Customization Variables for @-Commands. For the customization variables associated with command line options, see (texinfo)Customization Variables and Options. 3.3.2 Modifying Main Program Array Variables -------------------------------------------- Warning: The main program customization variables associated with arrays are not documented. Customization variables for the main program associated with an array of values are handled differently. You can use ‘texinfo_add_to_option_list’ to add values to the array and ‘texinfo_remove_from_option_list’ to remove values from the array associated with the customization variable: -- Function: texinfo_add_to_option_list ($variable_name, $variable_values_array_reference, $prepend) -- Function: texinfo_remove_from_option_list ($variable_name, $variable_values_array_reference) $VARIABLE_NAME is the name of the variable; the values in the array reference $VARIABLE_VALUES_ARRAY_REFERENCE are added to the list associated with the variable with ‘texinfo_add_to_option_list’, and removed with ‘texinfo_remove_from_option_list’. If the optional argument of ‘texinfo_add_to_option_list’ $PREPEND is set, the values are prepended instead of being appended. 3.3.3 Setting Converter Variables in Main Program ------------------------------------------------- Array and hash references customization variables values relevant in converters only (not in main program, but in the HTML converter) can be set through the main program in init files. These variables cannot be set on the command-line. They are documented in the customization documentation, not in the main Texinfo manual. You set such arrays or hashes references with ‘texinfo_set_from_init_file’. For example: my @SECTION_BUTTONS = ( \&singular_banner, 'Back', 'Forward', 'FastBack', 'FastForward', 'Up', 'Top', 'Contents', 'Index', 'About' ); texinfo_set_from_init_file ('SECTION_BUTTONS', \@SECTION_BUTTONS); 3.3.4 Getting Main Program Variables Values ------------------------------------------- To get the value of a variable, the function is ‘texinfo_get_conf’: -- Function: texinfo_get_conf ($variable_name) $VARIABLE_NAME is the name of the variable; its value (possibly ‘undef’) is returned. For example: if (texinfo_get_conf('footnotestyle') eq 'separate') { ... } 3.4 Init File Loading Error Reporting ===================================== If an error or a warning should be emitted when loading an init file, before the conversion, use ‘texinfo_register_init_loading_error’ for an error and ‘texinfo_register_init_loading_warning’ for a warning. -- Function: texinfo_register_init_loading_error ($message) -- Function: texinfo_register_init_loading_warning ($message) Cause an error message or a warning message based on $MESSAGE to be output, taking into account options related to error reporting such as ‘--force’ or ‘--no-warn’. Errors or warning emitted from user defined functions should use the converter (see Error Reporting in User Defined Functions). 4 Simple formatting customization ********************************* Some change in output formatting can be specified with simple code, not very different from simple textual configuration information. 4.1 Init File Expansion Contexts: Normal, Preformatted, Code, String, Math ========================================================================== Output formatting simple customization needs to be specified especially for different formatting contexts. There are five expansion contexts of interest: _normal context_ Paragraphs, index entries, tables, ... _preformatted context_ When spaces between words are kept. For example, within the ‘@display’ (see (texinfo)@display) and ‘@example’ environments (see (texinfo)@example), and in menu comments. The preformatted regions are usually rendered using ‘
’ elements in HTML.

_code context_
     When quotes and minus are kept.  In particular ‘---’, ‘``’ and
     other similar constructs are not converted to dash and quote
     special characters.  For example, in ‘@code’ or ‘@option’ commands
     (see (texinfo)Useful Highlighting).

_math context_
     Math (see ‘@math’: (texinfo)math).  Code or preformatted
     specifications are often used for math too.  In those cases, there
     is no way to separately specify the formatting in math context.

_string context_
     When rendering strings without formatting elements, for example in
     titles.  The string context allows for limited formatting,
     typically without any element when producing HTML or XML, so the
     value can be used in an attribute.  XML entities can be used in
     strings.

   It is worth mentioning that in some cases, in particular for file
names, plain text can also be used in conversion.  There is no
associated context in the converter, so the conversion to plain text is
usually performed by converting a Texinfo elements tree outside of the
main conversion flow.

4.2 Simple Customization for Commands Without Arguments
=======================================================

These commands include those whose names are a single nonletter
character, such as ‘@@’, and those with a normal alphabetic name but
whose braces should be empty, such as ‘@TeX{}’ and ‘@AA{}’.

   To change the formatting of a command, the functions is
‘texinfo_register_no_arg_command_formatting’:

 -- Function: texinfo_register_no_arg_command_formatting ($command_name,
          $context, $text, $html_element, $translated_string_converted,
          $translated_string_to_convert)
     $COMMAND_NAME is the @-command name, without the leading @.
     $CONTEXT is ‘normal’, ‘preformatted’ or ‘string’.  There is no
     separate math context, ‘preformatted’ should be used for math
     context.  See Init File Expansion Contexts.  If $CONTEXT is
     ‘undef’, the ‘normal’ context is assumed.

     The remaining arguments determine the formatting.  If $TEXT is set,
     the corresponding text is output when the @-command is formatted.
     $TEXT can contain HTML elements if needed.  If $HTML_ELEMENT is
     set, the text is enclosed between the $HTML_ELEMENT element opening
     and the element closing.  If $TRANSLATED_STRING_CONVERTED is set,
     the corresponding text is translated when the document language
     changes and used as text.  $TRANSLATED_STRING_CONVERTED should
     already be HTML. If $TRANSLATED_STRING_TO_CONVERT is set, the
     corresponding text is translated when the document language changes
     and converted from Texinfo code to HTML. Since the conversion is
     done in the appropriate context, $TRANSLATED_STRING_TO_CONVERT
     should only be set for the ‘normal’ context.  See
     (texi2any_internals)Texinfo::Translations METHODS.

   It is not required to set values for all the contexts.  If
preformatted context output is not set, normal context output is used.
If string context output is not set, preformatted context output is
used.

   For example, if you want ‘­’ to be output for ‘@-’ in normal,
preformatted (and math) and string context, call

     texinfo_register_no_arg_command_formatting('-', undef, '­');

   If you want "‘...’" to be output for ‘@enddots’ in
normal context and ‘...’ to be output in other contexts, call
     texinfo_register_no_arg_command_formatting('enddots',
                                                'normal', '...', 'small');
     texinfo_register_no_arg_command_formatting('enddots',
                                                'preformatted', '...');

   If you want "‘error-->’" to be used for ‘@error’ in every context,
with a translation when the document language changes, call

     texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
                                                'error-->');

   If you want "‘is the *same* as’" to be used for ‘@equiv’, translated
when the document language changes, and converted from Texinfo to HTML
in the context of the translation, call
     texinfo_register_no_arg_command_formatting('equiv', undef, undef, undef,
                                      undef, 'is the @strong{same} as');

   See Translated Strings Customization for customization of translated
strings.

4.3 Simple Customization for Simple Commands with Braces
========================================================

4.3.1 Customization of Commands Converting to Uppercase
-------------------------------------------------------

Formatting of ‘@sc’ may involve uppercasing the argument.  The
specification of @-command argument uppercasing can be changed with
‘texinfo_register_upper_case_command’:

 -- Function: texinfo_register_upper_case_command ($command_name,
          $value)
     $COMMAND_NAME is the @-command name, without the leading @.  $VALUE
     sets or unsets uppercasing of argument.

   For example, to prevent ‘@sc’ argument from being uppercased and set
‘@var’ argument to be uppercased:

     texinfo_register_upper_case_command('sc', 0);
     texinfo_register_upper_case_command('var', 1);

4.3.2 Simple Output Customization for Simple Commands with Braces
-----------------------------------------------------------------

You can change the formatting of the output produced by "indicator" and
font commands (e.g., ‘@code’, ‘@t’), and other simple commands with
arguments (e.g., ‘@asis’, ‘@clicksequence’, ‘@sup’, ‘@verb’) with
‘texinfo_register_style_command_formatting’:

 -- Function: texinfo_register_style_command_formatting ($command_name,
          $html_element, $in_quotes, $context)
     $COMMAND_NAME is the @-command name, without the leading @.
     $CONTEXT is ‘normal’ or ‘preformatted’.  There is no separate math
     context, ‘preformatted’ should be used for math context.  See Init
     File Expansion Contexts.  There is no string context either, as in
     string context simple formatting without the need for per command
     information should be sufficient.  If $CONTEXT is ‘undef’, the
     ‘normal’ context is assumed.

     If $HTML_ELEMENT is set, the argument is enclosed between the
     $HTML_ELEMENT element opening and the element closing.  If
     $IN_QUOTES is true, the result is enclosed in quotes associated
     with customization variables ‘OPEN_QUOTE_SYMBOL’ and
     ‘CLOSE_QUOTE_SYMBOL’ (see (texinfo)Customization of HTML Code
     Inserted).

     If $HTML_ELEMENT is undefined and $IN_QUOTES is not set, the
     formatted argument is output as is.

   For example, to set ‘@sansserif{argument}’ to be formatted as
‘ARGUMENT’ in normal and preformatted context, with quotes
in preformatted context, use:

     texinfo_register_style_command_formatting('sansserif', 'code', 0,
                                               'normal');
     texinfo_register_style_command_formatting('sansserif', 'code', 1,
                                               'preformatted');

   To output the formatted argument of ‘@t’ as is:
     foreach my $context ('normal', 'preformatted') {
       texinfo_register_style_command_formatting ('t', undef,
                                                  undef, $context);
     }

4.4 Simple Customization of Accent Commands
===========================================

You can modify the formatting of accent commands such as ‘@'’,
‘@ringaccent’ or ‘@dotless’ by selecting HTML general features, to
output numeric entities or characters (see (texinfo)HTML Features
Customization).

   You can also change how accented commands are converted to named
entities.  The accent named entities are obtained by combining a letter
to be accented, such as ‘e’ and a postfix based on the accent command
name, for example ‘acute’ for the acute accent ‘@'’.  For example, ‘@'e’
is converted to the ‘é’ named entity in the default case.

   The association of accent @-command and named entity postfix and the
list of letters that can be prepended can be changed with
‘texinfo_register_accent_command_formatting’:

 -- Function: texinfo_register_accent_command_formatting
          ($accent_command_name, $entity_postfix, $letters)
     $ACCENT_COMMAND_NAME is a Texinfo accent formatting @-command name,
     $ENTITY_POSTFIX is a string corresponding to the accent command
     that is postpended to the letter accent argument.  $LETTERS is a
     string listing the letters that can be combined with the
     $ENTITY_POSTFIX.  If $ENTITY_POSTFIX or $LETTERS is an empty
     string, numeric entities are used instead of named entities.

   For example, with the following code, ‘@dotless{i}’ should be
converted to ‘ı’, and ‘@dotless{j}’ to ‘&jnodot;’.  Other letters
than ‘i’ and ‘j’ in argument of ‘@dotless’ should not be combined into a
named entity with that example.
     texinfo_register_accent_command_formatting('dotless', 'nodot', 'ij');

4.5 Simple Customization of Containers
======================================

Texinfo tree elements that are not text container nor directly
associated with an @-command can have information set on their
formatting.  The first piece of information is whether their contents
should be considered in code context (see Init File Expansion Contexts).
The other piece of information is the type of preformatted environment
they are, analogous with the @-command names of ‘@example’ or
‘@display’(1).

   The function used is ‘texinfo_register_type_format_info’:

 -- Function: texinfo_register_type_format_info ($type, $code_type,
          $pre_class_type)
     $TYPE is the type of the container.  If $CODE_TYPE is set, the
     container contents are assumed to be in code context.  See Init
     File Expansion Contexts.  If $PRE_CLASS_TYPE is set, the HTML
     ‘
’ elements class attribute are based on $PRE_CLASS_TYPE, if
     there are such HTML elements output for preformatted content of
     $TYPE containers.

   For example, to set content appearing in-between node links in
‘@menu’, which is in the ‘menu_comment’ container type to be formatted
in a code context, with preformatted type ‘menu-between’, use:

     texinfo_register_type_format_info('menu_comment', 1, 'menu-between');

   See (texi2any_internals)Texinfo::Parser Types of container elements,
for a description of container types.

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

   (1) Note that setting the type of preformatted environment does not
make sure that there are preformatted containers used for the formatting
of their contents instead of paragraph containers, since this is
determined in the very first step of parsing the Texinfo code, which
cannot be customized.

5 Simple headers customizations
*******************************

Headers and footers with a navigation panel are output in the default
case.  You can already customize the overall formatting and appearance
of headers and navigation panels with customization variables (see
(texinfo)Customization of Navigation and Headers).

   You can specify more precisely the labels and links output in
navigation panels with simple code.  To explain how navigation panels
are customized, we first describe how the document is organized and
which directions are available as the directions is the basis for
navigation panel customization.

5.1 Output Units
================

We will call the main unit of output documents a document output “unit”.
An output unit's association with output files is determined by the
split options (see (texinfo)Splitting Output).  This section describes
precisely how these output units work, with details for customization.

   The output units are:

_Normal output units_
     These are composed of normal sections and nodes.  Usually a node is
     associated with a following sectioning command, while a sectioning
     command is associated with a previous node; they both together make
     up the output unit.  Either the node or the sectioning command is
     considered to be the main element component, depending on the
     values of the customization variables ‘USE_NODES’ (see
     (texinfo)HTML Output Structure Customization).

     For example, when generating Info, the nodes are the main elements;
     when generating HTML, either case may happen (see (texinfo)Two
     Paths).

_Top output unit_

     The top output unit is the highest output unit in the document
     structure.  If the document has an ‘@top’ section (see
     (texinfo)@top Command), it is the output unit associated with that
     section; otherwise, it is the output unit associated with the
     document's ‘@node Top’ (see (texinfo)The Top Node).  If there is no
     ‘@node Top’, the first output unit in the document is the top
     output unit.  The Top output unit is also a normal output unit.

_Miscellaneous output units_
     The remaining output units are associated with different files if
     the document is split, and also if ‘MONOLITHIC’ is not set (see
     texinfo: HTML Output Structure Customization in ‘Texinfo’).  There
     are four such miscellaneous output units, also called special
     output units:
       1. Table of contents
       2. Short table of contents, also called Overview
       3. Footnotes page
       4. About page

     More details:

        • The _Table of contents_ should only be formatted if
          ‘@contents’ is present in the document.

        • Similarly the _Short table of contents_ should only appear if
          ‘@shortcontents’ or ‘@summarycontents’ is present.

        • The customization variables ‘contents’ and ‘shortcontents’ may
          be set to trigger the output of the respective output units.

        • If ‘CONTENTS_OUTPUT_LOCATION’ is set to ‘separate_element’,
          the _Table of contents_ and _Short table of contents_ output
          units are separate (see Contents and Short Table of Contents
          Customization).  Otherwise the _Table of contents_ and _Short
          table of contents_ are directly included within the document,
          at locations depending on the specific
          ‘CONTENTS_OUTPUT_LOCATION’ value (see texinfo: HTML Output
          Structure Customization in ‘Texinfo’.

        • When generating HTML, the _Footnotes page_ should only be
          present if the footnotes appear on a separate page (see
          (texinfo)Footnote Styles).  However, a footnote output unit is
          present if the document is not split.

        • The _About page_ shouldn't be present for documents consisting
          of only one sectioning element, or for monolithic documents
          without navigation information, or if ‘DO_ABOUT’ is not set.

   It is common not to have anything but normal output units, especially
in case of monolithic output.

   A last type of output units exist, "virtual" output units
corresponding to directions to external manual nodes.  They are not part
of the output, but can be used in directions.  They are often referred
to as “external node units” or “external manual units”.  These units do
not exist in the document output, therefore there are no functions
called to format those output units.  They can appear in directions
formatting (see Navigation Panel Button Formatting).

5.2 Directions
==============

A variety of data items, called “output units directions”, are
associated with output units.  They may be used in the formatting
functions, and/or associated with a button (see Simple Navigation Panel
Customization).

   Each output unit direction has a name and a reference to the unit
they point to, when such an unit exists.  The unit is either a global
unit (for example, the Top output unit) or relative to the current
output unit (for example, the next output unit).  Such relative output
units are determined with respect to the document structure defined by
the section structuring commands (‘@chapter’, ‘@unnumbered’...) or by
the nodes if the node pointers are specified on ‘@node’ lines or in
menus (see (texinfo)Two Paths).

   Here is the list of global output units directions:

_‘ ’_
     An empty button.

_Top_
     Top output unit.

_First_
     First output unit in reading order.

_Last_
     Last output unit in reading order.

_About_
     About (help) page.

_Contents_
     Table of contents.

_Overview_
     Overview: short table of contents.

_Footnotes_
     Corresponds to the ‘Footnotes’ output unit (see Output Units).

_Index_
     The first output unit with ‘@printindex’.

   Here is the list of relative output units directions:

_This_
     The current output unit.

_Forward_
     Next output unit in reading order.

_Back_
     Previous output unit in reading order.

_FastForward_
     Next chapter output unit.

_FastBack_
     Beginning of this chapter, or previous chapter if the output unit
     corresponds to a chapter.

_Next_
     Next section output unit at the same level.

_Prev_
     Previous section output unit at the same level.

_Up_
     Up section.

_NodeNext_
     Next node output unit.

_NodeForward_
     Next node output unit in node reading order.

_NodeBack_
     Previous node output unit in node reading order.

_NodePrev_
     Previous node output unit.

_NodeUp_
     Up node output unit.

   Relative direction are each associated with a variant, with
‘FirstInFile’ prepended, which points to the direction relative to the
first output unit in file.  For example, ‘FirstInFileNodeNext’ is the
next node output unit relative to the first output unit in file.  The
‘FirstInFile’ directions are usually used in footers.

5.2.1 Output Unit Direction Information Type
--------------------------------------------

The output unit directions also have types of information associated,
which are in general set dynamically depending on the current output
unit, for instance on the output unit whose navigation panel is being
formatted:

‘href’
     A string that can be used as an href attribute linking to the
     output unit corresponding to the direction.

‘string’
     A string representing the direction that can be used in context
     where only entities are available (attributes).  See Init File
     Expansion Contexts.

‘text’
     A string representing the direction to be used in contexts with
     HTML elements (preformatted and normal contexts).  See Init File
     Expansion Contexts.

‘node’
     Same as ‘text’, but selecting the node associated with the output
     unit direction in priority.

‘section’
     Same as ‘text’, but selecting the sectioning command associated
     with the output unit direction in priority.

   ‘text’ and ‘string’ also have a variant with ‘_nonumber’ prepended,
such as ‘text_nonumber’ without sectioning command number in the
representation.

5.2.2 Direction Strings
-----------------------

Directions have strings associated, corresponding to their names,
description or specific HTML keywords:

‘accesskey’
     Direction ‘accesskey’ attribute used in navigation.

‘button’
     Direction short name typically used for buttons.

‘description’
     Description of the direction.

‘example’
     Section number corresponding to the example used in the About
     special element text.

‘rel’
     Direction ‘rel’ attribute used in navigation.

‘text’
     Direction text in a few words.

   ‘button’, ‘description’ and ‘text’ are translated based on the
document language.

   The ‘FirstInFile’ direction variants are associated with the same
strings as the direction they are prepended to (see FirstInFile
direction variant).  For example ‘FirstInFileNodeNext’ is associated
with the same strings as ‘NodeNext’.

5.3 Direction Strings Customization
===================================

The direction strings are used in the default case in navigation panel
formatting, therefore replacing their values is a way to customize
headers.  They are also used in the About special unit formatting (see
About Special Output Unit Customization).  The direction strings can be
customized with ‘texinfo_register_direction_string_info’:

 -- Function: texinfo_register_direction_string_info ($direction, $type,
          $converted_string, $string_to_convert, $context)
     $DIRECTION is a direction (see Directions), $TYPE is the type of
     string (see Direction Strings).  The other arguments are optional.
     $CONTEXT is ‘normal’ or ‘string’.  See Init File Expansion
     Contexts.  If $context is ‘undef’, the ‘normal’ context is assumed.

     $CONVERTED_STRING is the string, already converted to HTML that is
     used for the specified context.  If the ‘normal’ context
     $CONVERTED_STRING only is specified, the same string will be used
     for the ‘string’ context.

     Alternatively, $STRING_TO_CONVERT can be specified to set the
     string to the corresponding Texinfo code after translation and
     conversion to HTML. In that case, the context is ignored, as it
     will be set at the time of the conversion.

     $STRING_TO_CONVERT is ignored for special strings that do not need
     to be translated and cannot contain Texinfo @-commands
     (‘accesskey’, ‘rel’ and ‘example’).  $STRING_TO_CONVERT is also
     ignored if $CONVERTED_STRING is set for any context.

   For example, to set the ‘Up’ ‘button’ to be translated as ‘Higher’,
use:
     texinfo_register_direction_string_info('Up', 'button', undef, 'Higher');

5.4 Simple Navigation Panel Customization
=========================================

The “navigation panel” is the line of links (and labels) that typically
appears at the top of each node, so that users can easily get to the
next node, the table of contents, and so on.  It can be customized
extensively.

   You can set the ‘ICONS’ customization variable to use icons for the
navigation panel.  Setting ‘ICONS’ is necessary but not sufficient to
get icons for direction buttons since no button image is specified in
the default case.  The ‘ACTIVE_ICONS’ and ‘PASSIVE_ICONS’ customization
variables need to be set in addition:

‘ACTIVE_ICONS’
‘PASSIVE_ICONS’
     Hash references with output unit directions as key (see Directions)
     and button image icons as values.  ‘ACTIVE_ICONS’ is used for
     directions actually linking to an output unit, and ‘PASSIVE_ICONS’
     are used if there is no output unit to link to.  The button images
     are interpreted as URLs.

   Several arrays and hashes enable even more precise control over the
navigation panel buttons and their display.  They can be set as
customization variables with ‘texinfo_set_from_init_file’.  See Setting
Main Program String Variables.

   The following customization variables arrays determine the buttons
present in the various navigation panels:

‘SECTION_BUTTONS’
     Specifies the navigation panel buttons present at the beginning of
     sectioning elements in the case of section navigation being enabled
     or if split at nodes.  Specifies the navigation panel buttons
     present at the page header if split at section and there is no
     section navigation.

‘SECTION_FOOTER_BUTTONS’
‘CHAPTER_FOOTER_BUTTONS’
‘NODE_FOOTER_BUTTONS’
     These arrays specify the navigation panel buttons present in the
     page footer when the output is split at sections, chapters or
     nodes, respectively.

‘CHAPTER_BUTTONS’
     Specifies the buttons appearing at the page header if split at
     chapters and there is no section navigation.

‘MISC_BUTTONS’
     Specifies the buttons appearing at the beginning of special output
     units and, if the output is split, at the end of such units.

‘LINKS_BUTTONS’
     Used for ‘’ elements if they are output in the HTML ‘’.

‘TOP_BUTTONS’
‘TOP_FOOTER_BUTTONS’
     Specifies the buttons used in the top output unit (see Output
     Units).  ‘TOP_BUTTONS’ buttons are used for the header and
     ‘TOP_FOOTER_BUTTONS’ are used for the footer.

   Each array specifies which buttons are included, and how they are
displayed.  Each array item is associated with a button of the
navigation panel from left to right.  The meaning of the array item
values is the following:

_string with an output unit direction_
     If icons are not used, the button is a link to the corresponding
     output unit whose text is the ‘text’ direction string (see
     Direction Strings), surrounded by ‘[’ and ‘]’.  If the direction is
     ‘ ’, the ‘[’ and ‘]’ are omitted.

     If icons are used, the button is an image whose file is determined
     by the value associated with the output unit direction in the
     ‘ACTIVE_ICONS’ variable hash if the link leads to an output unit,
     or in the ‘PASSIVE_ICONS’ variable hash if there is no output unit
     to link to.  If there is a link to the output unit, the icon links
     to that output unit.  The button name and button description are
     given as HTML attributes to have a textual description of the icon.
     The corresponding strings correspond to the ‘button’ direction
     string for the button name and the ‘description’ for a more
     detailed description (see Direction Strings).

_function reference_
     The functions is called with one arguments, the converter object.
     The function should return two scalars, the button text and a
     boolean set if a delimiter is desired before the button.

_scalar reference_
     The scalar value is printed.

_array reference of length 2_
     Here, the first array item should be a an output unit direction.
     The text of the link depends on the second array item.

     _reference to a text string_
          A link to the output unit associated with the output unit
          direction is generated with the corresponding text used for
          the text link.

     _reference to a function_
          The functions is called with three arguments, the converter
          object, the output unit direction and the source Texinfo tree
          element (possibly undef).  The function should return two
          scalars, the button text and a boolean set if a delimiter is
          desired before the button.

   No delimiter is printed before the first button.  Leading space
buttons mixed with directions not found may be omitted of the navigation
panel output.

   If the customization variable ‘USE_ACCESSKEY’ is set, the ‘accesskey’
attribute is used in navigation.  The ‘accesskey’ direction string is
then used for the ‘accesskey’ attributes (see Direction Strings).

   Similarly, if the ‘USE_REL_REV’ customization variable is set, the
‘rel’ attribute is used in navigation.  In that case the ‘rel’ direction
string is used for the ‘rel’ attribute (see Direction Strings).

6 User Defined Functions
************************

Getting beyond the customization described previously requires writing
some functions and registering those functions such that they are called
for the conversion.  This allows dynamic redefinition of functions used
to produce output.

6.1 User Defined Functions are Registered
=========================================

User defined functions are always passed as a code reference to a
registering function, together with a string describing what the
function formats.  In the following made up example,
‘my_formatting_function’ is passed as a function reference
‘\&my_formatting_function’ to the fictitious registering function
‘texinfo_register_some_formatting’, with the string specifying the
formatting done by the function being ‘format_thing’:

     sub my_formatting_function {
       my $arg1 = shift;
       my $arg2 = shift;
       # prepare $formatted_text
       ...
       return $formatted_text;
     }

     texinfo_register_some_formatting ('format_thing', \&my_formatting_function);

   As such functions are defined by a reference name associated with a
string we will always use the string in function prototypes.  For the
function arguments we will use ‘\@array’ to indicate a reference to an
array (a.k.a. list, in Perl terminology), ‘\%hash’ for a reference to a
hash and ‘\&function’ for a reference on a function.

   To illustrate these conventions, here is the prototype for the
function associated with ‘format_thing’:

 -- Function Reference: $TEXT format_thing ($ARG1, \@ARG2)
     A function reference associated with ‘format_thing’ has a first
     argument $ARG1, a second argument a reference to an array \@ARG2,
     and returns the formatted text $TEXT.

6.2 Converter Object and Conversion Functions
=============================================

The first argument of most, if not all user defined function is a
converter object.  This object gives access to methods to get
information on the conversion context and to methods useful for the
conversion, both as an HTML converter and as a generic
‘Texinfo::Convert::Converter’ (see
(texi2any_internals)Texinfo::Convert::Converter Helper methods).  The
converter can be used for error reporting by using
‘Texinfo::Convert::Converter’ methods.  See Error Reporting in User
Defined Functions on error reporting.  The converter can also be used
for in-document strings translation.  See Translations in Output and
Customization on translated strings in output.

7 Error Reporting, Customization and Paths Manipulation with Converter
**********************************************************************

Some tasks common to all the user-defined functions related to error
reporting, customization variables handling and paths and URL
manipulation are described in this chapter.

7.1 Error Reporting in User Defined Functions
=============================================

To report an error or a warning in a user defined function, use the
methods of ‘Texinfo::Convert::Converter’ through a converter object (see
Converter Object and Conversion Functions).

   To report a warning or an error not specific of an element
conversion, use ‘converter_document_warn’ or ‘converter_document_error’:

 -- Function: $CONVERTER->converter_document_error ($text,
          $continuation)
 -- Function: $CONVERTER->converter_document_warn ($text, $continuation)
     Register a document-wide error or warning.  $TEXT is the error or
     warning message.

     The optional $CONTINUATION argument, if set, conveys that the
     message is a continuation of the previous registered message.

   To report a warning or an error in element conversion, use
‘converter_line_warn’ or ‘converter_line_error’
 -- Function: $CONVERTER->converter_line_error ($text, \%location_info,
          $continuation)
 -- Function: $CONVERTER->converter_line_warn ($text, \%location_info,
          $continuation)
     Register a warning or an error.  $TEXT is the text of the error or
     warning.  The \%LOCATION_INFO holds the information on the error or
     warning location.  The \%LOCATION_INFO reference on hash may be
     obtained from Texinfo elements ‘source_info’ keys.

     The optional $CONTINUATION argument, if set, conveys that the
     message is a continuation of the previous registered message.

   Note that registering an error does not stop the processing of the
Texinfo tree.

   See (texi2any_internals)Texinfo::Convert::Converter Registering error
and warning messages for the converter module documentation on errors
and warning messages registration.

7.2 Setting and Getting Conversion Customization Variables
==========================================================

The customization variables values set during the conversion process may
be different from the main program customization variables.  The general
rule is that variables set in the main program, in particular from init
files, are passed to the converter.  Some variables, however, only
appear in the converter.  Some variables are also set in the converter
based on the main program customization variables.  Finally, some
variables should be set or reset during conversion, in particular when
converting the tree representing the Texinfo document, when expanding
the tree element corresponding to @-commands associated with
customization variables (see (texinfo)Customization Variables for
@-Commands).

   The functions described here should be used in user defined
functions, but should not be used out of functions.  Conversely, the
similar functions used to set customization variables from init files
without a converter should not be used in functions, but should be used
out of functions in init files (see Managing Customization Variables).

   To get the value of a variable in a converter ‘$converter’, the
function is ‘get_conf’:

 -- Function: $RESULT = $CONVERTER->get_conf ($VARIABLE_NAME)
     $VARIABLE_NAME is the name of the variable; its value in the
     converter $CONVERTER (possibly ‘undef’) is returned.

   For example:

     my $footnotestyle = $converter->get_conf('footnotestyle');

   To set a variable in a converter ‘$converter’, the function is
‘set_conf’:

 -- Function: $CONVERTER->set_conf ($variable_name, $variable_value)
     $VARIABLE_NAME is the name of the variable; its value in the
     converter $CONVERTER is set to $VARIABLE_VALUE.  The $VARIABLE_NAME
     value will not be overidden if it was set from the command line or
     from an init file.

   For example:

     $converter->set_conf('footnotestyle', 'separate');

   Some customization variables, in particular those associated with
@-commands, can be reset to the value they had before starting the
conversion.  For example, they are reset in order to obtain their value
before the conversion.  Thet are also reset to the value they had before
starting the conversion when their value at the end of the preambule or
at the end of the document is needed, but there are no @-commands at
those locations in the Texinfo manual.  If a value set by ‘set_conf’ is
intended to be found when the customization variable value is reset,
‘set_conf’ should be called early.  For example, when called from a
user-defined function called at different stage, it should be called in
the ‘setup’ stage (see Init File Calling at Different Stages).

   The values set in converter with ‘set_conf’ will not override
command-line set customization variables, nor variables set early in
init files.  This is the expected behaviour, in particular when the
values are set from the document.  In the rare cases when overriding the
customization would be needed, the ‘force_conf’ function can be used:

 -- Function: $CONVERTER->force_conf ($variable_name, $variable_value)
     $VARIABLE_NAME is the name of the variable; its value in the
     converter $CONVERTER is set to $VARIABLE_VALUE, overriding any
     previous value.

7.3 Encoding and Decoding File Path Strings
===========================================

7.3.1 Encoding File Path Strings
--------------------------------

In general, the strings in the customization functions are character
strings.  For most purposes, this is right, and the encoding in output
files is taken care of by the converter.  Operations on directories and
file names, however, such as the creation of a directory or the opening
of a file require binary strings.

   To encode file names consistently with file name encoding used in the
conversion to HTML, there is a function ‘encoded_output_file_name’:

 -- Function: ($ENCODED_NAME, $ENCODING) =
          $CONVERTER->encoded_output_file_name ($CHARACTER_STRING_NAME)
     Encode $CHARACTER_STRING_NAME in the same way as other file name
     are encoded in the converter.  Use ‘OUTPUT_FILE_NAME_ENCODING’
     value for the file name encoding if set.  Otherwise, if
     ‘DOC_ENCODING_FOR_OUTPUT_FILE_NAME’ is set the input Texinfo
     document encoding is used, if unset, the default, files names are
     encoded using the current locale (see (texinfo)Global Customization
     Variables).  Return the encoded name and the encoding used to
     encode the name.

   There is also a similar function for the input file names encoding,
‘encoded_input_file_name’, which uses ‘INPUT_FILE_NAME_ENCODING’ and
‘DOC_ENCODING_FOR_INPUT_FILE_NAME’ and is less likely to be useful.

   When calling external commands, the command line arguments should
also be encoded.  To do similarly with other codes, the customization
variable ‘MESSAGE_ENCODING’ should be used.  Already encoded file names
may be used.  For example

     use Encode qw(encode);

     ....

     my ($encoded_file_path, $encoding)
       = $converter->encoded_output_file_name($file_name);

     my $fh = open($encoded_file_path);

     .....

     my $call_start = "command --set '$action' ";
     my $encoding = $converter->get_conf('MESSAGE_ENCODING');
     if (defined($encoding)) {
       $encoded_call_start = encode($encoding, $call_start);
     } else {
       $encoded_call_start = $call_start;
     }
     my $encoded_call = $encoded_call_start . $encoded_file_path;
     my $call = $call_start . $file_name;
     if (system($encoded_call)) {
      $converter->document_error($converter,
          sprintf(__("command did not succeed: %s"),
                 $call));
     }

7.3.2 Decoding File Path Strings
--------------------------------

The binary strings that could be accessed correspond to the
customization variables strings or arrays ‘INCLUDE_DIRECTORIES’,
‘CSS_FILES’, ‘MACRO_EXPAND’ and ‘INTERNAL_LINKS’.  If they need to be
decoded into character strings, for example to appear in error messages,
it is possible to use the ‘COMMAND_LINE_ENCODING’ customization variable
value as encoding name to mimic how the decoding of these strings from
the command line is done in the main program and in the converters.  See
(texinfo)Global Customization Variables.

   For example:
     my $macro_expand_fname = $converter->get_conf('MACRO_EXPAND');
     my $encoding = $converter->get_conf('COMMAND_LINE_ENCODING');
     if (defined($encoding)) {
       $macro_expand_fname = Encode::decode($encoding, $macro_expand_fname);
     }

   More information on Perl and encodings in perlunifaq
(https://perldoc.perl.org/perlunifaq).

7.4 Protection of URLs
======================

URLs need to be "percent-encoded" to protect non-ASCII characters,
spaces and other ASCII characters.  Percent-encoding also allows to have
characters be interpreted as part of a path and not as characters with a
special role in URLs.  For example, ‘?’ has a special role in URLs as it
starts a query string.  To have it considered as part of a file path,
instead of a marker of the beginning of a query, it needs to be percent
encoded.

   Convenience functions are provided for URL protection.  To protect a
whole URL, in which characters with a special role in URL are left as
is, use ‘url_protect_url_text’.  To protect file path in URL, including
characters with a special role in URLs, use ‘url_protect_file_text’.

 -- Function: $PROTECTED_URL =
          $CONVERTER->url_protect_url_text($INPUT_STRING)
     Percent-encode $INPUT_STRING, leaving as is all the characters with
     a special role in URLs, such as ‘:’, ‘/’, ‘?’, ‘&’, ‘#’ or ‘%’ (and
     a few other).  HTML reserved characters and form feeds protected
     are also protected as entities (see ‘format_protect_text’: Basic
     Formatting Customization).  This is typically used on complete URLs
     pointing to diverse internet resources, such as the ‘@url’ URL
     argument.

     for example
          return $converter->html_attribute_class('a', ['myurl'])
           .' href="'.$converter->url_protect_url_text($url)."\">$text";

 -- Function: $PROTECTED_PATH =
          $CONVERTER->url_protect_file_text($INPUT_STRING)
     Percent-encode $INPUT_STRING leaving as is character appearing in
     file paths only, such as ‘/’, ‘.’, ‘-’ or ‘_’.  All the other
     characters that can be percent-protected are protected, including
     characters with a special role in URLs.  For example, ‘?’, ‘&’ and
     ‘%’ are percent-protected.  HTML reserved characters and form feeds
     protected are also protected as entities (see
     ‘format_protect_text’: Basic Formatting Customization).  This is
     typically used on file names corresponding to actual files, used in
     the path portion of an URL, such as the image file path in
     ‘@image’.

     For example
          $converter->html_attribute_class('img', [$cmdname])
             . ' src="'.$converter->url_protect_file_text($image_file)."\");

8 Customizing Output-Related Names
**********************************

It is possible to control both output file names and target identifiers
in detail.

   User defined functions customizing file names and targets are
registered with ‘texinfo_register_file_id_setting_function’:

 -- Function: texinfo_register_file_id_setting_function ($customized,
          \&handler)
     $CUSTOMIZED is a string describing what the function should set.
     \&HANDLER should be a reference on the user defined function.  The
     different functions that can be registered have different arguments
     and return values.

   The different possibilities for the customized information are
explained in the next sections.

   For example:
     sub my_node_file_name($$$) {
       my ($converter, $element, $filename) = @_;
       # ....
       return $node_file_name
     }

     texinfo_register_file_id_setting_function('node_file_name',
                                               \&my_node_file_name);

8.1 Customizing Output File Names
=================================

You can specify the output file or directory, intermediate directories
and file extension with customization variables (see (texinfo)File Names
and Links Customization for HTML).

   Two function references registered with
‘texinfo_register_file_id_setting_function’ enable further
customization.  The first, ‘node_file_name’ is used to customize the
nodes files names.

 -- Function Reference: $NODE_FILE node_file_name ($CONVERTER,
          \%NODE_ELEMENT, $FILE_NAME)
     $CONVERTER is a converter object.  \%NODE_ELEMENT is the Texinfo
     tree element corresponding to the ‘@node’.  $FILE_NAME is the node
     file name that has been already set.  The function should return
     the node file name ($NODE_FILE).

   The other function reference, ‘unit_file_name’, is used to customize
the file names associated with each normal output unit (see Output
Units).

 -- Function Reference: ($FILE, $PATH) unit_file_name ($CONVERTER,
          \%OUTPUT_UNIT, $FILE_NAME, $FILE_PATH)
     $CONVERTER is a converter object.  \%OUTPUT_UNIT is the output
     unit.  $FILE_NAME is the file name that has been already set.
     $FILE_PATH is the file path that has been already set.  $FILE_PATH
     is ‘undef’ if the file is relative to the output directory, which
     is the case if the output is split.  The function should return the
     file name for the output unit, $FILE, and the file path for the
     output unit, $PATH, which should be ‘undef’ if the file path is to
     be constructed by putting $FILE in the destination directory.

   In the user defined functions, the information that an output unit is
associated with ‘@top’ or ‘@node Top’ may be determined with:
     $converter->unit_is_top_output_unit(\%output_unit);

   The information on tree elements may be interesting for those
functions (see Texinfo Tree Elements in User Defined Functions).  The
‘extra’ key ‘associated_section’ of a node element and ‘associated_node’
of a sectioning command element may also be useful.

   The file name associated with a sectioning command is set together
with the target, and is described in the next section.

8.2 Customizing Output Target Names
===================================

Similar to file names, so-called target and id names may be set.  The
“id” is placed where the item is located, while the “target” is used to
construct references to that item.  The id and target are the same.  A
function used to set both target and file name is also described here.

   The following function reference is for target items (nodes, anchors,
floats), including for external manuals:

 -- Function Reference: $TARGET label_target_name ($CONVERTER,
          $NORMALIZED, \%ELEMENT, $DEFAULT_TARGET)
     $CONVERTER is a converter object.  $NORMALIZED is the normalized
     node name, \%ELEMENT is a reference on a Texinfo tree command label
     element whose contents correspond to the node name.
     $DEFAULT_TARGET is the target that has been already set.  The
     function should return the target ($TARGET).

   The element corresponding to the label can be found with
‘label_command’ if the label corresponds to an internal reference (see
Target Tree Element Link):
     my $element;
     $element = $converter->label_command($normalized)
       if (defined($normalized));

   For sectioning commands, in addition to the sectioning command
target, targets for the sectioning command in table of contents and in
short table of contents are needed.  The following function reference is
for sectioning command related target and file name:

 -- Function Reference: ($TARGET, $TARGET_CONTENTS,
          $TARGET_SHORTCONTENTS, $FILE) sectioning_command_target_name
          ($CONVERTER, \%SECTION_ELEMENT, $DEFAULT_TARGET,
          $DEFAULT_TARGET_CONTENTS, $DEFAULT_TARGET_SHORTCONTENTS,
          $FILE_NAME)
     $CONVERTER is a converter object.  \%SECTION_ELEMENT is the Texinfo
     element corresponding to the sectioning command.

     $DEFAULT_TARGET, $DEFAULT_TARGET_CONTENTS and
     $DEFAULT_TARGET_SHORTCONTENTS are the targets that have been
     already set for the sectioning element and the sectioning element
     in table of contents and in short table of contents.  $FILE_NAME is
     the file name that has been already set.

     The function should return the $TARGET, $TARGET_CONTENTS and
     $TARGET_SHORTCONTENTS sectioning element target and sectioning
     element in table of contents and in short table of contents
     targets, and the file name for the sectioning element ($FILE).

8.3 Customizing External Node Output Names
==========================================

In the default case references to external nodes are set as described in
the Texinfo manual (see (texinfo)HTML Xref).  You can specify external
node manuals URLs in cross-references customization files (see
(texinfo)HTML Xref Configuration).  You can also set a base directory,
the Top node file target, the extension and other overall references to
external nodes formatting with customization variables (see
(texinfo)File Names and Links Customization for HTML).

   If the external reference is not already ignored because of
‘IGNORE_REF_TO_TOP_NODE_UP’, two function references give full control
over the external node target output names, with
‘external_target_split_name’ if the external target is considered to be
split, and ‘external_target_non_split_name’ if the external target is
non split.

 -- Function Reference: ($TARGET, $HOST_DIRECTORY, $FILE_NAME)
          external_target_split_name($CONVERTER, $NORMALIZED, \%ELEMENT,
          $DEFAULT_TARGET, $DEFAULT_HOST_DIRECTORY, $DEFAULT_FILE_NAME)
     $CONVERTER is a converter object.  $NORMALIZED is the normalized
     node name, \%ELEMENT is a reference on an element containing
     information on the external node.

     $DEFAULT_TARGET, $DEFAULT_HOST_DIRECTORY and $DEFAULT_FILE_NAME are
     the target, host and directory URL part and file name URL part that
     have been already set.

     The function should return the $TARGET, $HOST_DIRECTORY and
     $FILE_NAME URL parts.

 -- Function Reference: ($TARGET, $HOST_DIRECTORY_FILE)
          external_target_non_split_name($CONVERTER, $NORMALIZED,
          \%ELEMENT, $DEFAULT_TARGET, $DEFAULT_HOST_DIRECTORY_FILE)
     $CONVERTER is a converter object.  $NORMALIZED is the normalized
     node name, \%ELEMENT is a reference on an element containing
     information on the external node.

     $DEFAULT_TARGET is the target and $DEFAULT_HOST_DIRECTORY_FILE is
     the host and file name part of the URL that have been already set.

     The function should return the $TARGET and $HOST_DIRECTORY_FILE URL
     parts.

8.4 Customizing Special Elements Output Names
=============================================

For special output units file and target (see Output Units), the
function reference is:

 -- Function Reference: ($TARGET, $FILE) special_unit_target_file_name
          ($CONVERTER, \%OUTPUT_UNIT, $DEFAULT_TARGET, $FILE_NAME)
     $CONVERTER is a converter object.  \%OUTPUT_UNIT is the special
     output unit hash.  $DEFAULT_TARGET is the target that has been
     already set, and $FILE_NAME is the file name that has been already
     set.  The function should return the $TARGET and $FILE.

   To determine the variety of the special output unit processed, the
output unit ‘special_unit_variety’ hash key can be used.  See Table
16.1: Special Units Varieties.

9 Init File Calling at Different Stages
***************************************

Arbitrary user-defined functions may be called during conversion.  This
could be used, for example, to initialize variables and collect some
@-commands text, and doing clean-up after the Texinfo tree conversion.

   There are four stages for user defined functions:
‘setup’
     Called right after completing main program customization
     information with converter specific customization information, but
     before anything else is done, including collecting the output files
     names and registering the customization variables pre-conversion
     values.

‘structure’
     Called after setting and determining information on CSS, output
     files and directories, document structure and associated
     directions, file names, labels and links for nodes, sectioning
     commands, special output units, footnotes and index entries.

‘init’
     Called after some gathering of global information on the document,
     such as titles, copying comment and document description, which
     require some conversion of Texinfo, right before the main output
     processing.  At that point most of the information available from
     the converter is set (see Converter General Information).

‘finish’
     Called after output generation is finished.

   The function used to register a user defined functions is
‘texinfo_register_handler’:

 -- Function: texinfo_register_handler ($stage, \&handler, $priority)
     $STAGE is one of the stages described just above.  \&HANDLER is a
     reference on the user defined function.  $PRIORITY is an optional
     priority class.

     To determine the order of user defined functions calls, the
     priority classes are sorted, and within a priority class the order
     is the order of calling ‘texinfo_register_handler’.

   The call of the user defined functions is:

 -- Function Reference: $STATUS stage_handler ($CONVERTER, $DOCUMENT,
          $STAGE)
     $CONVERTER is a converter object.  $DOCUMENT is the Texinfo parsed
     ‘Texinfo::Document’ document.  $STAGE is the current stage.

     If $STATUS is not 0 it means that an error occured.  If $STATUS is
     positive, the user defined functions should have registered an
     error or warning message, for example with ‘document_error’ (see
     Error Reporting in User Defined Functions).  If $STATUS is
     negative, the converter will emit a non specific error message.  If
     the $STATUS is lower than -‘HANDLER_FATAL_ERROR_LEVEL’ or higher
     than ‘HANDLER_FATAL_ERROR_LEVEL’, the processing stops immediately.
     Default value for ‘HANDLER_FATAL_ERROR_LEVEL’ is 100.

10 Formatting HTML Output
*************************

HTML output formatting in user-defined code should take into account the
conversion context, can access converter information and use converter
functions to convert Perl Texinfo trees.  There are also several
conventions and constraints that user defined code should abide to when
formatting HTML, in order to comply with customization option values,
avoid modifying structures that should not be modified, and also to have
information correctly registered in the converter.

   Formatting of HTML output should be used in formatting functions (see
Customization and Use of Formatting Functions), tree elements conversion
functions (see Tree Element Conversion Customization) and output units
conversion functions (see Output Units Conversion Functions) described
later on.  Tree elements and output units conversion functions can also
be used to output HTML, how to retrieve the corresponding function
references and call those functions is also described with the functions
customization.

10.1 Specific HTML Constructs Formatting Functions
==================================================

A few specific HTML constructs should be formatted using particular
functions: elements with classes, "void elements" without end tag and
non breaking spaces.

10.1.1 Formatting HTML Element with Classes
-------------------------------------------

Opening an HTML element with one or more classes should always be done
through ‘html_attribute_class’:

 -- Function: $ELEMENT_OPEN = $CONVERTER->html_attribute_class
          ($HTML_ELEMENT, \@CLASSES)
     Formats the beginning of an HTML element $HTML_ELEMENT.  \@CLASSES
     is the list of classes for this element.  The element opening
     returned does not include the end of element symbol ‘>’ such that
     it is possible to add more attributes.

     If the HTML element is ‘span’, an empty string is returned if there
     is also no attribute.

     If ‘NO_CSS’ is set, no attribute is set for the element.  Otherwise
     a ‘class’ attribute is set based on \@CLASSES .  If
     ‘INLINE_CSS_STYLE’ is set, a CSS style attribute based on CSS
     element class rules is also added (see (texinfo)HTML CSS).
     Otherwise the information that the element class was seen is
     registered by the converter.

   Examples of use:
     my $open = $converter->html_attribute_class('span', ['math-arg']);
     my $arg_result = $open.'>'.$arg.''
       if ($open ne '');

     my $result = $converter->html_attribute_class('em', [$cmdname, 'jax_p'])
        . '>' . $arg_result . '';

10.1.2 Closing Lone HTML Element
--------------------------------

HTML elements with an opening element, but no closing element, such as
‘’ or ‘’, also called “void elements” should be closed by
calling ‘close_html_lone_element’:

 -- Function: $HTML_ELEMENT = $CONVERTER->close_html_lone_element
          ($UNCLOSED_ELEMENT)
     Close the $UNCLOSED_ELEMENT, which can contain attributes, by
     prepending ‘>’ or ‘/>’ depending on the ‘USE_XML_SYNTAX’
     customization variable value (see (texinfo)HTML Features
     Customization).

   Examples of use:
     $description = $converter->close_html_lone_element(
         "get_info('non_breaking_space');
     my $result = '' .$non_breaking_space. '';
   In that case, there is nothing more to do.

   If a ‘ ’ can directly appear in formatted code, however, the
corresponding text should be in a call to
‘substitute_html_non_breaking_space’, to take into account
‘OUTPUT_CHARACTERS’ and ‘USE_NUMERIC_ENTITY’ customization variables:

 -- Function: $SUBSTITUTED_TEXT =
          $CONVERTER->substitute_html_non_breaking_space
          ($FORMATTED_TEXT)
     Substitute ‘ ’ according to customization variables values.

   See (texinfo)HTML Features Customization for ‘OUTPUT_CHARACTERS’ and
‘USE_NUMERIC_ENTITY’ description.

10.2 Converter General Information
==================================

Some general information is available from the converter.  This
information should not change during conversion.

   To determine if an output format such as ‘html’ or ‘tex’ is expanded
(see (texinfo)Conditional Commands), use ‘is_format_expanded’:

 -- Function: $IS_FORMAT_EXPANDED = $CONVERTER->is_format_expanded
          ($FORMAT)
     Return true if format $FORMAT is expanded, according to
     command-line and init file information.

   The main method to get information from the converter is ‘get_info’:

 -- Function: $INFO = $CONVERTER->get_info ($ITEM)
     Return information on $ITEM.

   The available information is about:
‘copying_comment’
     Text appearing in ‘@copying’ with all the Texinfo commands put into
     comments (see (texinfo)@copying).

‘destination_directory’
     Destination directory for the output files.  It is common to use
     that string in directory or file paths with functions requiring
     binary strings.  In that case the character string needs to be
     encoded.  See Encoding File Path Strings.

‘document’
     The ‘Texinfo::Document’ parsed Texinfo document being converted.
     Some information relevant for conversion is available from the
     document using function accessors:

     ‘floats_information’
          Information on floats.  See
          Texinfo::Document::floats_information:
          (texi2any_internals)Texinfo::Document $float_types =
          floats_information($document).

     ‘global_commands_information’
          Global commands information.  See
          Texinfo::Document::global_commands_information:
          (texi2any_internals)Texinfo::Document $commands =
          global_commands_information($document).

     ‘global_information’
          Diverse information.  See
          Texinfo::Document::global_information:
          (texi2any_internals)Texinfo::Document $info =
          global_information($document).

     ‘indices_information’
          Information about defined indices, merged indices and index
          entries.  See Texinfo::Document::indices_information:
          (texi2any_internals)Texinfo::Document $indices_information =
          $document->indices_information().

     ‘sections_list’
          List of the sectioning commands in the document.

     See (texi2any_internals)Texinfo::Document Getting document
     information on information available from the document.

‘document_name’
     Base name of the document.  It is common to use that string in in
     directory or file paths with functions requiring binary strings.
     In that case the character string needs to be encoded.  See
     Encoding File Path Strings.

‘documentdescription_string’
     ‘@documentdescription’ argument converted in a string context (see
     (texinfo)@documentdescription).  See Init File Expansion Contexts.

‘expanded_formats’
     Information on output formats such as ‘html’ or ‘tex’ expansion
     (see (texinfo)Conditional Commands).  An hash reference with format
     names as key and a true value as value if the format is expanded,
     according to command-line and init file information.

     ‘expanded_formats’ information should be consistent with
     ‘is_format_expanded’ call result (see is_format_expanded).

‘jslicenses’
     An hash reference with categories of javascript used in the
     document as keys.  The corresponding values are also hashes with
     file names as keys and with array references as values.  The array
     references contain information on each of the file licences, with
     content
       1. licence name
       2. license URL
       3. file name or source of file

‘line_break_element’
     HTML line break element, based on ‘
’, also taking into account
     ‘USE_XML_SYNTAX’ customization variable value.

‘non_breaking_space’
     Non breaking space, can be ‘ ’, but also a non breaking space
     character or the corresponding numeric entity based on
     ‘OUTPUT_CHARACTERS’ and ‘USE_NUMERIC_ENTITY’ customization
     variables values.  See Substituting Non Breaking Space.

‘paragraph_symbol’
     Paragraph symbol, can be ‘¶’, but also the corresponding
     numeric entity or encoded character based on ‘OUTPUT_CHARACTERS’
     and ‘USE_NUMERIC_ENTITY’ customization variables values.  See
     (texinfo)HTML Features Customization.

‘title_string’
‘title_tree’
‘simpletitle_tree’
‘simpletitle_command_name’
     Some information is deduced from the title commands: “simpletitle”
     reflects ‘@settitle’ vs. ‘@shorttitlepage’, and “title” is
     constructed by trying all the title-related commands, including
     ‘@top’ and ‘@titlefont’, in the top element.

     ‘title_tree’ is a Texinfo tree corresponding to the title,
     ‘title_string’ is the result of the conversion in a string context
     (see Init File Expansion Contexts).  ‘simpletitle_tree’ is a
     Texinfo tree corresponding to the simpletitle, and
     ‘simpletitle_command_name’ is the @-command name used for the
     simpletitle, without the leading @.

‘title_titlepage’
     The formatted title, possibly based on ‘@titlepage’, or on
     ‘simpletitle_tree’ and similar information, depending on
     ‘SHOW_TITLE’ and ‘USE_TITLEPAGE_FOR_TITLE’ customization variables
     in the default case (see (texinfo)HTML Output Structure
     Customization).

   See Customization of CSS Rules Imports and Selectors for an
explanation on getting information on CSS.

10.3 Getting Conversion Context
===============================

Some dynamically generated information should be used from the
converter, in particular the expansion context (see Init File Expansion
Contexts).

10.3.1 Conversion in String Context
-----------------------------------

Conversion and formatting functions should check if in string context to
avoid using HTML elements in formatting when in string context.  See
Init File Expansion Contexts.

   To determine if in string context, the functions is ‘in_string’:

 -- Function: $IN_STRING = $CONVERTER->in_string ()
     Return true if in string context.

   Example of use:

     if ($converter->in_string()) {
       return "$mail_string ($text)";
     } else {
       return $converter->html_attribute_class('a', [$cmdname])
                           ." href=\"mailto:$mail_string\">$text";
     }

10.3.2 Conversion in Preformatted Context
-----------------------------------------

Conversion and formatting functions should test if in preformatted
context to convert accordingly.  See Init File Expansion Contexts.

   To determine if in preformatted context, the functions is
‘in_preformatted_context’:

 -- Function: $IN_PREFORMATTED = $CONVERTER->in_preformatted_context ()
     Return true if in preformatted context.

   Another function tells if within a preformatted command:
 -- Function: $INSIDE_PREFORMATTED = $CONVERTER->inside_preformatted ()
     Return true if within a preformatted block command such as
     ‘@preformatted’, ‘@format’.

     It is not exactly the same as preformatted context, for instance
     menu comments are in preformatted context even if not in a
     preformatted block command.

   If in preformatted context, it is possible to get preformatted
@-commands and preformatted types nesting with
‘preformatted_classes_stack’:

 -- Function: \@PREFORMATTED_NESTING =
          $CONVERTER->preformatted_classes_stack ()
     Returns an reference on an array containing the block preformatted
     @-commands such as ‘@example’, ‘@display’ or ‘@menu’ names without
     the leading @ and the HTML attribute class preformatted container
     names, in order of appearance.

   The ‘%Texinfo::Commands::preformatted_code_commands’ hash can be used
to determine if a preformatted command is to be formatted as code (see
(texi2any_internals)Texinfo::Commands %preformatted_code_commands).

     my $pre_classes = $converter->preformatted_classes_stack();
     foreach my $pre_class (@$pre_classes) {
       if ($Texinfo::Commands::preformatted_code_commands{$pre_class}) {
         $result = '' .$result. '';
         last;
       }
     }

   See Simple Customization of Containers on customizing containers
preformatted class.

10.3.3 Other Dynamic Information
--------------------------------

To get the current output unit being converted, use
‘current_output_unit’:
 -- Function: $OUTPUT_UNIT = $CONVERTER->current_output_unit ()
     Return the output unit being converted, or ‘undef’ if there is no
     output unit.

   To get the file name of the current output unit being converted, use
‘current_filename’:
 -- Function: $FILENAME = $CONVERTER->current_filename ()
     Return the file name of the current output unit being converted.

   To get the text filling and alignement context, determined by
‘@flushleft’ or ‘@center’, use ‘in_align’:

 -- Function: $ALIGN_CONTEXT = $CONVERTER->in_align ()
     If the alignment context is the default alignement context, return
     ‘undef’.  Otherwise, returns the command name of the alignment
     context.

   To determine if the conversion is in a context converted multiple
times, use ‘in_multiple_conversions’:
 -- Function: $MULTIPLE_CONVERSION = $CONVERTER->in_multiple_conversions
          ()
     Return true if the Texinfo tree being converted is converted
     multiple times and the current conversion is not the main
     conversion.

     For example, return true if a node name is converted as part of a
     direction string formating in a navigation panel, which is not the
     main expansion of the ‘@node’.  The main ‘@node’ element expansion
     occurs where the @-command is located.

   To determine if the a mutiple expansion context is set, use
‘in_multi_expanded’:
 -- Function: $MULTI_EXPANDED_CONTEXT_INFORMATION =
          $CONVERTER->in_multi_expanded ()
     Return a string representing the multiple expanded context, or
     ‘undef’ if not in a multiple expanded context.

     A multiple expanded context implies to be in multiple conversions.
     However, it is possible to be in multiple conversions without being
     in a multiple expanded context, as a multiple expanded context
     needs to be set explicitly, and is not always needed.

   To get the current paragraph and preformatted number, use
‘paragraph_number’ or ‘preformatted_number’:

 -- Function: $NUMBER = $CONVERTER->paragraph_number ()
 -- Function: $NUMBER = $CONVERTER->preformatted_number ()
     Return the current paragraph or preformatted container number in
     the current formatting context.

   To get the topmost block @-command being converted, use
‘top_block_command’:
 -- Function: $COMMAND_NAME = $CONVERTER->top_block_command ()
     Return the most recent block @-command seen in the current
     formatting context.

10.4 Converting Texinfo Trees
=============================

In some cases, it may be needed to convert a Texinfo tree rooted at any
element.  There is no reason to do that often, as the converter already
goes through the tree calling functions to convert the elements, but it
can be interesting in some cases.

   This is, for example, often needed if a translated Texinfo tree is
setup (see Internationalization of Strings Function).  For example, here
a Texinfo tree is returned by the ‘cdt’ call, based on the translation
of the ‘No value for @strong{{item}}’ string, and converted to HTML with
‘convert_tree’:
     my $tree = $converter->cdt('No value for @strong{{item}}',
                                {'item' => $text_element});
     my $no_value_converted_output = $converter->convert_tree($tree);

10.4.1 Texinfo Tree Conversion Functions
----------------------------------------

The ‘convert_tree’ function converts a Texinfo tree rooted at any
element:

 -- Function: $CONVERTED_TEXT = $CONVERTER->convert_tree (\%ELEMENT,
          $EXPLANATION)
     \%ELEMENT is a Texinfo tree element.  $EXPLANATION is optional, it
     is a string explaining why the function was called, to help in case
     of debugging.  The function returns \%ELEMENT converted.

   ‘convert_tree’ is suitable when the conversion is in the flow of the
Texinfo tree conversion.  Sometime, it is better to ignore the
formatting context of the main conversion, for example for the
formatting of a caption, or the formatting of footnotes texts.  Another
special case is the case of tree elements being converted more than
once, even if in the flow of the Texinfo tree conversion, for example if
there are multiple ‘@insertcopying’ in a document.  A last special case
arise, with formatting done in advance or out of the main conversion.
This is the case, in practice, for sectioning commands or node commands
which may be formatted as directions in navigation panels, menus or
indices, may appear more than once in the document and be converted more
than once, if language changes, for example.

   For such cases, the function is ‘convert_tree_new_formatting_context’
which sets the context appropriately.
‘convert_tree_new_formatting_context’ ultimately calls ‘convert_tree’.

 -- Function: $CONVERTED_TEXT =
          $CONVERTER->convert_tree_new_formatting_context (\%ELEMENT,
          $CONTEXT, $MULTIPLE_PASS, $GLOBAL_CONTEXT,
          $BLOCK_COMMAND_NAME)
     \%ELEMENT is a Texinfo tree element.  $CONTEXT describes the new
     context setup to format out of the main conversion flow.
     $MULTIPLE_PASS is an optional string that marks that the conversion
     is done more than once.  It should be unique and suitable for
     inclusion in targets and identifiers.  $GLOBAL_CONTEXT is an
     optional string that marks that the formatting may be done in
     advance, and can be redone.  $BLOCK_COMMAND_NAME is an optional
     block command name that is used to initialized the new context.  It
     can be useful, in particular, to propagate the topmost block
     command in the new context.

     The function returns \%ELEMENT converted, setting the conversion
     context according to the arguments.

   See Setting the Context for Conversion on how to set a specific
context for a Texinfo tree conversion.

10.4.2 Setting the Context for Conversion
-----------------------------------------

Special container types are recognized by the converter and can be used
to convert a Texinfo tree in a specific context.  Those types cannot
appear in a regular Texinfo tree.  In general they should be the type of
tree root elements setup by the user.

   The types are:

‘_code’
     In this container, the conversion is done in a code context See
     Init File Expansion Contexts.  For a container tree element.

‘_converted’
     The text of this text element is considered to be already
     formatted.

‘_string’
     In this container, the conversion is done in a string context.  See
     Init File Expansion Contexts.  For a container tree element.

   These contexts are typically used together with converter conversion
functions (see Texinfo Tree Conversion Functions).  For example:

     my @contents = @{$element->{'contents'}};
     push @contents, {'text' => ' HTML text ',
                        'type' => '_converted'};
     my $result = $converter->convert_tree({'type' => '_code',
                                       'contents' => \@contents });

10.4.3 Conversion to Plain Text
-------------------------------

The conversion to plain text can be achieved by using the
‘Texinfo::Text’ converter ‘convert_to_text’ function (see
(texi2any_internals)Texinfo::Convert::Text).

   ‘convert_to_text’ requires a conversion options argument to determine
how the conversion to text should be done, specifying, for instance, the
encoding or the formatting context.  Such options are available in
‘$converter->{'convert_text_options'}’.

   For example, to convert the Texinfo tree element $ELEMENT to plain
text:
     my $plain_text = Texinfo::Convert::Text::convert_to_text($element,
                                       $converter->{'convert_text_options'});

   Conversion to plain text is often used for strings that are to be
formatted in code context.  Code context can be set and reset by using
‘Texinfo::Convert::Text::set_options_code’ and
‘Texinfo::Convert::Text::reset_options_code’:
     Texinfo::Convert::Text::set_options_code(
                    $converter->{'convert_text_options'});
     my $code_string = Texinfo::Convert::Text::convert_to_text($element,
                                 $converter->{'convert_text_options'});
     Texinfo::Convert::Text::reset_options_code(
                    $converter->{'convert_text_options'});

   If encoded characters should be used irrespective of the specified
document encoding, a possibility relevant, in general, for file names,
‘Texinfo::Convert::Text::set_options_encoding_if_not_ascii’ should be
called before the conversion and the original options should be reset
afterwards by calling ‘Texinfo::Convert::Text::reset_options_encoding’:
     Texinfo::Convert::Text::set_options_code(
                    $converter->{'convert_text_options'});
     Texinfo::Convert::Text::set_options_encoding_if_not_ascii($converter,
                                  $converter->{'convert_text_options'});
     my $file_name = Texinfo::Convert::Text::convert_to_text($element,
                                 $converter->{'convert_text_options'});
     Texinfo::Convert::Text::reset_options_code(
                    $converter->{'convert_text_options'});
     Texinfo::Convert::Text::reset_options_encoding(
                    $converter->{'convert_text_options'});

10.4.4 Texinfo Tree Elements in User Defined Functions
------------------------------------------------------

Many user defined functions used for formatting have Texinfo tree
elements as arguments.  The user defined code should never modify the
tree elements.  It is possible to reuse Texinfo tree elements
information, but with a copy.  For example, the following is correct:

     my @contents = @{$element->{'contents'}};
     push @contents, {'text' => ' my added text'};
     my $result = $converter->convert_tree({'cmdname' => 'strong',
                                       'contents' => \@contents });

   The following is incorrect:

     push @{$element->{'contents'}}, {'text' => ' my added text'};

   Nodes and sectioning elements hold information on the document
structure (see (texi2any_internals)Texinfo::Structuring METHODS). For
example, the following keys of the ‘extra’ sectioning elements hash can
be interesting in several user-defined formatting and conversion
functions:

‘section_childs’
     For sectioning commands elements.  The children of the sectioning
     element in the sectioning tree.

‘section_level’
     The level of the section, taking into account ‘@raisesections’ and
     ‘@lowersections’.  Level 0 corresponds to ‘@top’ or ‘@part’ and
     level 1 to ‘@chapter’ level sectioning commands.  See
     (texinfo)Raise/lower sections.

   Detailed information on the tree elements is available in the Texinfo
Parser documentation, in particular a list of types and of information
in the elements ‘extra’ hash (see (texi2any_internals)Texinfo::Parser
TEXINFO TREE).

10.4.5 Output Units in User Defined Functions
---------------------------------------------

Some information is available only in output units.  Finding an output
unit and using the information associated with the output unit hash
reference keys may be needed in user-defined conversion functions.

   Both normal and special output units (see Output Units) can be
obtained as output units conversion function arguments (see Output Units
Conversion Functions).  The current output unit being processed is also
available as ‘$converter->current_output_unit()’ (see Other Dynamic
Information).  Root command (‘@node’ or sectioning command)
‘associated_unit’ key value points to the associated output unit.
Lastly ‘get_element_root_command_element’ may be used to get the the
output unit associated with an element (see
get_element_root_command_element).

   The following keys of output unit hashes can be interesting:

‘unit_type’
     ‘unit’ for normal output units, ‘special_unit’ for special units
     and ‘external_node_unit’ for external nodes virtual units
     corresponding to references to external manuals.

‘unit_command’
     For normal output units, points to the associated ‘@node’ or
     sectioning @-command depending on which of nodes or sectioning
     commands are the main components of output units.  See Output
     Units.  The corresponding sectioning and ‘@node’ @-command elements
     have an ‘associated_unit’ key directly in their hash that points to
     the associated output unit.

     For special units, points to a "virtual" tree element with type
     ‘special_unit_element’ associated with the special element, that
     does not appear in the Texinfo tree but can be used as a target for
     directions to the special unit.  This element has an
     ‘associated_unit’ key that points to the associated output unit.

     for references to external manuals virtual units, points to the
     tree element corresponding to the external manual and node label.

‘unit_contents’
     Array reference on tree elements associated with the output unit.

‘unit_filename’
     The associated file name.

‘unit_directions’
     Hash with ‘next’ and ‘prev’ for the next and previous output units
     in document order.

‘special_unit_variety’
     The variety of the special output unit.  For special units only.
     See Table 16.1: Special Units Varieties.

   see (texi2any_internals)Texinfo::Structuring METHODS for more on
document structure information held by output units.

11 Customization and Use of Formatting Functions
************************************************

Full customization of output is achieved with replacing default
formatting functions with user defined functions.  There are two broad
classes of functions, the “conversion” functions used for output units
and elements of the Texinfo tree, and other “formatting” functions with
diverse purposes, including formatting that are not based on tree
elements (for example beginning and end of file formatting).
“Conversion” functions are described in the next chapters.

   This chapter describes how “formatting” functions are registered and
basic formatting functions that can be used in diverse situations.  More
specific formatting functions are described later on together with
information on specific output customization.

   Most formatting functions are specific, with specific arguments, and
a specific item formatted.  They can be called for HTML formatting and
may also be customized.

   User defined functions associated with the formatting of special
output units body (see Output Units) can be considered as formatting
functions, but are registered especially (see Special Unit Body
Formatting Functions).

   The formatting functions are often called from functions that can be
replaced by user-defined functions, therefore these functions may not be
called if the replacement functions do not keep a similar operation.

11.1 Registering Specific Formating Functions
=============================================

User defined formatting functions are registered with
‘texinfo_register_formatting_function’:

 -- Function: texinfo_register_formatting_function ($formatted,
          \&handler)
     $FORMATTED is a string describing the formatting function.
     \&HANDLER is the user defined function reference.

   To call a formatting function from user defined code, the function
reference should first be retrieved using ‘formatting_function’:

 -- Function: \&FORMATTING_FUNCTION = $CONVERTER->formatting_function
          ($FORMATTED)
     $FORMATTED is a string describing the formatting function.  Returns
     the associated formatting function reference.

   It is possible to have access to the default formatting function
reference.  The function used is:

 -- Function: \&DEFAULT_FORMATTING_FUNCTION =
          $CONVERTER->default_formatting_function ($FORMATTED)
     $FORMATTED is a string describing the formatting function.  Returns
     the default formatting function reference.

   The string that should be used to register or call each of the
formatting functions and the call of the formatting functions are
documented in the following sections of the manual, depending on where
they are relevant.

11.2 Basic Formatting Customization
===================================

The following formatting functions references handle basic formatting
and are called from diverse formatting and conversion functions.  See
Registering Specific Formating Functions for information on how to
register and get the functions references.

   All the functions take a converter object as their first argument.

‘format_comment’

      -- Function Reference: $TEXT format_comment ($CONVERTER,
               $INPUT_TEXT)
          Return $INPUT_TEXT in a comment.

     See Texinfo::Convert::Converter::xml_comment:
     (texi2any_internals)Texinfo::Convert::Converter $comment =
     $converter->xml_comment($text).

‘format_heading_text’

      -- Function Reference: $TEXT format_heading_text ($CONVERTER,
               $COMMAND_NAME, \@CLASSES, $INPUT_TEXT, $LEVEL, $ID,
               \%ELEMENT, $TARGET)
          Returns a heading formatted using $INPUT_TEXT as heading text,
          $LEVEL as heading level, \@CLASSES for a class attribute.
          $COMMAND_NAME gives an information on the @-command the
          heading is associated with and can be ‘undef’, for instance
          for special output units headings.

          $ID is an optional identifier, and \%ELEMENT is an optional
          Texinfo tree element associated with the heading.  $TARGET is
          the id of the element this heading is referring to.

          In the default case, if the $TARGET or $ID are specified, a
          copiable anchor will be generated and injected into the
          heading.  In the case both are specified, $ID is preferred
          over $TARGET, as it is closer to the element the user sees the
          anchor on.

     This function reference can be called for ‘@node’ and sectioning
     commands, heading commands, special output units and title
     @-commands.

     A formatted headings is, in the default case, like
     ‘
$INPUT_TEXT
’ for a $LEVEL 2 heading.

‘format_program_string’

      -- Function Reference: $TEXT format_program_string ($CONVERTER)
          This function reference should return the formatted program
          string.

‘format_protect_text’
      -- Function Reference: $TEXT format_protect_text ($CONVERTER,
               $INPUT_TEXT)
          Return $INPUT_TEXT with HTML reserved characters and form
          feeds protected.

          For performance reasons, this function reference may not be
          called everywhere text is protected.  For those cases, the
          calling function should also be redefined to call
          ‘&{$converter->formatting_function('format_protect_text')}(...)’
          instead of another function(1).

     See Texinfo::Convert::Converter::xml_protect_text:
     (texi2any_internals)Texinfo::Convert::Converter $protected_text =
     $converter->xml_protect_text($text).
‘format_separate_anchor’

     This function reference is called if there is not another HTML
     element to add an identifier attribute to.

      -- Function Reference: $TEXT format_separate_anchor ($CONVERTER,
               $ID, $CLASS)
          ID is the identifier.  $CLASS is an optional class to be used
          in an HTML class attribute.

          Return an anchor with identifier $ID.

   For example, a separate anchor with an id built from a counter could
be obtained with:
     $counter++;
     my $anchor_id = 'anchor_id_' . $counter;
     my $anchor_with_counter
       = &{$converter->formatting_function('format_separate_anchor')}(
                                  $converter, $anchor_id, 'myanchor_class');

   The default function used for separate anchors can be replaced by a
user-defined anchor formatting function using a ‘
’ element with:
     sub my_format_separate_anchor($$;$)
     {
       my $converter = shift;
       my $id = shift;
       my $class = shift;

       return $converter->html_attribute_class('p', [$class])." id=\"$id\">
";
     }

     texinfo_register_formatting_function('format_separate_anchor',
                                          \&my_format_separate_anchor);

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

   (1) The function called is actually the function referenced as
‘$converter->formatting_function('format_protect_text')’ in the default
case, but it is called directly to avoid an indirection

12 Tree Element Conversion Customization
****************************************

Customization of tree elements associated with @-commands is done with
different functions than those used for other tree elements, for
instance containers with a type and tree elements holding text.

   There are two main functions for each element command or type, one
called when the element is first encountered, and the other called after
formatting the contents of the element.  The actual conversion is
usually done after formatting the contents of the element, but it may
sometime be necessary to have some code run when the element is first
encountered.

   For @-commands with both a command name and a type, the type is used
as selector for the formating function for ‘def_line’,
‘definfoenclose_command’ and ‘index_entry_command’ types.

12.1 Command Tree Element Conversion
====================================

All the command elements can have a conversion function and an opening
function that can be registered to be called by the converter.  Some
commands also require more specific information and functions for their
formatting.

12.1.1 Command Tree Element Conversion Functions
------------------------------------------------

User defined functions called for an @-command element conversion, after
arguments and contents have been formatted, are registered with
‘texinfo_register_command_formatting’:

 -- Function: texinfo_register_command_formatting ($command_name,
          \&handler)
     $COMMAND_NAME is an @-command name, without the leading @.
     \&HANDLER is the user defined function reference.

   The call of the user defined functions is:
 -- Function Reference: $TEXT command_conversion ($CONVERTER,
          $COMMAND_NAME, \%ELEMENT, \@ARGS, $CONTENT)
     $CONVERTER is a converter object.  $COMMAND_NAME is the @-command
     name without the @.  \%ELEMENT is the Texinfo element.

     \@ARGS, if defined, is a reference on the formatted arguments of
     the @-command.  Each of the array items correspond to each of the
     @-command argument.  Each array item is either ‘undef’ if the
     argument is empty, or a hash reference, with keys corresponding to
     possible argument formatting contexts:

     ‘normal’
          Argument formatted in a normal context

     ‘monospace’
          Argument formatted in a context where spaces are kept as is,
          as well as quotes and minus characters, for instance in ‘--’
          and ‘``’.  Both in preformatted and code context.  See Init
          File Expansion Contexts.

     ‘monospacestring’
          Same as monospace, but in addition in string context.  See
          Init File Expansion Contexts.

     ‘monospacetext’
          Same as monospace, but in addition the argument is converted
          to plain text.

     ‘filenametext’
          Same as monospacetext, but in addition the document encoding
          is used to convert accented letters and special insertion
          @-commands to plain text independently of customization
          variables.

     ‘raw’
          Text is kept as is, special HTML characters are not protected.
          Appears only as ‘@inlineraw’ second argument.

     ‘string’
          In string context.  See Init File Expansion Contexts.

     ‘arg_tree’
          The Texinfo tree element corresponding to the argument.  See
          Texinfo Tree Elements in User Defined Functions.

     ‘url’
          Similar with filenametext.  The difference is that UTF-8
          encoding is always used for the conversion of accented and
          special insertion @-commands to plain text.  This is best for
          percent encoding of URLs, which should always be produced from
          UTF-8 encoded strings.

     The formatted arguments contexts depend on the @-command, there
     could be none, for ‘@footnote’ argument which is not directly
     converted where the footnote command is, or multiple, for example
     for the fourth argument of ‘@image’ which is both available as
     ‘normal’ and ‘string’.  See Table 12.1: HTML command arguments
     formatting, for the converted arguments contexts.  @-commands not
     specified in the table have their arguments in ‘normal’ context.

     For example, ‘$args->[0]->{'normal'}’ is the first argument
     converted in normal context.  It should be present for most
     @-commands with arguments, but not for all, for example ‘@anchor’
     argument is only available as ‘monospacestring’.

     $CONTENT is the @-command formatted contents.  It corresponds to
     the contents of block @-commands, and to Texinfo code following
     ‘@node’, sectioning commands, ‘@tab’ and ‘@item’ in ‘@enumerate’
     and ‘@itemize’.  $CONTENT can be ‘undef’ or the empty string.

     The $TEXT returned is the result of the @-command conversion.

‘@abbr’              normal            normal,
                                       string
‘@acronym’           normal            normal,
                                       string
‘@anchor’            monospacestring
‘@email’             url,              normal
                     monospacestring
‘@footnote’
‘@image’             monospacestring,  filenametext   filenametext   normal,        filenametext
                     filenametext,                                   string
                     url
‘@inforef’           monospace         normal         filenametext
‘@inlinefmt’         monospacetext     normal
‘@inlinefmtifelse’   monospacetext     normal         normal
‘@inlineifclear’     monospacetext     normal
‘@inlineifset’       monospacetext     normal
‘@inlineraw’         monospacetext     raw
‘@item’
‘@itemx’
‘@link’              monospace         normal         filenametext
‘@printindex’
‘@pxref’             monospace         normal         normal         filenametext   normal
‘@ref’               monospace         normal         normal         filenametext   normal
‘@sp’
‘@uref’              url,              normal         normal
                     monospacestring
‘@url’               url,              normal         normal
                     monospacestring
‘@value’             monospacestring
‘@xref’              monospace         normal         normal         filenametext   normal

Table 12.1: HTML command arguments formatting contexts in conversion
function argument

   To call a conversion function from user defined code, the function
reference should first be retrieved using ‘command_conversion’:

 -- Function: \&COMMAND_CONVERSION = $CONVERTER->command_conversion
          ($COMMAND_NAME)
     $COMMAND_NAME is the @-command name without the @.  Returns the
     conversion function reference for $COMMAND_NAME, or ‘undef’ if
     there is none, which should only be the case for @-commands ignored
     in HTML not defined by the user.

   for example, to call the conversion function for the ‘@tab’
@-command, passing arguments that may correspond to another @-command:
     &{$converter->command_conversion('tab')}($converter, $cmdname,
                                          $command, $args, $content);

   It is possible to have access to the default conversion function
reference.  The function used is:

 -- Function: \&DEFAULT_COMMAND_CONVERSION =
          $CONVERTER->default_command_conversion ($COMMAND_NAME)
     $COMMAND_NAME is the @-command name without the @.  Returns the
     default conversion function reference for $COMMAND_NAME, or ‘undef’
     if there is none, which should only be the case for @-commands
     ignored in HTML.

12.1.2 Command Tree Element Opening Functions
---------------------------------------------

User defined functions called when an @-command element is first
encountered are registered with ‘texinfo_register_command_opening’.  In
general the possibility to call code at the @-command opening is not
used much, as the HTML formatting is in general done when the content
appearing in the comand is formatted.  In the default conversion
functions, this function is used for ‘@quotation’, to register
prependended text to be output with the following inline container,
usually a paragraph.  This is described in detail with the inline
containers formatting (see Inline Text Containers Formatting).

 -- Function: texinfo_register_command_opening ($command_name,
          \&handler)
     $COMMAND_NAME is an @-command name, with the leading @.  \&HANDLER
     is the user defined function reference.

   The call of the user defined functions is:

 -- Function Reference: $TEXT command_open ($CONVERTER, $COMMAND_NAME,
          \%ELEMENT)
     $CONVERTER is a converter object.  $COMMAND_NAME is the @-command
     name without the @.  \%ELEMENT is the Texinfo element.

     The $TEXT returned is prepended to the formatting of the @-command.

   It is possible to have access to the default opening function
reference.  The function used is:
 -- Function: \&DEFAULT_COMMAND_OPEN = $CONVERTER->default_command_open
          ($COMMAND_NAME)
     $COMMAND_NAME is the @-command name without the @.  Returns the
     default opening function reference for $COMMAND_NAME, or ‘undef’ if
     there is none.

12.1.3 Heading Commands Formatting
----------------------------------

You can change the heading commands formatting by setting customization
variables.  In particular, you can change the navigation information
output in headers associated with heading commands by selecting a
different type of navigation (see (texinfo)HTML Output Structure
Customization), by changing the links formatting (see (texinfo)File
Names and Links Customization for HTML), the navigation panels
formatting (see (texinfo)Customization of Navigation and Headers) and
the heading levels (see (texinfo)Specific Customization of HTML
Formatting).

   ‘@node’ and sectioning commands default conversion function call
‘format_heading_text’ (see Basic Formatting Customization) and
‘format_element_header’ (see Element Header and Footer Formatting).  The
‘@node’ and sectioning elements are formatted like any other elements
associated with @-commands.  The corresponding function references can
therefore be replaced by user defined functions for a precise control of
conversion (See Command Tree Element Conversion Functions).

   In the default formatting, when a sectioning command is encountered,
a ‘
’ element is opened for the extent of the sectioning command
including its children sectioning commands.  This extent need to be
closed at different places, for instance when another sectioning command
is reached, at the end of a file, or at the end of the document.

   The user defined formatting function should take care of registering
and closing opened section levels.  In the default code, registering is
done in the sectioning commands conversion function only.

   The function for registering opened section extent is
‘register_opened_section_level’:

 -- Function: $CONVERTER->register_opened_section_level ($filename,
          $level, $closing_text)
     $FILENAME is the filename the section belongs to.  You could use
     ‘$converter->current_filename()’ for $FILENAME.  $LEVEL is the
     sectioning command level.  It is typically obtained with
     ‘section->{'extra'}->{'section_level'}’ (see Texinfo Tree Elements
     in User Defined Functions).  $CLOSING_TEXT is the text that should
     be output when the section level $LEVEL is closed.

   The function for closing registered section extents is
‘close_registered_sections_level’:

 -- Function: \@CLOSING_TEXTS =
          $CONVERTER->close_registered_sections_level ($FILENAME,
          $LEVEL)
     $FILENAME is the filename the closed sections belong to.  You could
     use ‘$converter->current_filename()’ for $FILENAME.  $LEVEL is the
     sectioning command level.  Opened section are closed down to
     section level $LEVEL.  The closing texts are returned in the
     \@CLOSING_TEXTS array reference in order.

   Example of use:
     my $level = $opening_section->{'extra'}->{'section_level'};
     my $closed_strings
        = $converter->close_registered_sections_level(
                         $converter->current_filename(), $level);
     $result .= join('', @{$closed_strings});

     # ....

     $converter->register_opened_section_level(
                      $converter->current_filename(), $level, "
\n");

12.1.4 Target Tree Element Link
-------------------------------

User-defined code in functions replacing default conversion functions
for ‘@xref’ and similar @-commands output, ‘@menu’, ‘@node’, sectioning
commands, ‘@printindex’ and ‘@listoffloats’ formatting requires links,
labels and files information, mainly to output hyperlinks to “target
commands”.

   Target @-commands are @-commands that are associated with an
identifier and can be linked to.  They corresponds first to @-commands
with unique identifier used as labels, ‘@node’, ‘@anchor’ and ‘@float’.
Sectioning commands, index entries, footnotes are also associated with
targets.  The "virtual" elements associated with special output units
are also associated with targets leading to each special unit (see
Output Units in User Defined Functions).

   To get the unique Texinfo tree element corresponding to a label, use
‘label_command’:

 -- Function: \%ELEMENT = $CONVERTER->label_command ($LABEL)
     Return the element in the tree that $LABEL refers to.

   For example:
     my $node_element = $converter->label_command('Some-node_003f');

   Labels are available for target @-commands and for @-command
referring to target elements such as ‘@xref’ or ‘@menu’ entry node
argument as the extra ‘normalized’ element key.

   For example, the first ‘@xref’ argument ‘normalized’ element key may
be used to get the node or anchor element it points to:
     my $arg_node = $xref_tree_element->{'args'}->[0];
     if ($arg_node and $arg_node->{'extra'}
         and defined($arg_node->{'extra'}->{'normalized'})) {
       my $target_node
         = $converter->label_command($arg_node->{'extra'}->{'normalized'});
     }

   Tree elements not associated with a label are obtained each
differently.  For example, elements associated with index entries can be
obtained using the Texinfo parsed document index entries with
‘$converter->get_info('document')->indices_information()’ (see Converter
General Information), or through sorted indices information (see
Specific Formatting for Indices).  Footnote elements can be obtained
through the ‘@footnote’ conversion function, and can also be passed to
footnote formatting functions (see Customizing Footnotes).  Floats
elements in ‘@listoffloats’ can be obtained from
‘$converter->get_info('document')->floats_information()’ (see Converter
General Information).

   To get the identifier, file name and href of tree elements that may
be used as link target, use ‘command_id’, ‘command_filename’ and
‘command_href’:

 -- Function: $IDENTIFIER = $CONVERTER->command_id (\%TARGET_ELEMENT)
     Returns the id specific of the \%TARGET_ELEMENT tree element.

 -- Function: $FILE_NAME = $CONVERTER->command_filename
          (\%TARGET_ELEMENT)
     Returns the file name of the \%TARGET_ELEMENT tree element.

 -- Function: $HREF = $CONVERTER->command_href (\%TARGET_ELEMENT,
          $SOURCE_FILENAME, $SOURCE_COMMAND, $SPECIFIED_TARGET)
     Return string for linking to \%TARGET_ELEMENT with ‘’ or
     ‘undef’ if not found or empty.  $SOURCE_FILENAME is the file the
     link comes from.  If not set, the current file name is used.
     $SOURCE_COMMAND is an optional argument, the @-command the link
     comes from.  It is only used for messages.  $SPECIFIED_TARGET is an
     optional identifier that overrides the target identifier if set.

   To get the text of tree elements that may be used as link
description, use ‘command_text’:

 -- Function: $RESULT = $CONVERTER->command_text (\%TARGET_ELEMENT,
          $TYPE)
     Return the information to be used for a hyperlink to
     \%TARGET_ELEMENT.  The information returned depends on $TYPE:

     _text_
          Return text.

     _string_
          Return text in string context.  See Init File Expansion
          Contexts.

   Using those functions, a target element hyperlink can be constructed
as:
     my $target_text = $converter->command_text($target_element);
     my $target_href = $converter->command_href($target_element);
     my $hyperlink = "$target_text";

   To get a Texinfo tree of elements that may be used as link
description, use ‘command_tree’:

 -- Function: $RESULT = $CONVERTER->command_tree (\%TARGET_ELEMENT,
          $NO_NUMBER)
     Return the a Texinfo tree to be used for a hyperlink to
     \%TARGET_ELEMENT.  If $NO_NUMBER is set, return a Texinfo elements
     tree representing text without a chapter number being included.

   To obtain the top level command element associated with a footnote,
float or index entry target element, use ‘command_root_element_command’:

 -- Function: \%TOP_LEVEL_ELEMENT =
          $CONVERTER->command_root_element_command (\%TARGET_ELEMENT)
     Return the top level element, either a ‘@node’ or a sectioning
     element \%TARGET_ELEMENT is in.

   This is used in indices formatting to link to index entry associated
sectioning element in addition to linking to the index entry location.
For example:

     my $entry_root_link = '';
     my $associated_command
      =  $converter->command_root_element_command($target_element);
     if ($associated_command) {
       my $associated_command_href
         = $converter->command_href($associated_command);
       my $associated_command_text
         = $converter->command_text($associated_command);

       if (defined($associated_command_href)) {
         $entry_root_link
           = ""
               ."$associated_command_text";
     } elsif (defined($associated_command_text)) {
       $entry_root_link = $associated_command_text;
     }

     my $formatted_entry = "$hyperlink"
                       ."$entry_root_link\n";

   To get the node element associated with a target element, use
‘command_node’:

 -- Function: \%NODE_ELEMENT = $CONVERTER->command_node
          (\%TARGET_ELEMENT)
     Return the node element associated with \%TARGET_ELEMENT.

   For elements that are not target elements, use
‘get_element_root_command_element’ to get the root level Perl tree
element and the output unit containing the element:

 -- Function: \%TOP_LEVEL_ELEMENT, \%OUTPUT_UNIT =
          $CONVERTER->get_element_root_command_element (\%ELEMENT)
     Return the top level element and output unit a Texinfo tree
     \%ELEMENT is in.  Both the top level element and the output unit
     may be undefined, depending on how the converter is called and on
     the Texinfo tree.  The top level element returned is also
     determined by the customization variable ‘USE_NODES’.  If
     ‘USE_NODES’ is set the ‘@node’ is preferred, otherwise the
     sectioning command is preferred.

   For example to get the ‘@node’ or sectioning root command tree
element containing a ‘@printindex’ element tree and the associated
identifier for the formatting of the ‘@printindex’ Texinfo tree element:
     my ($output_unit, $root_command)
      = $converter->get_element_root_command_element($printindex_element);
     my $index_element_id = $converter->command_id($root_command);

12.1.5 Specific Formatting for Indices
--------------------------------------

Index formatting customization is achieved through registering a
conversion function for ‘@printindex’ (see Command Tree Element
Conversion Functions).  The Texinfo parsed document index entries
information directly obtained from the Texinfo manual parsing is
available through
‘$converter->get_info('document')->indices_information()’ (see Converter
General Information).  Sorted index entries, which are usually used for
index formatting are available through
‘get_converter_indices_sorted_by_letter’:

 -- Function: \%SORTED_INDEX_ENTRIES =
          $CONVERTER->get_converter_indices_sorted_by_letter ()
     Returns index entries sorted by index and letter.  This function
     should be called each time sorted indices are needed, in case the
     sorting depends on the ‘@documentlanguage’ value.  See
     Texinfo::Convert::Converter::get_converter_indices_sorted_by_letter:
     (texi2any_internals)Texinfo::Convert::Converter $sorted_indices =
     $converter->get_converter_indices_sorted_by_letter().

12.1.6 Image Formatting
-----------------------

Image ‘@image’ command formatting is customized by registering a
conversion function for ‘@image’ (see Command Tree Element Conversion
Functions).  To get the location of an image file, it could be useful to
use ‘html_image_file_location_name’:

 -- Function: ($IMAGE_FILE, $IMAGE_BASEFILE, $IMAGE_EXTENSION,
          $IMAGE_PATH, $IMAGE_PATH_ENCODING) =
          $CONVERTER->html_image_file_location_name ($COMMAND_NAME,
          \%ELEMENT, \@ARGS)
     $COMMAND_NAME, \%ELEMENT and \@ARGS should be the arguments of an
     ‘@image’ @-command formatting (see Command Tree Element Conversion
     Functions).

     The return values gives information on the image file if found, or
     fallback values.  $IMAGE_FILE is the relative image file name.  It
     is the file name used in formatting of the ‘@image’ command in the
     default case.  $IMAGE_BASEFILE is the base file name of the image,
     without extension, corresponding to the ‘@image’ @-command first
     argument.  $IMAGE_EXTENSION is the image file extension (without a
     leading dot).  $IMAGE_PATH is the path to the actual image file,
     ‘undef’ if no file was found.  $IMAGE_PATH is returned as a binary
     string, the other strings returned are character strings.
     $IMAGE_PATH_ENCODING is the encoding used to encode the image path
     to a binary string.

12.2 Type Tree Element Conversion
=================================

All the containers and text Texinfo tree elements not handled with
command tree elements have a “type” associated.  As for commands tree
elements, they can have an opening function and a conversion function
registered for a type and used.  Some types may need more specific
information too.

   For tree elements that contain text, a ‘text’ type is used to select
the formatting functions, irrespective of the actual type of such a tree
element.  The ‘text’ type does not exist in actual Texinfo tree
elements.

12.2.1 Type Tree Element Conversion Functions
---------------------------------------------

User defined functions called for the conversion of an element without
@-command with text or a container type are registered with
‘texinfo_register_type_formatting’.  For containers, the user defined
function is called after conversion of the content.

 -- Function: texinfo_register_type_formatting ($type, \&handler)
     $TYPE is the element type.  \&HANDLER is the user defined function
     reference.

   The call of the user defined functions is:

 -- Function Reference: $TEXT type_conversion ($CONVERTER, $TYPE,
          \%ELEMENT, $CONTENT)
     $CONVERTER is a converter object.  $TYPE is the element type.
     \%ELEMENT is the Texinfo element.  $CONTENT is text for elements
     associated with text, or the formatted contents for other elements.
     $CONTENT can be ‘undef’ or the empty string.

     The $TEXT returned is the result of the element conversion.

   To call a conversion function from user defined code, the function
reference should first be retrieved using ‘type_conversion’:

 -- Function: \&TYPE_CONVERSION = $CONVERTER->type_conversion ($TYPE)
     $TYPE is the element type.  Returns the conversion function
     reference for $TYPE, or ‘undef’ if there is none, which should only
     be the case for types ignored in HTML not defined by the user.

   It is possible to have access to the default conversion function
reference.  The function used is:

 -- Function: \&DEFAULT_TYPE_CONVERSION =
          $CONVERTER->default_type_conversion ($TYPE)
     $TYPE is the element type.  Returns the default conversion function
     reference for $TYPE, or ‘undef’ if there is none, which should only
     be the case for types ignored in HTML.

   Here is an example of paragraph formatting that prepends some HTML
code to each paragraph and formats in code context (see Setting the
Context for Conversion).  It also shows how string context can be taken
into account.

     sub my_tree_element_convert_paragraph_type($$$$)
     {
       my $converter = shift;
       my $type = shift;
       my $element = shift;
       my $content = shift;

       $content = '' if (!defined($content));

       if ($converter->in_string()) {
         return $content;
       }

       my @contents = {$element->{'contents'}};
       push @contents, {'text' => ' HTML text ',
                        'type' => '_converted'};
       my $result = $converter->convert_tree({'type' => '_code',
                                        'contents' => \@contents });
       return "
".$result."
";
     }

     texinfo_register_type_formatting('paragraph',
                             \&my_tree_element_convert_paragraph_type);

12.2.2 Type Tree Element Opening Functions
------------------------------------------

User defined functions called when an element without @-command with a
container type is first encountered are registered with
‘texinfo_register_type_opening’:

 -- Function: texinfo_register_type_opening ($type, \&handler)
     $TYPE is the element type.  \&HANDLER is the user defined function
     reference.

   The call of the user defined functions is:

 -- Function Reference: $TEXT type_open ($CONVERTER, $TYPE, \%ELEMENT)
     $CONVERTER is a converter object.  $TYPE is the element type.
     \%ELEMENT is the Texinfo element.

     The $TEXT returned is prepended to the formatting of the type
     container.

   It is possible to have access to the default opening function
reference.  The function used is:
 -- Function: \&DEFAULT_TYPE_OPEN = $CONVERTER->default_type_open
          ($TYPE)
     $COMMAND_NAME is the element type.  Returns the default opening
     function reference for $TYPE, or ‘undef’ if there is none.

   In the default conversion functions, this function is not often used,
conversion is in general done after the elements inside of the type
container have been formatted.  This function is defined for inline text
container elements to get text to prepend to their content (see Inline
Text Containers Formatting).

12.2.3 Text Tree Elements Conversion
------------------------------------

Tree elements holding text are converted by the function reference
registered for the ‘text’ type conversion irrespective of the actual
tree element type.  For example, a tree element with type
‘spaces_before_paragraph’ and text and a tree element without type but
with text are both converted by the function reference registered for
‘text’.

   The definition and registration of a conversion function for all the
tree elements holding text should be along:

     sub my_convert_text($$$)
     {
       my $converter = shift;
       my $type = shift;
       my $element = shift;
       my $text = shift;

       # ...

       $text = uc($text) if ($converter->in_upper_case());

       # ...
     }

     texinfo_register_type_formatting ('text', \&my_convert_text);

   The $TYPE free conversion function argument is the actual type of the
converted element (can be ‘undef’).

   Formatting of text requires to use informative functions on specific
contexts only relevant for text.  User defined functions should convert
the text according to the context.

   Each context is associated with a function:

_code_

      -- Function: $IN_CODE = $CONVERTER->in_code ()
          Return true if in code context.  See Init File Expansion
          Contexts.

_math_

      -- Function: $IN_MATH = $CONVERTER->in_math ()
          Return true if in math context.  See Init File Expansion
          Contexts.

_raw_

      -- Function: $IN_RAW = $CONVERTER->in_raw ()
          Return true if in raw format, in ‘@inlineraw’ or in ‘@html’.
          In such a context, text should be kept as is and special HTML
          characters should not be protected.

_verbatim_

      -- Function: $IN_VERBATIM = $CONVERTER->in_verbatim ()
          Return true if in verbatim context, corresponding to ‘@verb’
          and ‘@verbatim’.  In general, HTML characters should be
          protected in this context.

_upper-case_

      -- Function: $IN_UPPER_CASE = $CONVERTER->in_upper_case ()
          Return true if in upper-case context, corresponding to ‘@sc’.

_non-breakable space_

      -- Function: $IN_NON_BREAKABLE_SPACE =
               $CONVERTER->in_non_breakable_space ()
          Return true if in context where line breaks are forbidden,
          corresponding to ‘@w’.

_space protected_

      -- Function: $IN_SPACE_PROTECTED = $CONVERTER->in_space_protected
               ()
          Return true if in context where space and newline characters
          are kept, corresponding to ‘@verb’.

12.2.4 Inline Text Containers Paragraph and Preformatted Formatting
-------------------------------------------------------------------

Text is mainly output in two “inline” text containers, ‘paragraph’ for
text in paragraph and ‘preformatted’ for text in preformatted
environments.  The Texinfo code parsing makes sure that it is the case,
to simplify conversion to formats which allow text only in specific
environments such as HTML.

   Formatted text may also be prepared based on information from Texinfo
elements tree while out of the inline containers.  For example,
‘@quotation’ argument should in general be prepended to the first
paragraph in ‘@quotation’, caption number is also typically prependended
to the caption.  For that case, functions allow to register pending
inline formatted content, and get the content to be prepended in inline
text containers.

   Pending formatted content text is registered with
‘register_pending_formatted_inline_content’:

 -- Function: $CONVERTER->register_pending_formatted_inline_content
          ($category, $content)
     $CONTENT is the formatted content to be registered and output in
     the next inline container.  $CATEGORY is a indicator of the source
     of the formatted inline content, mostly used to cancel registered
     content if no inline container was seen.

   For example
     my $quotation_arg_to_prepend
       = $converter->convert_text($quotation_arg_element);
     $converter->register_pending_formatted_inline_content('quotation',
                                      $formatted_quotation_arg_to_prepend);

   Pending formatted content can (and should) be cancelled when it is
known that there is no suitable inline container to be used to output
the text.  The function is ‘cancel_pending_formatted_inline_content’:

 -- Function: $CANCELLED_CONTENT =
          $CONVERTER->cancel_pending_formatted_inline_content
          ($CATEGORY)
     Cancel the first $CATEGORY pending formatted content text found.
     Returns ‘undef’ if nothing was cancelled, and the cancelled content
     otherwise.

   Pending formatted content is gathered by calling
‘get_pending_formatted_inline_content’.  In the default case, this is
done in inline containers opening code (see Type Tree Element Opening
Functions).

 -- Function: $CONTENT =
          $CONVERTER->get_pending_formatted_inline_content ()
     Returns the concatenated pending content.

   The inline containers get the content when they are opened, but are
converted after the formatting of their contents.  Two additional
functions allow to associate pending content to an element,
‘associate_pending_formatted_inline_content’, and get the associated
content, ‘get_associated_formatted_inline_content’.
‘associate_pending_formatted_inline_content’ is normally called in
inline container opening code, right after
‘get_pending_formatted_inline_content’, while
‘get_associated_formatted_inline_content’ is called in the inline
container conversion function (see Type Tree Element Conversion
Functions).

 -- Function: $CONVERTER->associate_pending_formatted_inline_content
          (\%element, $content)
     Associate $CONTENT to the Texinfo tree element \%ELEMENT.

 -- Function: $CONTENT =
          $CONVERTER->get_associated_formatted_inline_content
          (\%ELEMENT)
     Get $CONTENT associated with the Texinfo tree element \%ELEMENT.

   Here is some inline container formatting code showing how those
functions are used, with the paragraph type element formatting example
completed:
     sub _open_inline_container_type($$$)
     {
       my $self = shift;
       my $type = shift;
       my $element = shift;

       my $pending_formatted = $self->get_pending_formatted_inline_content();

       if (defined($pending_formatted)) {
         $self->associate_pending_formatted_inline_content($element,
                                                         $pending_formatted);
       }
       return '';
     }

     sub my_final_convert_paragraph_type($$$$)
     {
       my $converter = shift;
       my $type = shift;
       my $element = shift;
       my $content = shift;

       $content = '' if (!defined($content));

       my $prepended
         = $converter->get_associated_formatted_inline_content($element);
       if ($converter->in_string()) {
         return $prepended.$content;
       }

       my @contents = {$element->{'contents'}};
       push @contents, {'text' => ' HTML text ',
                        'type' => '_converted'};
       my $result = $converter->convert_tree({'type' => '_code',
                                        'contents' => \@contents });
       return "
".$prepended.$result."
";
     }

     texinfo_register_type_formatting('paragraph',
                                  \&my_final_convert_paragraph_type);

13 Output Units Conversion Functions
************************************

Output units formatting function are setup and used similarly as for
tree container types (see Type Tree Element Conversion Functions).  The
output unit types correspond to the ‘unit_type’ key values of output
unit hashes (see Unit Type).

   User defined functions called for the conversion of an output unit
are registered with ‘texinfo_register_output_unit_formatting’.  The user
defined function is called after conversion of the content.

 -- Function: texinfo_register_output_unit_formatting ($unit_type,
          \&handler)
     $UNIT_TYPE is the output unit type.  \&HANDLER is the user defined
     function reference.

   The call of the user defined functions is:

 -- Function Reference: $TEXT output_unit_conversion ($CONVERTER,
          $UNIT_TYPE, \%OUTPUT_UNIT, $CONTENT)
     $CONVERTER is a converter object.  $UNIT_TYPE is the output unit
     type.  \%OUTPUT_UNIT is the output unit.  $CONTENT the formatted
     contents.  $CONTENT can be ‘undef’ or the empty string.

     The $TEXT returned is the result of the output unit conversion.

   To call a conversion function from user defined code, the function
reference should first be retrieved using ‘type_conversion’:

 -- Function: \&OUTPUT_UNIT_CONVERSION =
          $CONVERTER->output_unit_conversion ($UNIT_TYPE)
     $UNIT_TYPE is the output unit type.  Returns the conversion
     function reference for $UNIT_TYPE, or ‘undef’ if there is none.

   It is possible to have access to the default conversion function
reference.  The function used is:

 -- Function: \&DEFAULT_OUTPUT_UNIT_CONVERSION =
          $CONVERTER->default_output_unit_conversion ($UNIT_TYPE)
     $UNIT_TYPE is the output unit type.  Returns the default conversion
     function reference for $UNIT_TYPE, or ‘undef’ if there is none.

   Nomal output units with output unit type ‘unit’ default conversion
involves calling the formatting reference ‘format_element_footer’ (see
Element Header and Footer Formatting).

   Special units conversion is achieved by calling
‘special_unit_body_formatting’ (see Special Unit Body Formatting
Functions), ‘format_navigation_header’ (see Navigation Panel and
Navigation Header Formatting), ‘format_heading_text’ (see Basic
Formatting Customization) and ‘format_element_footer’ (see Element
Header and Footer Formatting).  Special units type is ‘special_unit’.

14 Shared Conversion State
**************************

For advanced customization, it is often necessary to pass information
during conversion between different formatting functions or between
different calls of the same function.  An interface is provided for
information shared among formatting functions, called “shared conversion
state”.  Each data piece in the “shared conversion state” is associated
with an @-command name, has a name, and a list of selectors.

   This interface is often useful for the formatting of paragraph and
preformatted containers and @-commands such as ‘@abbr’, ‘@footnote’,
‘@node’, sectioning commands, ‘@quotation’ and ‘@float’.

   It is required to use that interface when sharing information with
the default formatting functions.  Every type of function can use shared
state, formatting functions (see Customization and Use of Formatting
Functions), tree elements (see Tree Element Conversion Customization)
and output units conversion functions (see Output Units Conversion
Functions).

14.1 Define, Get and Set Shared Conversion State
================================================

Four types for selectors and value are currently considered:

‘string’
     A string.
‘integer’
     An integer
‘element’
     A Texinfo tree element.
‘index_entry.’
     An index entry reference as appearing in index data structures.
     See (texi2any_internals)Texinfo::Document index_entries.

   New shared infomation is defined with
‘define_shared_conversion_state’:

 -- Function: $CONVERTER->define_shared_conversion_state ($cmdname,
          $name, \@specification)
     $CMDNAME is an @-command name, without leading @.  NAME is the name
     associated with the data.  The ‘top’ command name is conventionally
     used if there is no natural association with another @-command.
     \@SPECIFICATION array reference specifies the types of the
     selectors and the type of the value as strings.  The last string of
     the array specifies the type of the value.  The preceding strings
     specify the number and types of selectors(1).

     For example, ‘['integer', 'element', 'string']’ specifies a
     ‘string’ type for the value, and two selectors, the first with
     ‘integer’ type, and the second with ‘element’ type.  ‘['integer']’
     specifies an integer for the value and no selector.

   For example, the following defines a ‘color’ shared conversion state
formally associated with ‘@quotation’, with an integer value and a
string selector.
     $converter->define_shared_conversion_state ('quotation', 'color',
                                                 ['string', 'integer']);

   The association with an @-command is provided for a semantic
classification of shared conversion information, but has no practical
effect.  In particular, nothing prevents using shared conversion state
information associated with an @-command in the formatting of another
@-command.

   The function ‘get_shared_conversion_state’ is used to get
information:

 -- Function: $VALUE = $CONVERTER->get_shared_conversion_state
          ($CMDNAME, $NAME, [$SELECTOR ...])
     Return the reference $VALUE associated with $CMDNAME and $NAME.
     The number of selectors given in argument should match the number
     of selectors in the definition (possibly none).

   For example, continuing with the ‘color’ shared information data
defined above, with one selector variable:
     my $color_number
        = $converter->get_shared_conversion_state('quotation',
                                                    'color', 'purple1');

   The function ‘set_shared_conversion_state’ is used to set shared
information:

 -- Function: $CONVERTER->define_shared_conversion_state ($CMDNAME,
          $NAME, [$SELECTOR ...], $VALUE)
     Sets $VALUE associated with $CMDNAME and $NAME.  The number of
     selectors given in argument should match the number of selectors in
     the definition (possible none).

   For example:
     $converter->set_shared_conversion_state('quotation', 'color',
                                             'special_black', 42);

   The converter is used to hold the information, but does not use nor
write.

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

   (1) The number of strings in the specification is the only
information actually used, to determine the number of selectors.
However, it is advised to use the specified types for consistency and
compatibility with future changes.

14.2 Shared Conversion State in Default Formatting
==================================================

The following shared conversion state information is defined in the
default formatting functions:

Command             Name                        Selectors                  Value
-------------------------------------------------------------------------------------
‘abbr’              ‘explained_commands’        string (first argument)    string
‘acronym’           ‘explained_commands’        string (first argument)    string
‘footnote’          ‘footnote_number’                                      integer
‘footnote’          ‘footnote_id_numbers’       string (footnote id)       integer
‘listoffloats’      ‘formatted_listoffloats’    string (normalized         integer
                                                argument)
‘menu’              ‘html_menu_entry_index’                                integer
‘printindex’        ‘formatted_index_entries’   index_entry (index entry   integer
                                                hash)
‘top’               ‘in_skipped_node_top’                                  integer
‘nodedescription’   ‘formatted_nodedescriptions’element                    integer
                                                (‘@nodedescription’ tree
                                                element)

   These shared information data correspond to:
‘explained_commands’
     Associate the explanation given in a previous ‘@abbr’ or ‘@acronym’
     second argument to first ‘@abbr’ or ‘@acronym’ arguments.
‘footnote_number’
     The current number of footnotes formatted in document.
‘footnote_id_numbers’
     Associate a footnote identifier, typically used in hyperlink
     reference, to the number of time the corresponding footnote was
     formatted.  More than one corresponds to very rare cases, for
     instance a footnote in ‘@copying’ and multiple ‘@insertcopying’.
‘formatted_listoffloats’
     Associate a list of float type to the number of time it was
     formatted.
‘html_menu_entry_index’
     Current number of menu entries in a menu.  Reset to 0 at ‘@menu’
     beginning.
‘formatted_index_entries’
     Associate an index entry to the number of time it was formatted.
‘in_skipped_node_top’
     Set to 1 in a ‘Top’ node being skipped, in case
     ‘NO_TOP_NODE_OUTPUT’ is set.
‘formatted_nodedescriptions’
     Associate a ‘@nodedescription’ tree element to the number of time
     it was formatted.

15 Translations in Output and Customization
*******************************************

Translated strings can be specified in customization functions, for
@-commands without arguments (see Simple Customization for Commands
Without Arguments), for direction strings (see Direction Strings
Customization) and for specific elements headings such as footnotes,
contents or about (see Special Units Information Customization).
Translated strings can also be inserted in the output in user-defined
customization functions, by using specific functions for
internationalization of strings, ‘cdt’, ‘cdt_string’ or ‘pcdt’ (see
(texi2any_internals)Texinfo::Convert::Converter Translations in output
documents).

   It is possible to customize the translated strings, in order to
change the translations of the strings translated in the default case.
If new translated strings are added, it is even required to use
translated strings customization to add translations for the added
strings.

   See (texinfo)Internationalization of Document Strings for additional
information on the default case.

15.1 Internationalization of Strings Function
=============================================

The subroutines ‘cdt’, ‘cdt_string’ or ‘pcdt’, are used for translated
strings:

 -- Function: $TRANSLATED_TREE = $CONVERTER->cdt ($STRING,
          \%VARIABLES_HASH, $TRANSLATION_CONTEXT)
 -- Function: $TRANSLATED_STRING = $CONVERTER->cdt_string ($STRING,
          \%VARIABLES_HASH, $TRANSLATION_CONTEXT)
 -- Function: $TRANSLATED_TREE = $CONVERTER->pcdt ($TRANSLATION_CONTEXT,
          $STRING, \%VARIABLES_HASH)
     $STRING is the string to be translated, \%VARIABLES_HASH is a hash
     reference holding the variable parts of the translated string.
     $TRANSLATION_CONTEXT is an optional translation context that limits
     the search of the translated string to that context (see
     (gettext)Contexts).

     The result returned is a Perl Texinfo tree for ‘cdt’ and ‘pcdt’ and
     a string for ‘cdt_string’.  With ‘cdt_string’ the substitutions may
     only be strings.

     If called as ‘pcdt’, $TRANSLATION_CONTEXT is not optional and is
     the first argument.

   With ‘cdt’ and ‘pcdt’, when the string is expanded as Texinfo, and
converted to a Texinfo tree in Perl, the arguments are substituted; for
example, ‘{arg_name}’ is replaced by the corresponding actual argument,
which should be a Texinfo tree element.  With ‘cdt_string’, the string
should already be converted, the arguments are substituted as strings;
for example ‘{arg_name}’ is replaced by the corresponding actual
argument, which should be a string.

   In the following example, ‘{date}’, ‘{program_homepage}’ and
‘{program}’ are the arguments of the string.  Since they are used in
‘@uref’, their order in the formatted output depends on the formatting
and is not predictable.  ‘{date}’, ‘{program_homepage}’ and ‘{program}’
are substituted after the expansion, which means that they should
already be Texinfo tree elements.

       $converter->cdt('Generated @emph{@today{}} using '
        .'@uref{{homepage}, @emph{{program}}}.',
           { 'homepage' => { 'text' => $converter->get_conf('PACKAGE_URL') },
             'program' => { 'text' => $converter->get_conf('PROGRAM') }});

   An example of combining conversion with translation:
     $converter->convert_tree($converter->cdt(
            '{explained_string} ({explanation})',
            {'explained_string' => {'type' => '_converted',
                                    'text' => $result},
             'explanation' => {'type' => '_converted',
                               'text' => $explanation_result}}),
                              "convert explained $cmdname");

   In the default case, the functions from the ‘Texinfo::Translations’
module are used for translated strings through converter functions.  It
is possible to use user-defined functions instead as seen next.  See
(texi2any_internals)Texinfo::Translations for more on
‘Texinfo::Translations’.

   In ‘texi2any’ code, ‘cdt’ and ‘cdt_string’ are also used to mark
translated strings for tools extracting translatable strings to produce
template files.  ‘pcdt’ is used to mark translated string with a
translation context associated.

15.2 Translated Strings Customization
=====================================

To customize strings translations, register the
‘format_translate_message’ function reference:

 -- Function Reference: $TRANSLATED_STRING format_translate_message
          ($CONVERTER, $STRING, $LANG, $TRANSLATION_CONTEXT)
     $STRING is the string to be translated, $LANG is the language.
     $TRANSLATION_CONTEXT is an optional translation context.

     The result returned should be the translated string.  The result
     returned may also be ‘undef’, in which case the translation is done
     as if the function reference had not been defined.

     See Internationalization of Strings Function for more information
     on strings translations function arguments.

   This function reference is not set in the default case, in the
default case ‘translate_string’ from the ‘Texinfo::Translations’ module
is called (see Internationalization of Strings Function).  See
Registering Specific Formating Functions for information on how to
register and get the function reference.

   Here is an example with new translated strings added and definition
of ‘format_translate_message’ to translate the strings:

     texinfo_register_no_arg_command_formatting('error', undef, undef,
                                                     undef, 'error-->');
     my %translations = (
      'fr' => {
                'error-->' => {'' => 'erreur-->',},
                # ...
              },
      'de' => {
                'error-->' => {'' => 'Fehler-->',},
                # ...
              }
      # ...
     );

     sub my_format_translate_message($$$;$)
     {
       my ($self, $string, $lang, $translation_context) = @_;
       $translation_context = '' if (!defined($translation_context));
       if (exists($translations{$lang})
           and exists($translations{$lang}->{$string})
           and exists($translations{$lang}->{$string}
                                       ->{$translation_context})) {
         my $translation = $translations{$lang}->{$string}
                                           ->{$translation_context};
         return $translation;
       }
       return undef;
     }

     texinfo_register_formatting_function('format_translate_message',
                                       \&my_format_translate_message);

15.3 Translation Contexts
=========================

Translation contexts may be set to avoid ambiguities for translated
strings, in particular when the strings are short (see
(gettext)Contexts).  Translation contexts are set for translated
direction strings (see Direction Strings) and for special output units
headings (see Special Units Information Customization).

   For direction strings, the translation context is based on the
direction name (see Directions), with ‘direction’ prepended and another
string prepended, depending on the type of string:

‘button’
     ‘button label’ is prepended

‘description’
     ‘description’ is prepended

‘text’
     ‘string’ is prepended

   For example, the ‘Top’ direction ‘button’ direction string
translation context is ‘Top direction button label’.

   As an exception, the ‘This’ direction has ‘(current section)’
prepended to have a more explicit translation context.  The ‘This’
direction ‘text’ direction string translation context is thus ‘This
(current section) direction string’.

   For special output unit headings, the translation context is obtained
by prepending ‘section heading’ to the special output unit variety (see
Table 16.1: Special Units Varieties).  For example, the ‘footnotes’
special output unit variety heading translation context is ‘footnotes
section heading’.

   Here is an example, which could be used with a similar function
registered as in the example above (see New translated strings example):

     texinfo_register_direction_string_info('Forward', 'text', undef,
                                            'Forward');
     texinfo_register_special_unit_info('heading', 'contents',
                                   'The @emph{Table of Contents}');

     my %translations = (
       'fr' => {
              'The @emph{Table of Contents}' => {'contents section heading'
                            => '@result{} La @emph{Table des mati@`eres}',},
              'Forward' => {'Forward direction string'
                            => 'Vers l\'avant @result{}',},
               }
        ...
     );

   Other translated strings may also be associated with translation
contexts.  The translation template file
‘po_document/texinfo_document.pot’ in the source directory of Texinfo
contains the translated strings appearing in all the output formats.

16 Customizing Footnotes, Tables of Contents and About
******************************************************

Some customization is specific for different special output units
content formatting, especially when the formatting is not done in a
separate output unit (see Output Units), but some customization is
relevant for all the special units.  The formatting of special units
bodies is handled the same for all the special units, when formatted as
separate units.

   To specify a special unit in those contexts, the special units
varieties are used, as described in Table 16.1: Special Units Varieties.

Special Unit              Special Unit Variety
-------------------------------------------------
Table of contents         ‘contents’
Short table of contents   ‘shortcontents’
Footnotes                 ‘footnotes’
About                     ‘about’

Table 16.1: Association of special elements names with their special
element variety

   The variety of special elements is the special unit hash value
associated with the ‘special_unit_variety’ key.

   To get information on the special output unit variety associated with
an @-command command name, use ‘command_name_special_unit_information’:

 -- Function: ($SPECIAL_UNIT_VARIETY, \%OUTPUT_UNIT, $CLASS_BASE,
          $OUTPUT_UNIT_DIRECTION) =
          $CONVERTER->command_name_special_unit_information
          ($COMMAND_NAME)
     $COMMAND_NAME is an @-command name without the leading @.  If the
     $COMMAND_NAME is not associated with a special output unit, returns
     ‘undef’.  Otherwise, return the $SPECIAL_UNIT_VARIETY (see Table
     16.1: Special Units Varieties), the \%OUTPUT_UNIT output unit, a
     $CLASS_BASE string for HTML class attribute and the
     $OUTPUT_UNIT_DIRECTION direction corresponding to that special
     elements (see Directions).

   In the current setup, special output units are associated with
‘@contents’, ‘@shortcontents’ and ‘@summarycontents’ and with
‘@footnote’.

16.1 Special Units Information Customization
============================================

To customize special output units formatting, a simple possibility is to
change the information associated with the special output units.

   The following items common to all the special units may be
customized:

‘class’
     String for special element HTML class attributes.

‘direction’
     Direction corresponding to the special element.  See Directions.

‘heading’
     Special element heading Texinfo code.

‘heading_tree’
     Special element heading Texinfo tree.

‘order’
     Index determining the sorting order of special elements.

‘file_string’
     File string portion prepended to the special element file names,
     such as ‘_toc’.

‘target’
     A string representing the target of the special element, typically
     used as id attribute and in href attribute.

   The heading string is set with ‘heading’, and should be a Texinfo
code string.  ‘heading_tree’ cannot be set directly, but can be
retrieved.  It is determined from ‘heading’ after translation and
conversion to a Texinfo tree.

   To set the information, use ‘texinfo_register_special_unit_info’ in
an init file:

 -- Function: texinfo_register_special_unit_info ($item_type,
          $special_unit_variety, $value)
     Set $ITEM_TYPE information for the special unit variety
     $SPECIAL_UNIT_VARIETY to $VALUE.  $VALUE may be ‘undef’, or an
     empty string, but only ‘heading’ and ‘target’ should be set to that
     value as a non-empty value is needed for the other items for
     formatting.

   To get the list of varieties, use ‘get_special_unit_info_varieties’:

 -- Function: $LIST = $CONVERTER->get_special_unit_info_varieties
          ($ITEM_TYPE)
     $ITEM_TYPE is the type of information to be retrieved as described
     above.  The list of the special units varieties with information
     for the $ITEM_TYPE is returned.

   To retrieve the information for formatting, use ‘special_unit_info’:

 -- Function: $LIST_OR_VALUE = $CONVERTER->special_unit_info
          ($ITEM_TYPE, $SPECIAL_UNIT_VARIETY)
     $ITEM_TYPE is the type of information to be retrieved as described
     above.  $SPECIAL_UNIT_VARIETY is a special unit variety, the
     corresponding value is returned.

     The value returned is translated and converted to a Texinfo tree
     for ‘heading_tree’.

16.2 Customizing Footnotes
==========================

In the default case footnotes are numbered.  If ‘NUMBER_FOOTNOTES’ is
set to 0, a ‘*’ is used instead, or the ‘NO_NUMBER_FOOTNOTE_SYMBOL’
customization variable value, if set.

   Redefinition of ‘@footnote’ conversion reference and footnote
formatting references is needed for further customization.

   ‘@footnote’ @-commands appearing in the Texinfo elements tree are
converted like any other elements associated with @-commands (see
Command Tree Element Conversion Functions).  It is therefore possible to
redefine their formatting by registering a user defined function.

   To pass information on footnotes between the conversion function
processing the ‘@footnote’ command at the location they appear in the
document and the functions formatting their argument elsewhere, two
functions are available: ‘register_footnote’ to be called where they
appear in the document, and ‘get_pending_footnotes’ to be called where
they are formatted.

 -- Function: $CONVERTER->register_footnote (\%element, $footnote_id,
          $foot_in_doc_id, $number_in_doc, $footnote_location_filename,
          $multi_expanded_region)
     \%ELEMENT is the footnote Texinfo tree element.  $FOOTNOTE_ID is
     the identifier for the location where the footnote arguments are
     expanded.  $FOOT_IN_DOC_ID is the identifier for the location where
     the footnote appears in the document.  $NUMBER_IN_DOC is the number
     of the footnote in the document.  $FOOTNOTE_LOCATION_FILENAME is
     the filename of the output unit of the footnote in the document.
     If the footnote appears in a region that is expanded multiple
     times, the information on the expansion is $MULTI_EXPANDED_REGION
     (see Other Dynamic Information).

   ‘register_footnote’ is normally called in the ‘@footnote’ @-command
conversion function reference.  The default conversion function also
call ‘command_href’ to link to the location where the footnote text will
be expanded (see Target Tree Element Link).

 -- Function: \@PENDING_FOOTNOTES_INFORMATION =
          $CONVERTER->get_pending_footnotes ()
     Returns in \@PENDING_FOOTNOTES_INFORMATION the information gathered
     in ‘register_footnote’.  Each of the array reference element in
     \@PENDING_FOOTNOTES_INFORMATION is an array reference containing
     the arguments of ‘register_footnote’ in the same order.

   The formatting of footnotes content is done by the
‘format_footnotes_sequence’ formatting reference (see Registering
Specific Formating Functions):

 -- Function Reference: $FOOTNOTES_SEQUENCE format_footnotes_sequence
          ($CONVERTER)
     Formats and returns the footnotes that need to be formatted.  This
     function normally calls ‘get_pending_footnotes’.  The default
     function also calls ‘footnote_location_href’ to link to the
     location in the document where the footnote appeared, and the
     ‘format_single_footnote’ formatting function to format a single
     footnote.

   The formatting of one footnote is done by the
‘format_single_footnote’ formatting reference:

 -- Function Reference: $FOOTNOTE format_single_footnote ($CONVERTER,
          \%ELEMENT, $FOOTNOTE_ID, $NUMBER_IN_DOC,
          $FOOTNOTE_LOCATION_HREF, $FOOTNOTE_MARK)
     Formats and returns a single footnote.  \%ELEMENT is the footnote
     Texinfo tree element.  $FOOTNOTE_ID is the identifier for the
     location where the footnote arguments are expanded.  $NUMBER_IN_DOC
     is the number of the footnote in the document.
     $FOOTNOTE_LOCATION_HREF is the href that links to the footnote
     location in the main document.  $FOOTNOTE_MARK is the footnote
     number or mark.

   If footnotes are in a separate output unit (see Output Units), the
default footnote special output unit body formatting function calls
‘format_footnotes_sequence’ (see Special Unit Body Formatting
Functions).

   If the footnotes are not in a separate output unit, or there is no
separate unit because there is only one output unit or no output unit,
the ‘format_footnotes_segment’ formatting reference is called when
pending footnotes need to be formatted.  This function reference can be
replaced by a user defined function.

 -- Function Reference: $FOOTNOTES_SEGMENT format_footnotes_segment
          ($CONVERTER)
     Returns the footnotes formatted.  In the default case, the function
     reference calls ‘format_footnotes_sequence’ and also sets up a
     header with ‘format_heading_text’ (see Basic Formatting
     Customization), using the customization variables
     ‘FOOTNOTE_END_HEADER_LEVEL’ and the special ‘footnotes’ element
     ‘heading’ information (see Special Units Information
     Customization).

   To get the id of a footnote in the main document, use
‘footnote_location_target’:

 -- Function: $TARGET = $CONVERTER->footnote_location_target
          (\%FOOTNOTE_ELEMENT)
     Return the id for the location of the footnote \%FOOTNOTE_ELEMENT
     in the main document (where the footnote number or symbol appears).

   To get an href to link to a footnote location in the main document,
use ‘footnote_location_href’:

 -- Function: $HREF = $CONVERTER->footnote_location_href
          (\%FOOTNOTE_ELEMENT, $SOURCE_FILENAME, $SPECIFIED_TARGET,
          $TARGET_FILENAME)
     Return string for linking to \%FOOTNOTE_ELEMENT location in the
     main document with ‘’.  $SOURCE_FILENAME is the file the
     link comes from.  If not set, the current file name is used.
     $SPECIFIED_TARGET is an optional identifier that overrides the
     target identifier if set.  $TARGET_FILENAME is an optional file
     name that overrides the file name href part if set.

   See Target Tree Element Link to get link information for the location
where footnote text is output.

16.3 Contents and Short Table of Contents Customization
=======================================================

You can set the customization variable ‘CONTENTS_OUTPUT_LOCATION’ to
determine where the table of contents and short table of content are
output in the document (see (texinfo)HTML Output Structure
Customization):

‘after_top’
     The tables of contents are output at the end of the ‘@top’ section,
     to have the main location for navigation in the whole document
     early on.  This is in line with ‘FORMAT_MENU’ set to ‘sectiontoc’
     with sectioning command being used in HTML for navigation rather
     than menus.  This is the default.

‘inline’
     The tables of content are output where the corresponding @-command,
     for example ‘@contents’, is set.  This behavior is consistent with
     ‘texi2dvi’.

‘separate_element’
     The tables of contents are output in separate output units, either
     at the end of the document if the output is unsplit or in separate
     files if not.  This makes sense when menus are used for navigation
     with ‘FORMAT_MENU’ set to ‘menu’.

‘after_title’
     The tables of contents are merged into the title material, which in
     turn is not output by default; see HTML Title Page Customization.

   You can set other customization variables to modify table of contents
links formatting (see (texinfo)File Names and Links Customization for
HTML) and change the HTML code inserted before and after the tables of
contents (see (texinfo)Customization of HTML Code Inserted).

   Finally, the following function reference provides even more control
over the table of contents and short table of contents formatting
reference:

 -- Function Reference: $TOC_RESULT format_contents ($CONVERTER,
          $COMMAND_NAME, \%ELEMENT, $FILENAME)
     $COMMAND_NAME is the @-command name without leading @, should be
     ‘contents’, ‘shortcontents’ or ‘summarycontents’.  \%ELEMENT is
     optional.  It corresponds to the $COMMAND_NAME Texinfo tree
     element, but it is only set if ‘format_contents’ is called from a
     Texinfo tree element conversion, and not as a special element body
     formatting.  $FILENAME is optional and should correspond to the
     filename where the formatting happens, for links.

     In the default function, structuring information is used to format
     the table of contents (see Converter General Information), and
     ‘command_contents_href’ and ‘command_href’ (see Target Tree Element
     Link) are used for links.  If $FILENAME is unset, the current file
     name is used, using ‘$converter->current_filename()’.

     Return formatted table of contents or short table of contents.

   If contents are in a separate output unit (see Output Units), the
default contents and shortcontents special element body formatting
function calls ‘format_contents’ (see Special Unit Body Formatting
Functions).  Otherwise, ‘format_contents’ is called in the conversion of
heading @-command, in title page formatting, and in ‘@contents’
conversion function, depending on the ‘CONTENTS_OUTPUT_LOCATION’ value.

   To get id and link href of sectioning commands in table of contents
and short table of contents, use ‘command_contents_target’ and
‘command_contents_href’:

 -- Function: $TARGET = $CONVERTER->command_contents_target
          (\%SECTIONING_ELEMENT, $CONTENTS_OR_SHORTCONTENTS)
     Returns the id for the location of \%SECTIONING_ELEMENT sectioning
     element in the table of contents, if $CONTENTS_OR_SHORTCONTENTS is
     ‘contents’, or in the short table of contents, if
     $CONTENTS_OR_SHORTCONTENTS is set to ‘shortcontents’ or
     ‘summarycontents’.

 -- Function: $HREF = $CONVERTER->command_contents_href
          (\%SECTIONING_ELEMENT, $CONTENTS_OR_SHORTCONTENTS,
          $SOURCE_FILENAME)
     Return string for linking to the \%SECTIONING_ELEMENT sectioning
     element location in the table of contents, if
     $CONTENTS_OR_SHORTCONTENTS is ‘contents’ or in the short table of
     contents, if $CONTENTS_OR_SHORTCONTENTS is set to ‘shortcontents’
     or ‘summarycontents’.  $SOURCE_FILENAME is the file the link comes
     from.  If not set, the current file name is used.  Returns ‘undef’
     if no string is found or the string is empty.

16.4 About Special Output Unit Customization
============================================

The default About output unit has an explanation of the buttons used in
the document, controlled by ‘SECTION_BUTTONS’.  The formatting of this
is influenced by the ‘text’, ‘description’ and ‘example’ direction
strings (see Direction Strings) and by ‘ACTIVE_ICONS’ (see Simple
Navigation Panel Customization).

   ‘PROGRAM_NAME_IN_ABOUT’ can also be used to change the beginning of
the About output unit formatting.

   If the above is not enough and you want to control exactly the
formatting of the about unit, the ‘about’ special output unit body
reference function may be overridden (see Special Unit Body Formatting
Functions).

16.5 Special Unit Body Formatting Functions
===========================================

In addition to the formatting possibilities available with the default
special output units formatting presented previously, it is also
possible to control completely how a separate special output unit is
formatted.

   To register body formating user defined functions for special output
units (see Output Units), the special output units varieties are used,
as described in Table 16.1: Special Units Varieties.  Special element
body formatting user defined functions are registered with
‘texinfo_register_formatting_special_unit_body’:

 -- Function: texinfo_register_formatting_special_unit_body
          ($special_unit_variety, \&handler)
     $SPECIAL_UNIT_VARIETY is the element variety (see Table 16.1:
     Special Units Varieties).  \&HANDLER is the user defined function
     reference.

   The call of the user defined functions is:
 -- Function Reference: $TEXT special_unit_body ($CONVERTER,
          $SPECIAL_UNIT_VARIETY, \%SPECIAL_UNIT)
     $CONVERTER is a converter object.  $SPECIAL_UNIT_VARIETY is the
     unit variety.  \%SPECIAL_UNIT is the special output unit.

     The $TEXT returned is the formatted special output unit body.

   To call a special output unit body formatting function from user
defined code, the function reference should first be retrieved using
‘special_unit_body_formatting’:

 -- Function: \&SPECIAL_UNIT_BODY_FORMATTING =
          $CONVERTER->special_unit_body_formatting
          ($SPECIAL_UNIT_VARIETY)
     $SPECIAL_UNIT_VARIETY is the special output unit variety.  Returns
     the conversion function reference for $VARIETY, or ‘undef’ if there
     is none, which should not happen for the special output units
     described in this manual.

   For example:
     my $footnotes_element_body
      = &{$converter->special_unit_body_formatting('footnotes')}(
                                        $converter, 'footnotes', $element);

   It is possible to have access to the default conversion function
reference.  The function used is:

 -- Function: \&DEFAULT_SPECIAL_UNIT_BODY_FORMATTING =
          $CONVERTER->defaults_special_unit_body_formatting
          ($SPECIAL_UNIT_VARIETY)
     $SPECIAL_UNIT_VARIETY is the special output unit variety.  Returns
     the default conversion function reference for
     $SPECIAL_UNIT_VARIETY, or ‘undef’ if there is none, which should
     not happen for the special output units described in this manual.

   See Customizing Footnotes for more on footnotes formatting.  See
Contents and Short Table of Contents Customization for more on the
‘contents’ and ‘shortcontents’ formatting.  See About Special Output
Unit Customization for more on the ‘about’ special output unit body
formatting.

17 Customizing HTML Footers, Headers and Navigation Panels
**********************************************************

‘texi2any’ provides for customization of the HTML page headers, footers,
and navigation panel.  (These are unrelated to the headings and
"footings" produced in TeX output; see Page Headings:
(texinfo)Headings.)

   In the event that your needs are not met by setting customization
variables (see (texinfo)Customization of Navigation and Headers) and
changing the navigation buttons (see Simple Navigation Panel
Customization), you can completely control the formatting of navigation
panels by redefining function references.  See Registering Specific
Formating Functions for information on how to register the function
references.

   In a nutshell, element header and footer formatting function
determines the button directions list to use and calls navigation header
formatting.  The navigation header formatting adds some formatting if
needed, but mostly calls the navigation panel formatting.  The
navigation panel can call buttons formatting.

   All the formatting functions take a converter object as first
argument.

17.1 Navigation Panel Button Formatting
=======================================

The function reference ‘format_button’ does the formatting of one
button, corresponding, in general, to a link to a direction:

 -- Function Reference: $FORMATTED_BUTTON format_button ($CONVERTER,
          $BUTTON, $SOURCE_COMMAND)
     $BUTTON holds the specification of the button (see Buttons
     Display).  $SOURCE_COMMAND is an optional argument, the @-command
     the link comes from.

     Returns the formatted result in $FORMATTED_BUTTON.

     The buttons images can be formatted with ‘format_button_icon_img’
     (see below).

     Simple navigation panel customization (see Simple Navigation Panel
     Customization), ‘USE_ACCESSKEY’, ‘USE_REL_REV’ and direction
     strings customization (see Direction Strings Customization) can be
     relevant for the formatting of a button.

   To get direction strings typically used for formatting of buttons or
hyperrefs leading to that direction, use ‘direction_string’:

 -- Function: $STRING = $CONVERTER->direction_string ($DIRECTION,
          $STRING_TYPE, $CONTEXT)
     Retrieve the $DIRECTION (see Directions) string of type
     $STRING_TYPE (see Direction Strings).  $CONTEXT is ‘normal’ or
     ‘string’.  See Init File Expansion Contexts.  If $CONTEXT is
     ‘undef’, the ‘normal’ context is assumed.  The string will be
     translated if needed.  May return ‘undef’.

   To get the Texinfo special output unit associated with a special
output unit direction, such as ‘About’ or ‘Contents’, as well as output
unit associated with other global directions, such as ‘Top’ or ‘Index’,
use use ‘global_direction_unit’:

 -- Function: \%OUTPUT_UNIT = $CONVERTER->global_direction_unit
          ($DIRECTION)
     Return the output unit associated with direction $DIRECTION, or
     ‘undef’ if the direction is not a global output unit direction nor
     a special output unit direction or the associated special output
     unit is not output.

   To get link information for relative and global directions, use
‘from_element_direction’:

 -- Function: $RESULT = $CONVERTER->from_element_direction ($DIRECTION,
          $TYPE, $SOURCE_ELEMENT, $SOURCE_FILENAME, $SOURCE_COMMAND)
     Return a string for linking to $DIRECTION, or the information to be
     used for a hyperlink to $DIRECTION, depending on $TYPE.  The
     possible values for $TYPE are described in Output Unit Direction
     Information Type.

     $SOURCE_ELEMENT is the output unit the link comes from.  If not
     set, the current output unit is used.  $SOURCE_FILENAME is the file
     the link comes from.  If not set, the current file name is used.
     $SOURCE_COMMAND is an optional argument, the @-command the link
     comes from.  It is only used for messages.

   ‘format_button_icon_img’ formatting function can be redefined.  In
the default case, it is called for an active direction, if ‘ICONS’ is
set, when formatting a navigation panel button.

 -- Function Reference: $TEXT format_button_icon_img ($CONVERTER,
          $BUTTON, $ICON, $NAME)
     $BUTTON is a button name, typically obtained from the ‘button’
     direction string (see Direction Strings).  $ICON is an image file
     name to be used as icon.  $NAME is the direction heading, typically
     formatted in string context.  See Init File Expansion Contexts.

     Returns a formatted icon image.

   See Directions for the list of directions.

17.2 Navigation Panel and Navigation Header Formatting
======================================================

The overall display of navigation panels is controlled via this function
reference, ‘format_navigation_header’:

 -- Function Reference: $NAVIGATION_TEXT format_navigation_header
          ($CONVERTER, \@BUTTONS, $COMMAND_NAME, \%ELEMENT)
     \@BUTTONS is an array reference holding the specification of the
     buttons for the navigation panel (see Simple Navigation Panel
     Customization).  \%ELEMENT is the element in which the navigation
     header is formatted.  $COMMAND_NAME is the associated command
     (sectioning command or ‘@node’).  It may be ‘undef’ for special
     output units.

     Returns the formatted navigation header and panel.  The navigation
     panel itself can be formatted with a call to
     ‘format_navigation_panel’.

     The customization variable ‘VERTICAL_HEAD_NAVIGATION’ should be
     relevant (see (texinfo)Customization of Navigation and Headers).

   The navigation panel display is controlled via
‘format_navigation_panel’:

 -- Function Reference: $NAVIGATION_TEXT format_navigation_panel
          ($CONVERTER, \@BUTTONS, $COMMAND_NAME, \%ELEMENT, $VERTICAL)
     \@BUTTONS is an array reference holding the specification of the
     buttons for that navigation panel.  \%ELEMENT is the element in
     which the navigation header is formatted.  $COMMAND_NAME is the
     associated command (sectioning command or ‘@node’).  It may be
     ‘undef’ for special elements.  $VERTICAL is true if the navigation
     panel should be vertical.

     Returns the formatted navigation panel in $NAVIGATION_TEXT.  The
     buttons in the navigation panel can be formatted with a call to
     ‘format_button’ (see format_button).

17.3 Element Header and Footer Formatting
=========================================

By default, the function associated with ‘format_element_header’ formats
the header and navigation panel of an output unit.

 -- Function Reference: $FORMATTED_HEADER format_element_header
          ($CONVERTER, $COMMAND_NAME, \%ELEMENT, \%OUTPUT_UNIT)
     \%ELEMENT is the element in which the navigation header is
     formatted (sectioning command, ‘@node’ or special output unit).
     $COMMAND_NAME is the associated command name.  It may be ‘undef’
     for special output units.  \%OUTPUT_UNIT is the associated output
     unit (see Texinfo Tree Elements in User Defined Functions).

     Returns the formatted navigation header and panel.

     In the default code, the function reference select a buttons list
     (see Simple Navigation Panel Customization).  The navigation header
     can then be formatted with a call to ‘format_navigation_header’
     (see format_navigation_header).  It is also possible to format
     directly the navigation panel, depending on customization variables
     values and location in file.

   Similarly, the function associated with ‘format_element_footer’
formats the footer and navigation panel of a output unit.

 -- Function Reference: $FORMATTED_FOOTER format_element_footer
          ($CONVERTER, $OUTPUT_UNIT_TYPE, \%OUTPUT_UNIT, $CONTENT,
          $COMMAND)
     \%OUTPUT_UNIT is the output unit in which the navigation footer is
     formatted.  $OUTPUT_UNIT_TYPE is the associated type.  $CONTENT is
     the formatted element content.  $CONTENT can be ‘undef’.  $COMMAND
     is an optional argument, the @-command associated with the
     \%OUTPUT_UNIT.

     Returns the formatted navigation footer and panel.

     In the default code, the function reference select a buttons list
     (see Simple Navigation Panel Customization).  The navigation header
     can then be formatted with a call to ‘format_navigation_header’
     (see format_navigation_header).

     Many customization variables have an effect on the footer
     formatting, such as ‘SPLIT’ (see (texinfo)HTML Splitting),
     customization variables used for the customization of headers such
     as ‘HEADERS’ or ‘WORDS_IN_PAGE’ (see (texinfo)Customization of
     Navigation and Headers) and customization variables setting
     inserted HTML code such as ‘DEFAULT_RULE’ (see
     (texinfo)Customization of HTML Code Inserted).

   To select the list of buttons for header and footer formatting, it
may be handy to be able to determine if the output unit being formatted
is the Top output unit.  To determine if a output unit is associated
with the top output unit, use ‘unit_is_top_output_unit’:

 -- Function: $IS_TOP_OUTPUT_UNIT = $CONVERTER->unit_is_top_output_unit
          (\%OUTPUT_UNIT)
     Returns true if the \%OUTPUT_UNIT output unit is the Top output
     unit (see Output Units) and is either associated with the ‘@top’
     sectioning command or with the ‘Top’ ‘@node’.

17.4 Element Counters in Files
==============================

The position of the output unit being formatted in its file or the total
number of elements output to a file is interesting for navigation header
and footer formatting, for instance to format end of files, decide which
type navigation header or footer is needed and whether a rule should be
output.

   To get information on tree elements unit counter in files, use
‘count_elements_in_filename’:

 -- Function: $COUNT = $CONVERTER->count_elements_in_filename
          ($SPECIFICATION, $FILE_NAME)
     Return output unit counter for $FILE_NAME, or ‘undef’ if the
     counter does not exist.  The counter returned depends on
     $SPECIFICATION:

     _current_
          Return the number of output units associated with $FILE_NAME
          having already been processed.
     _remaining_
          Return the number of output units associated with $FILE_NAME
          that remains to be processed.
     _total_
          Return the total number of output units associated with the
          file.

   For example, to get the total number of output units associated with
the file of a node element:
     my $file_name = $converter->command_filename($node_element);
     my $number = $converter->count_elements_in_filename('total',
                                                       $file_name);

18 Beginning and Ending Files
*****************************

The end of file (footers) formatting function reference is called from
the converter after all the output units in the file have been
converted.  The beginning of file (headers) formatting function
reference is called right after the footers formatting function
reference.

   See Registering Specific Formating Functions for information on how
to register and get the functions references.

18.1 Customizing HTML File Beginning
====================================

You can set the variable ‘DOCTYPE’ to replace the default.  The
‘DOCTYPE’ is output at the very beginning of each output file.

   You can define the variable ‘EXTRA_HEAD’ to add text within the
‘’ HTML element.  Similarly, the value of ‘AFTER_BODY_OPEN’ is
added just after ‘’ is output.  These variables are empty by
default.

   The ‘’ element attributes may be set by defining the
customization variable ‘BODY_ELEMENT_ATTRIBUTES’.

   By default, the encoding name from ‘OUTPUT_ENCODING_NAME’ is used.
If this variable is not defined, it is automatically determined.

   A date is output in the header if ‘DATE_IN_HEADER’ is set.

   The description from ‘@documentdescription’ (or a value set as a
customization variable) is used in the header (see
(texinfo)@documentdescription).

   ‘’ elements are used in the header if ‘USE_LINKS’ is set, in
which case ‘LINKS_BUTTONS’ determines which links are used and the ‘rel’
direction string (see Direction Strings) determines the link type
associated with the ‘rel’ attribute.  See Simple Navigation Panel
Customization.

   You can set ‘HTML_ROOT_ELEMENT_ATTRIBUTES’ to add attributes to the
‘’ element.

   If ‘SECTION_NAME_IN_TITLE’ is set, the sectioning command argument is
used in the ‘’ HTML element instead of the ‘@node’ argument.

   You can also set a JavaScript browsing interface with customization
variables (see (texinfo)JavaScript Interface and Licenses).  See
(texinfo)Customization of Navigation and Headers for more information on
customization variables in the main Texinfo manual.  See
(texinfo)Customization of HTML Code Inserted for more on insertion of
HTML code in output.

   The following function references give full control over the page
header formatting done at the top of each HTML output file.

 -- Function Reference: $FILE_BEGIN format_begin_file ($CONVERTER,
          $FILENAME, \%OUTPUT_UNIT)
     $FILENAME is the name of the file output.  \%OUTPUT_UNIT is the
     first output unit of the file.  This function should print the page
     header, in HTML, including the ‘<body>’ element.

18.2 Customizing HTML File End
==============================

You can define the variable ‘PRE_BODY_CLOSE’ to add text just before the
HTML ‘</body>’ element.  Nothing is added by default.  If
‘PROGRAM_NAME_IN_FOOTER’ is set, the date and name of the program that
generated the output are output in the footer.

   By default, the JavaScript license web labels page is formatted and
output at the end of file (see (texinfo)JavaScript Interface and
Licenses).

   The ‘format_end_file’ function reference give full control over the
page footer formatting done at the bottom of each HTML output file.

 -- Function Reference: $FILE_END format_end_file ($CONVERTER,
          $FILENAME, \%OUTPUT_UNIT)
     $FILENAME is the name of the file output.  \%OUTPUT_UNIT is the
     last output unit of the file.  This function should print the page
     footer, including the ‘</body>’ element.

18.3 Associating Information to an Output File
==============================================

To be able to retrieve information associated with the current file, in
general for the file begin or end formatting,
‘register_file_information’ can be used to associate integer
information, and ‘get_file_information’ to retrieve that information.

 -- Function: $CONVERTER->register_file_information ($key, $value)
     Associate the current output file name file to the key $KEY, itself
     associated with the integer value $VALUE.

 -- Function: $VALUE = $CONVERTER->get_file_information ($KEY,
          $FILE_NAME)
     Return the value associated with the key $KEY and file name
     $FILE_NAME.

   By default, this interface is used to get ‘mathjax’ file information
registered when converting math @-commands to insert references to
MathJax scripts in file beginning (see (texinfo)MathJax scripts) and
license information in end of files (see (texinfo)JavaScript Interface
and Licenses).

19 Titlepage, CSS and Redirection Files
***************************************

19.1 HTML Title Page Customization
==================================

If ‘SHOW_TITLE’ is not set, no title is output.  ‘SHOW_TITLE’ is ‘undef’
in the default case.  If ‘undef’, ‘SHOW_TITLE’ is set if
‘NO_TOP_NODE_OUTPUT’ is set.  The "title page" is used to format the
HTML title if ‘USE_TITLEPAGE_FOR_TITLE’ is set, otherwise the
‘simpletitle’ is used.  ‘USE_TITLEPAGE_FOR_TITLE’ is set in the default
case.  See (texinfo)HTML Output Structure Customization.

   The following functions references provides full control on the title
and "title page" formatting:

 -- Function Reference: $TITLE_TITLEPAGE format_title_titlepage
          ($CONVERTER)
     Returns the formatted title or "title page" text.

     In the default case, return nothing if ‘SHOW_TITLE’ is not set,
     return the output of ‘format_titlepage’ if
     ‘USE_TITLEPAGE_FOR_TITLE’ is set, and otherwise output a simple
     title based on ‘simpletitle’.

 -- Function Reference: $TITLE_PAGE format_titlepage ($CONVERTER)
     Returns the formatted "title page" text.

     In the default case, the ‘@titlepage’ is used if found in global
     information, otherwise ‘simpletitle’ is used (see Converter General
     Information).

19.2 CSS Customization
======================

CSS in HTML output can already be modified with command line options and
customization variables (see (texinfo)HTML CSS). More control of the
generated CSS is available through functions.

19.2.1 Customization of CSS Rules, Imports and Selectors
--------------------------------------------------------

Information on static CSS data used in conversion and more direct
control over rules, CSS imports and selectors is available through
functions.  The information is about CSS rules lines and CSS import
lines obtained from parsing ‘--css-include=FILE’ files, as described in
(texinfo)HTML CSS, and CSS style rules associated with HTML elements and
class attributes used in the conversion to HTML. The CSS style rules
selectors are, classically, ‘ELEMENT.CLASS’ strings with ELEMENT an HTML
element and CLASS an attribute class associated with that element.

   The function used are ‘css_get_info’ and ‘css_get_selector_style’ to
get information and ‘css_add_info’ and ‘css_set_selector_style’ to
modify:

 -- Function: $CONVERTER->css_get_info ($specification)
 -- Function: $CONVERTER->css_get_selector_style ($selector)
 -- Function: $CONVERTER->css_add_info ($specification, $css_info)
 -- Function: $CONVERTER->css_set_selector_style ($selector, $css_style)

     Those functions can only be used on a converter $CONVERTER, from
     functions registered and called with a converter.  $SPECIFICATION
     is ‘'rules'’ to get information on or set information for CSS rules
     lines and ‘'imports'’ to get information on or set information for
     CSS import lines.  Any other value for $SPECIFICATION corresponds
     to HTML elements and class attributes selectors, and can be used to
     get the list of selectors.

     With ‘css_get_info’, array references corresponding to
     $SPECIFICATION are returned.

     ‘css_get_selector_style’ returns the CSS style corresponding to the
     HTML element and class attribute selector $SELECTOR, or ‘undef’ if
     not found.

     With ‘css_add_info’, $CSS_INFO is an additional entry added to CSS
     rules lines if $SPECIFICATION is set to ‘'rules'’ or an additional
     entry added to CSS import lines if $SPECIFICATION is set to
     ‘'imports'’.

     With ‘css_set_selector_style’, $SELECTOR is a CSS rule selector and
     the associated style rule is set to $CSS_STYLE.

   Some examples of use:

     my @all_included_rules = $converter->css_get_info('rules');
     my $all_default_selector_styles = $converter->css_get_info('styles');
     my $titlefont_header_style = $converter->css_get_selector_style('h1.titlefont');

     $converter->css_set_selector_style('h1.titlefont', 'text-align:center');
     $converter->css_add_info('imports', "\@import \"special.css\";\n");

   Note that the CSS selectors and associated style rules that can be
accessed and modified will not necessarily end up in the HTML output.
They are output only if the HTML element and class corresponding to a
selector is seen in the document.  See Customizing the CSS Lines.

   The simplest way to modify CSS rules would be to use a function
registered for the ‘structure’ stage:

     sub my_function_set_some_css {
       my $converter = shift;

       $converter->css_set_selector_style('h1.titlefont',
                                          'text-align:center');
       # ... calls to  $converter->css_add_info();
     }

     texinfo_register_handler('structure', \&my_function_set_some_css);

19.2.2 Customizing the CSS Lines
--------------------------------

The CSS ELEMENT.CLASS that appeared in a file, gathered through
‘html_attribute_class’ calls (see Formatting HTML Element with Classes)
are available through the ‘html_get_css_elements_classes’ function:

 -- Function: \@CSS_ELEMENT_CLASSES =
          $CONVERTER->html_get_css_elements_classes ($FILE_NAME)
     Returns a reference on an array containing ‘element.class’ pairs of
     elements and classes appearing in $FILE_NAME.

   It is possible to change completely how CSS lines are generated by
redefining the following function reference:

 -- Function Reference: $CSS_LINES format_css_lines ($CONVERTER,
          $FILE_NAME)
     This function returns the CSS lines and ‘<script>’ HTML element for
     $FILE_NAME.

     In the default case, the function reference uses ‘CSS_REFS’
     corresponding to command-line ‘--css-ref’,
     ‘html_get_css_elements_classes’, ‘css_get_info’ and
     ‘css_element_class_rule’ (see Customization of CSS Rules Imports
     and Selectors) to determine the CSS lines.

19.3 Customizing Node Redirection Pages
=======================================

Node redirection pages are output if ‘NODE_FILES’ is set (see
(texinfo)Invoking texi2any).

   It is possible to change completely how node redirection pages are
generated by redefining the following function reference:

 -- Function Reference: $NODE_REDIRECTION_FILE_CONTENT
          format_node_redirection_page ($CONVERTER, \%ELEMENT)
     \%ELEMENT is a node element needing a redirection page.  A
     redirection page is needed if the node file name is not the file
     name expected for HTML cross manual references (see (texinfo)HTML
     Xref).

     Returns the content of the node redirection file.

Appendix A Specific Functions for Specific Elements
***************************************************

Links on Texinfo Perl modules functions or descriptions of functions
that can be used for specific elements formatting:

‘@today’
     See Texinfo::Convert::Utils::expand_today:
     (texi2any_internals)Texinfo::Convert::Utils $tree =
     expand_today($converter).

‘@verbatiminclude’
     See Texinfo::Convert::Utils::expand_verbatiminclude:
     (texi2any_internals)Texinfo::Convert::Utils $tree =
     expand_verbatiminclude($registrar, $configuration_information,
     $verbatiminclude).

‘@def*’ @-commands
     See Texinfo::Convert::Utils::definition_arguments_content:
     (texi2any_internals)Texinfo::Convert::Utils $arguments =
     definition_arguments_content($element).  See
     Texinfo::Convert::Utils::definition_category_tree:
     (texi2any_internals)Texinfo::Convert::Utils $tree =
     definition_category_tree($converter, $def_line).

‘@float’
     See Texinfo::Convert::Converter::float_name_caption:
     (texi2any_internals)Texinfo::Convert::Converter ($caption,
     $prepended) = $converter->float_name_caption ($float).  Can be
     called as ‘$converter->float_name_caption’.

accent @-commands
     See Texinfo::Convert::Converter::xml_accent:
     (texi2any_internals)Texinfo::Convert::Converter $result =
     xml_accent($text, $accent_command, $in_upper_case,
     $use_numeric_entities).  Can be called as ‘$converter->xml_accent’.

     See Texinfo::Convert::Converter::xml_numeric_entity_accent:
     (texi2any_internals)Texinfo::Convert::Converter $result =
     xml_numeric_entity_accent($accent_command_name, $text).

     See Texinfo::Convert::Converter::convert_accents:
     (texi2any_internals)Texinfo::Convert::Converter $result =
     $converter->convert_accents($accent_command, \&format_accents,
     $in_upper_case).

text element
     See
     Texinfo::Convert::Converter::xml_format_text_with_numeric_entities:
     (texi2any_internals)Texinfo::Convert::Converter $formatted_text =
     $converter->xml_format_text_with_numeric_entities($text).  Can be
     called as ‘$converter->xml_format_text_with_numeric_entities’.

‘@item’ in ‘@table’ and similar @-commands
     See Texinfo::Convert::Converter::table_item_content_tree:
     (texi2any_internals)Texinfo::Convert::Converter $table_item_tree =
     $converter->table_item_content_tree($element, $contents).  Can be
     called as ‘$converter->table_item_content_tree’.

‘@*index’ ‘@subentry’
     See Texinfo::Convert::Converter::comma_index_subentries_tree:
     (texi2any_internals)Texinfo::Convert::Converter $contents_array
     $converter->comma_index_subentries_tree($entry).  Can be called as
     ‘$converter->comma_index_subentries_tree’.

global informative commands (‘@contents’, ‘@footnotestyle’ ...)
     See Texinfo::Common::set_informative_command_value:
     (texi2any_internals)Texinfo::Common
     set_informative_command_value($configuration_information,
     $element).

heading commands, such as ‘@subheading’
     See Texinfo::Common::section_level:
     (texi2any_internals)Texinfo::Common $level =
     section_level($section).  This function would work for sectioning
     commands too, but for sectioning commands,
     ‘section->{'extra'}->{'section_level'}’ can also be used.  See
     Texinfo Tree Elements in User Defined Functions.

sectioning commands
     See Texinfo::Structuring::section_level_adjusted_command_name:
     (texi2any_internals)Texinfo::Structuring $command_name =
     section_level_adjusted_command_name($element).

‘@itemize’
     ‘@itemize’ normally have an @-command as argument.  If, instead,
     the argument is some Texinfo code,
     ‘html_convert_css_string_for_list_mark’ can be used to convert that
     argument to text usable in CSS style specifications.

      -- Function: $TEXT_FOR_CSS =
               $CONVERTER->html_convert_css_string_for_list_mark
               (\%ELEMENT, $EXPLANATION)
          \%ELEMENT is the Texinfo element that is converted to CSS
          text.  In general, it is ‘$itemize->{'args'}->[0]’, with
          ‘$itemize’ an ‘@itemize’ Texinfo tree element.  $EXPLANATION
          is an optional string describing what is being done that can
          be useful for debugging.

          Returns \%ELEMENT formatted as text suitable for CSS.

   The ‘Texinfo::Convert::NodeNameNormalization’ converter, used for
normalization of labels, exports functions that can be used on Texinfo
elements trees to obtain strings that are unique and can be used in
attributes.  See
(texi2any_internals)Texinfo::Convert::NodeNameNormalization.

Appendix B Functions Index
**************************

* Menu:

* $CONVERTER->associate_pending_formatted_inline_content: Inline Text Containers Formatting.
                                                             (line 3221)
* $CONVERTER->cancel_pending_formatted_inline_content: Inline Text Containers Formatting.
                                                             (line 3193)
* $CONVERTER->cdt:                       Internationalization of Strings Function.
                                                             (line 3509)
* $CONVERTER->cdt_string:                Internationalization of Strings Function.
                                                             (line 3511)
* $CONVERTER->close_html_lone_element:   Closing Lone HTML Element.
                                                             (line 1760)
* $CONVERTER->close_registered_sections_level: Heading Commands Formatting.
                                                             (line 2725)
* $CONVERTER->command_contents_href:     Contents and Short Table of Contents Customization.
                                                             (line 3993)
* $CONVERTER->command_contents_target:   Contents and Short Table of Contents Customization.
                                                             (line 3985)
* $CONVERTER->command_conversion:        Command Tree Element Conversion Functions.
                                                             (line 2622)
* $CONVERTER->command_filename:          Target Tree Element Link.
                                                             (line 2804)
* $CONVERTER->command_href:              Target Tree Element Link.
                                                             (line 2808)
* $CONVERTER->command_id:                Target Tree Element Link.
                                                             (line 2801)
* $CONVERTER->command_name_special_unit_information: Customizing Footnotes, Tables of Contents and About.
                                                             (line 3715)
* $CONVERTER->command_node:              Target Tree Element Link.
                                                             (line 2882)
* $CONVERTER->command_root_element_command: Target Tree Element Link.
                                                             (line 2850)
* $CONVERTER->command_text:              Target Tree Element Link.
                                                             (line 2820)
* $CONVERTER->command_tree:              Target Tree Element Link.
                                                             (line 2841)
* $CONVERTER->convert_tree:              Texinfo Tree Conversion Functions.
                                                             (line 2089)
* $CONVERTER->convert_tree_new_formatting_context: Texinfo Tree Conversion Functions.
                                                             (line 2112)
* $CONVERTER->converter_document_error:  Error Reporting in User Defined Functions.
                                                             (line 1221)
* $CONVERTER->converter_document_warn:   Error Reporting in User Defined Functions.
                                                             (line 1223)
* $CONVERTER->converter_line_error:      Error Reporting in User Defined Functions.
                                                             (line 1232)
* $CONVERTER->converter_line_warn:       Error Reporting in User Defined Functions.
                                                             (line 1234)
* $CONVERTER->count_elements_in_filename: Element Counters in Files.
                                                             (line 4295)
* $CONVERTER->css_add_info:              Customization of CSS Rules Imports and Selectors.
                                                             (line 4481)
* $CONVERTER->css_get_info:              Customization of CSS Rules Imports and Selectors.
                                                             (line 4479)
* $CONVERTER->css_get_selector_style:    Customization of CSS Rules Imports and Selectors.
                                                             (line 4480)
* $CONVERTER->css_set_selector_style:    Customization of CSS Rules Imports and Selectors.
                                                             (line 4482)
* $CONVERTER->current_filename:          Other Dynamic Information.
                                                             (line 2016)
* $CONVERTER->current_output_unit:       Other Dynamic Information.
                                                             (line 2010)
* $CONVERTER->default_command_conversion: Command Tree Element Conversion Functions.
                                                             (line 2637)
* $CONVERTER->default_command_open:      Command Tree Element Opening Functions.
                                                             (line 2673)
* $CONVERTER->default_formatting_function: Registering Specific Formating Functions.
                                                             (line 2355)
* $CONVERTER->default_output_unit_conversion: Output Units Conversion Functions.
                                                             (line 3312)
* $CONVERTER->default_type_conversion:   Type Tree Element Conversion Functions.
                                                             (line 3005)
* $CONVERTER->default_type_open:         Type Tree Element Opening Functions.
                                                             (line 3062)
* $CONVERTER->defaults_special_unit_body_formatting: Special Unit Body Formatting Functions.
                                                             (line 4069)
* $CONVERTER->define_shared_conversion_state: Define Get and Set Shared Conversion State.
                                                             (line 3367)
* $CONVERTER->define_shared_conversion_state <1>: Define Get and Set Shared Conversion State.
                                                             (line 3412)
* $CONVERTER->direction_string:          Navigation Panel Button Formatting.
                                                             (line 4133)
* $CONVERTER->encoded_output_file_name:  Encoding File Path Strings.
                                                             (line 1334)
* $CONVERTER->footnote_location_href:    Customizing Footnotes.
                                                             (line 3904)
* $CONVERTER->footnote_location_target:  Customizing Footnotes.
                                                             (line 3896)
* $CONVERTER->force_conf:                Conversion Customization Variables.
                                                             (line 1314)
* $CONVERTER->formatting_function:       Registering Specific Formating Functions.
                                                             (line 2347)
* $CONVERTER->from_element_direction:    Navigation Panel Button Formatting.
                                                             (line 4156)
* $CONVERTER->get_associated_formatted_inline_content: Inline Text Containers Formatting.
                                                             (line 3225)
* $CONVERTER->get_conf:                  Conversion Customization Variables.
                                                             (line 1275)
* $CONVERTER->get_converter_indices_sorted_by_letter: Specific Formatting for Indices.
                                                             (line 2920)
* $CONVERTER->get_element_root_command_element: Target Tree Element Link.
                                                             (line 2890)
* $CONVERTER->get_file_information:      Associating Information to an Output File.
                                                             (line 4413)
* $CONVERTER->get_info:                  Converter General Information.
                                                             (line 1810)
* $CONVERTER->get_pending_footnotes:     Customizing Footnotes.
                                                             (line 3838)
* $CONVERTER->get_pending_formatted_inline_content: Inline Text Containers Formatting.
                                                             (line 3205)
* $CONVERTER->get_shared_conversion_state: Define Get and Set Shared Conversion State.
                                                             (line 3397)
* $CONVERTER->get_special_unit_info_varieties: Special Units Information Customization.
                                                             (line 3781)
* $CONVERTER->global_direction_unit:     Navigation Panel Button Formatting.
                                                             (line 4146)
* $CONVERTER->html_attribute_class:      Formatting HTML Element with Classes.
                                                             (line 1728)
* $CONVERTER->html_convert_css_string_for_list_mark: Specific Functions for Specific Elements.
                                                             (line 4668)
* $CONVERTER->html_get_css_elements_classes: Customizing the CSS Lines.
                                                             (line 4541)
* $CONVERTER->html_image_file_location_name: Image Formatting.
                                                             (line 2937)
* $CONVERTER->in_align:                  Other Dynamic Information.
                                                             (line 2022)
* $CONVERTER->in_code:                   Text Tree Elements Conversion.
                                                             (line 3113)
* $CONVERTER->in_math:                   Text Tree Elements Conversion.
                                                             (line 3119)
* $CONVERTER->in_multi_expanded:         Other Dynamic Information.
                                                             (line 2042)
* $CONVERTER->in_multiple_conversions:   Other Dynamic Information.
                                                             (line 2029)
* $CONVERTER->in_non_breakable_space:    Text Tree Elements Conversion.
                                                             (line 3144)
* $CONVERTER->in_preformatted_context:   Conversion in Preformatted Context.
                                                             (line 1967)
* $CONVERTER->in_raw:                    Text Tree Elements Conversion.
                                                             (line 3125)
* $CONVERTER->in_space_protected:        Text Tree Elements Conversion.
                                                             (line 3151)
* $CONVERTER->in_string:                 Conversion in String Context.
                                                             (line 1946)
* $CONVERTER->in_upper_case:             Text Tree Elements Conversion.
                                                             (line 3139)
* $CONVERTER->in_verbatim:               Text Tree Elements Conversion.
                                                             (line 3132)
* $CONVERTER->inside_preformatted:       Conversion in Preformatted Context.
                                                             (line 1971)
* $CONVERTER->is_format_expanded:        Converter General Information.
                                                             (line 1803)
* $CONVERTER->label_command:             Target Tree Element Link.
                                                             (line 2766)
* $CONVERTER->output_unit_conversion:    Output Units Conversion Functions.
                                                             (line 3304)
* $CONVERTER->paragraph_number:          Other Dynamic Information.
                                                             (line 2055)
* $CONVERTER->pcdt:                      Internationalization of Strings Function.
                                                             (line 3513)
* $CONVERTER->preformatted_classes_stack: Conversion in Preformatted Context.
                                                             (line 1983)
* $CONVERTER->preformatted_number:       Other Dynamic Information.
                                                             (line 2056)
* $CONVERTER->register_file_information: Associating Information to an Output File.
                                                             (line 4409)
* $CONVERTER->register_footnote:         Customizing Footnotes.
                                                             (line 3820)
* $CONVERTER->register_opened_section_level: Heading Commands Formatting.
                                                             (line 2713)
* $CONVERTER->register_pending_formatted_inline_content: Inline Text Containers Formatting.
                                                             (line 3176)
* $CONVERTER->set_conf:                  Conversion Customization Variables.
                                                             (line 1286)
* $CONVERTER->special_unit_body_formatting: Special Unit Body Formatting Functions.
                                                             (line 4053)
* $CONVERTER->special_unit_info:         Special Units Information Customization.
                                                             (line 3789)
* $CONVERTER->substitute_html_non_breaking_space: Substituting Non Breaking Space.
                                                             (line 1786)
* $CONVERTER->top_block_command:         Other Dynamic Information.
                                                             (line 2062)
* $CONVERTER->type_conversion:           Type Tree Element Conversion Functions.
                                                             (line 2997)
* $CONVERTER->unit_is_top_output_unit:   Element Header and Footer Formatting.
                                                             (line 4277)
* $CONVERTER->url_protect_file_text($INPUT_STRING): Protection of URLs.
                                                             (line 1432)
* $CONVERTER->url_protect_url_text($INPUT_STRING): Protection of URLs.
                                                             (line 1418)
* command_conversion:                    Command Tree Element Conversion Functions.
                                                             (line 2513)
* command_open:                          Command Tree Element Opening Functions.
                                                             (line 2664)
* external_target_non_split_name($CONVERTER,: Customizing External Node Output Names.
                                                             (line 1606)
* external_target_split_name($CONVERTER,: Customizing External Node Output Names.
                                                             (line 1592)
* format_begin_file:                     Customizing HTML File Beginning.
                                                             (line 4374)
* format_button:                         Navigation Panel Button Formatting.
                                                             (line 4114)
* format_button_icon_img:                Navigation Panel Button Formatting.
                                                             (line 4173)
* format_comment:                        Basic Formatting Customization.
                                                             (line 2377)
* format_contents:                       Contents and Short Table of Contents Customization.
                                                             (line 3956)
* format_css_lines:                      Customizing the CSS Lines.
                                                             (line 4549)
* format_element_footer:                 Element Header and Footer Formatting.
                                                             (line 4248)
* format_element_header:                 Element Header and Footer Formatting.
                                                             (line 4228)
* format_end_file:                       Customizing HTML File End.
                                                             (line 4395)
* format_footnotes_segment:              Customizing Footnotes.
                                                             (line 3883)
* format_footnotes_sequence:             Customizing Footnotes.
                                                             (line 3849)
* format_heading_text:                   Basic Formatting Customization.
                                                             (line 2387)
* format_navigation_header:              Navigation Panel and Navigation Header Formatting.
                                                             (line 4190)
* format_navigation_panel:               Navigation Panel and Navigation Header Formatting.
                                                             (line 4209)
* format_node_redirection_page:          Customizing Node Redirection Pages.
                                                             (line 4569)
* format_program_string:                 Basic Formatting Customization.
                                                             (line 2415)
* format_protect_text:                   Basic Formatting Customization.
                                                             (line 2420)
* format_separate_anchor:                Basic Formatting Customization.
                                                             (line 2439)
* format_single_footnote:                Customizing Footnotes.
                                                             (line 3861)
* format_title_titlepage:                HTML Title Page Customization.
                                                             (line 4440)
* format_titlepage:                      HTML Title Page Customization.
                                                             (line 4449)
* format_translate_message:              Translated Strings Customization.
                                                             (line 3574)
* label_target_name:                     Customizing Output Target Names.
                                                             (line 1535)
* node_file_name:                        Customizing Output File Names.
                                                             (line 1490)
* output_unit_conversion:                Output Units Conversion Functions.
                                                             (line 3293)
* sectioning_command_target_name:        Customizing Output Target Names.
                                                             (line 1555)
* special_unit_body:                     Special Unit Body Formatting Functions.
                                                             (line 4042)
* special_unit_target_file_name:         Customizing Special Elements Output Names.
                                                             (line 1625)
* stage_handler:                         Init File Calling at Different Stages.
                                                             (line 1681)
* texinfo_add_to_option_list:            Modifying Main Program Array Variables.
                                                             (line  426)
* texinfo_get_conf:                      Getting Main Program Variables Values.
                                                             (line  462)
* texinfo_register_accent_command_formatting: Simple Customization of Accent Commands.
                                                             (line  679)
* texinfo_register_command_formatting:   Command Tree Element Conversion Functions.
                                                             (line 2507)
* texinfo_register_command_opening:      Command Tree Element Opening Functions.
                                                             (line 2657)
* texinfo_register_direction_string_info: Direction Strings Customization.
                                                             (line 1001)
* texinfo_register_file_id_setting_function: Customizing Output-Related Names.
                                                             (line 1458)
* texinfo_register_formatting_function:  Registering Specific Formating Functions.
                                                             (line 2339)
* texinfo_register_formatting_special_unit_body: Special Unit Body Formatting Functions.
                                                             (line 4035)
* texinfo_register_handler:              Init File Calling at Different Stages.
                                                             (line 1670)
* texinfo_register_init_loading_error:   Init File Loading Error Reporting.
                                                             (line  477)
* texinfo_register_init_loading_warning: Init File Loading Error Reporting.
                                                             (line  478)
* texinfo_register_no_arg_command_formatting: Simple Customization for Commands Without Arguments.
                                                             (line  542)
* texinfo_register_output_unit_formatting: Output Units Conversion Functions.
                                                             (line 3286)
* texinfo_register_special_unit_info:    Special Units Information Customization.
                                                             (line 3771)
* texinfo_register_style_command_formatting: Simple Output Customization for Simple Commands with Braces.
                                                             (line  626)
* texinfo_register_type_format_info:     Simple Customization of Containers.
                                                             (line  707)
* texinfo_register_type_formatting:      Type Tree Element Conversion Functions.
                                                             (line 2979)
* texinfo_register_type_opening:         Type Tree Element Opening Functions.
                                                             (line 3047)
* texinfo_register_upper_case_command:   Customization of Commands Converting to Uppercase.
                                                             (line  607)
* texinfo_remove_from_option_list:       Modifying Main Program Array Variables.
                                                             (line  428)
* texinfo_set_format_from_init_file:     Setting Main Program String Variables.
                                                             (line  400)
* texinfo_set_from_init_file:            Setting Main Program String Variables.
                                                             (line  368)
* Texinfo::Common::get_build_constant:   Getting Build Constants.
                                                             (line  311)
* type_conversion:                       Type Tree Element Conversion Functions.
                                                             (line 2985)
* type_open:                             Type Tree Element Opening Functions.
                                                             (line 3053)
* unit_file_name:                        Customizing Output File Names.
                                                             (line 1501)

Appendix C Variables Index
**************************

* Menu:

* ACTIVE_ICONS:                          Simple Navigation Panel Customization.
                                                             (line 1041)
* ACTIVE_ICONS <1>:                      Simple Navigation Panel Customization.
                                                             (line 1099)
* AFTER_BODY_OPEN:                       Customizing HTML File Beginning.
                                                             (line 4335)
* BODY_ELEMENT_ATTRIBUTES:               Customizing HTML File Beginning.
                                                             (line 4340)
* BUTTONS_REL, In file beginning:        Customizing HTML File Beginning.
                                                             (line 4352)
* CHAPTER_BUTTONS:                       Simple Navigation Panel Customization.
                                                             (line 1071)
* CHAPTER_FOOTER_BUTTONS:                Simple Navigation Panel Customization.
                                                             (line 1065)
* COMMAND_LINE_ENCODING:                 Decoding File Path Strings.
                                                             (line 1383)
* CONTENTS_OUTPUT_LOCATION:              Contents and Short Table of Contents Customization.
                                                             (line 3920)
* CONTENTS_OUTPUT_LOCATION, Output unit: Output Units.       (line  802)
* DATE_IN_HEADER:                        Customizing HTML File Beginning.
                                                             (line 4346)
* DO_ABOUT:                              Output Units.       (line  816)
* DOC_ENCODING_FOR_INPUT_FILE_NAME:      Encoding File Path Strings.
                                                             (line 1345)
* DOC_ENCODING_FOR_OUTPUT_FILE_NAME:     Encoding File Path Strings.
                                                             (line 1334)
* DOCTYPE:                               Customizing HTML File Beginning.
                                                             (line 4332)
* explained_commands:                    Shared Conversion State in Default Formatting.
                                                             (line 3455)
* EXTRA_HEAD:                            Customizing HTML File Beginning.
                                                             (line 4335)
* footnote_id_numbers:                   Shared Conversion State in Default Formatting.
                                                             (line 3460)
* footnote_number:                       Shared Conversion State in Default Formatting.
                                                             (line 3458)
* formatted_index_entries:               Shared Conversion State in Default Formatting.
                                                             (line 3471)
* formatted_listoffloats:                Shared Conversion State in Default Formatting.
                                                             (line 3465)
* formatted_nodedescriptions:            Shared Conversion State in Default Formatting.
                                                             (line 3476)
* HANDLER_FATAL_ERROR_LEVEL:             Init File Calling at Different Stages.
                                                             (line 1686)
* html_menu_entry_index:                 Shared Conversion State in Default Formatting.
                                                             (line 3468)
* HTML_ROOT_ELEMENT_ATTRIBUTES:          Customizing HTML File Beginning.
                                                             (line 4358)
* in_skipped_node_top:                   Shared Conversion State in Default Formatting.
                                                             (line 3473)
* INLINE_CSS_STYLE:                      Formatting HTML Element with Classes.
                                                             (line 1738)
* INPUT_FILE_NAME_ENCODING:              Encoding File Path Strings.
                                                             (line 1345)
* LINKS_BUTTONS:                         Simple Navigation Panel Customization.
                                                             (line 1079)
* LINKS_BUTTONS, In file beginning:      Customizing HTML File Beginning.
                                                             (line 4352)
* LOCALE_OUTPUT_FILE_NAME_ENCODING:      Encoding File Path Strings.
                                                             (line 1334)
* MESSAGE_ENCODING:                      Encoding File Path Strings.
                                                             (line 1349)
* MISC_BUTTONS:                          Simple Navigation Panel Customization.
                                                             (line 1075)
* NO_CSS:                                Formatting HTML Element with Classes.
                                                             (line 1738)
* NO_NUMBER_FOOTNOTE_SYMBOL:             Customizing Footnotes.
                                                             (line 3801)
* NO_TOP_NODE_OUTPUT:                    HTML Title Page Customization.
                                                             (line 4430)
* NODE_FOOTER_BUTTONS:                   Simple Navigation Panel Customization.
                                                             (line 1066)
* NUMBER_FOOTNOTES:                      Customizing Footnotes.
                                                             (line 3801)
* OUTPUT_ENCODING_NAME:                  Customizing HTML File Beginning.
                                                             (line 4343)
* PACKAGE:                               Getting Build Constants.
                                                             (line  316)
* PACKAGE_AND_VERSION:                   Getting Build Constants.
                                                             (line  318)
* PACKAGE_AND_VERSION_CONFIG:            Getting Build Constants.
                                                             (line  319)
* PACKAGE_CONFIG:                        Getting Build Constants.
                                                             (line  317)
* PACKAGE_NAME:                          Getting Build Constants.
                                                             (line  320)
* PACKAGE_NAME_CONFIG:                   Getting Build Constants.
                                                             (line  321)
* PACKAGE_URL:                           Getting Build Constants.
                                                             (line  324)
* PACKAGE_URL_CONFIG:                    Getting Build Constants.
                                                             (line  325)
* PACKAGE_VERSION:                       Getting Build Constants.
                                                             (line  322)
* PACKAGE_VERSION_CONFIG:                Getting Build Constants.
                                                             (line  323)
* PASSIVE_ICONS:                         Simple Navigation Panel Customization.
                                                             (line 1042)
* PASSIVE_ICONS <1>:                     Simple Navigation Panel Customization.
                                                             (line 1099)
* PRE_BODY_CLOSE:                        Customizing HTML File End.
                                                             (line 4383)
* PROGRAM_NAME_IN_ABOUT:                 About Special Output Unit Customization.
                                                             (line 4013)
* PROGRAM_NAME_IN_FOOTER:                Customizing HTML File End.
                                                             (line 4383)
* SECTION_BUTTONS:                       Simple Navigation Panel Customization.
                                                             (line 1057)
* SECTION_FOOTER_BUTTONS:                Simple Navigation Panel Customization.
                                                             (line 1064)
* SECTION_NAME_IN_TITLE:                 Customizing HTML File Beginning.
                                                             (line 4361)
* SHOW_TITLE:                            HTML Title Page Customization.
                                                             (line 4430)
* texinfo_document Gettext domain:       Internationalization of Strings Function.
                                                             (line 3506)
* TOP_BUTTONS:                           Simple Navigation Panel Customization.
                                                             (line 1082)
* TOP_FOOTER_BUTTONS:                    Simple Navigation Panel Customization.
                                                             (line 1083)
* USE_ACCESSKEY:                         Simple Navigation Panel Customization.
                                                             (line 1138)
* USE_LINKS:                             Customizing HTML File Beginning.
                                                             (line 4352)
* USE_REL_REV:                           Simple Navigation Panel Customization.
                                                             (line 1142)
* USE_TITLEPAGE_FOR_TITLE:               HTML Title Page Customization.
                                                             (line 4430)

Appendix D General Index
************************

* Menu:

* --init-file:                           Loading Init Files. (line  210)
* </body> tag, outputting:               Customizing HTML File End.
                                                             (line 4398)
* <body> tag, attributes of:             Customizing HTML File Beginning.
                                                             (line 4340)
* <body> tag, outputting:                Customizing HTML File Beginning.
                                                             (line 4376)
* <head> block, adding to:               Customizing HTML File Beginning.
                                                             (line 4335)
* About page, output unit:               Output Units.       (line  781)
* About special output unit, customizing: About Special Output Unit Customization.
                                                             (line 4007)
* Accent command named entities:         Simple Customization of Accent Commands.
                                                             (line  664)
* Accent commands, customizing HTML for: Simple Customization of Accent Commands.
                                                             (line  664)
* accesskey navigation:                  Simple Navigation Panel Customization.
                                                             (line 1138)
* associated_unit output unit:           Output Units in User Defined Functions.
                                                             (line 2276)
* Button specification, navigation panel: Simple Navigation Panel Customization.
                                                             (line 1049)
* Calling functions at different stages: Init File Calling at Different Stages.
                                                             (line 1639)
* Commands without arguments, customizing HTML for: Simple Customization for Commands Without Arguments.
                                                             (line  535)
* Constants:                             Getting Build Constants.
                                                             (line  307)
* Contents, customizing elements:        Contents and Short Table of Contents Customization.
                                                             (line 3920)
* Contexts for expansion in init files:  Init File Expansion Contexts.
                                                             (line  495)
* CSS customization:                     Customization of CSS Rules Imports and Selectors.
                                                             (line 4466)
* CSS customization <1>:                 Customizing the CSS Lines.
                                                             (line 4537)
* Customization of About special output unit: About Special Output Unit Customization.
                                                             (line 4007)
* Customization of tables of contents elements: Contents and Short Table of Contents Customization.
                                                             (line 3920)
* Customization variables, setting and getting: Managing Customization Variables.
                                                             (line  346)
* Customizing CSS, Imports:              Customization of CSS Rules Imports and Selectors.
                                                             (line 4466)
* Customizing CSS, Lines output:         Customizing the CSS Lines.
                                                             (line 4537)
* Customizing CSS, Rules:                Customization of CSS Rules Imports and Selectors.
                                                             (line 4466)
* Customizing CSS, Selectors:            Customization of CSS Rules Imports and Selectors.
                                                             (line 4466)
* Customizing HTML page footers:         Customizing HTML File End.
                                                             (line 4383)
* Customizing HTML page headers:         Element Header and Footer Formatting.
                                                             (line 4225)
* Customizing output file names:         Customizing Output File Names.
                                                             (line 1481)
* Customizing output target names:       Customizing Output Target Names.
                                                             (line 1527)
* Date, in header:                       Customizing HTML File Beginning.
                                                             (line 4346)
* Direction information type:            Output Unit Direction Information Type.
                                                             (line  928)
* Direction strings:                     Direction Strings.  (line  965)
* Direction strings, getting:            Navigation Panel Button Formatting.
                                                             (line 4130)
* Directions:                            Directions.         (line  834)
* Document description, in HTML output:  Customizing HTML File Beginning.
                                                             (line 4348)
* Document structure:                    Texinfo Tree Elements in User Defined Functions.
                                                             (line 2225)
* Document units:                        Output Units.       (line  750)
* Elements, main unit of output documents: Output Units.     (line  750)
* Encoding, in HTML output:              Customizing HTML File Beginning.
                                                             (line 4343)
* Error reporting, conversion:           Error Reporting in User Defined Functions.
                                                             (line 1214)
* Error reporting, loading:              Init File Loading Error Reporting.
                                                             (line  473)
* Expansion contexts, for init files:    Init File Expansion Contexts.
                                                             (line  495)
* FirstInFile direction variant:         Directions.         (line  919)
* Footer, customizing for HTML:          Customizing HTML File End.
                                                             (line 4383)
* Footnotes, output unit:                Output Units.       (line  781)
* Formatting functions, for navigation panel: Navigation Panel and Navigation Header Formatting.
                                                             (line 4187)
* Functions, calling at different stages: Init File Calling at Different Stages.
                                                             (line 1639)
* Global directions output units, getting: Navigation Panel Button Formatting.
                                                             (line 4141)
* Headers, customizing for HTML:         Element Header and Footer Formatting.
                                                             (line 4225)
* HTML customization for accent commands: Simple Customization of Accent Commands.
                                                             (line  664)
* HTML customization for commands without arguments: Simple Customization for Commands Without Arguments.
                                                             (line  535)
* HTML customization for simple commands: Simple Output Customization for Simple Commands with Braces.
                                                             (line  621)
* HTML determine commands converting to uppercase: Customization of Commands Converting to Uppercase.
                                                             (line  603)
* Icons, in navigation buttons:          Simple Navigation Panel Customization.
                                                             (line 1099)
* Id names, customizing:                 Customizing Output Target Names.
                                                             (line 1527)
* Init file basics:                      Init File Basics.   (line  266)
* Init file calling functions at different stages: Init File Calling at Different Stages.
                                                             (line 1639)
* Init file expansion contexts:          Init File Expansion Contexts.
                                                             (line  495)
* Init file namespace:                   Init File Namespace.
                                                             (line  285)
* Initialization files, loading:         Loading Init Files. (line  170)
* Insertion commands, customizing HTML for: Simple Customization for Commands Without Arguments.
                                                             (line  535)
* Links information:                     Directions.         (line  834)
* Loading init files:                    Loading Init Files. (line  170)
* Math expansion context:                Init File Expansion Contexts.
                                                             (line  515)
* Namespace, for init files:             Init File Namespace.
                                                             (line  285)
* Navigation panel button specification: Simple Navigation Panel Customization.
                                                             (line 1049)
* Navigation panel formatting functions: Navigation Panel and Navigation Header Formatting.
                                                             (line 4187)
* Navigation panel, simple customization of: Simple Navigation Panel Customization.
                                                             (line 1030)
* Normal expansion context:              Init File Expansion Contexts.
                                                             (line  500)
* Normal output units:                   Output Units.       (line  758)
* Output elements:                       Output Units.       (line  750)
* Output file names, customizing:        Customizing Output File Names.
                                                             (line 1481)
* Output unit directions:                Directions.         (line  834)
* Output units, defined:                 Output Units.       (line  755)
* Overview element, customizing:         Contents and Short Table of Contents Customization.
                                                             (line 3920)
* Overview, output unit:                 Output Units.       (line  781)
* Percent encoding:                      Protection of URLs. (line 1405)
* Perl namespaces, for init files:       Init File Namespace.
                                                             (line  285)
* Perl, language for init files:         Init File Basics.   (line  266)
* Preformatted expansion context:        Init File Expansion Contexts.
                                                             (line  503)
* Protecting, URL:                       Protection of URLs. (line 1405)
* rel navigation:                        Simple Navigation Panel Customization.
                                                             (line 1142)
* Search paths, for initialization files: Loading Init Files.
                                                             (line  170)
* Short table of contents element, customizing: Contents and Short Table of Contents Customization.
                                                             (line 3920)
* Short table of contents, output unit:  Output Units.       (line  781)
* Simple commands, customizing HTML for: Simple Output Customization for Simple Commands with Braces.
                                                             (line  621)
* Simple Customization, of navigation panel: Simple Navigation Panel Customization.
                                                             (line 1030)
* Special Elements file names, customizing: Customizing Special Elements Output Names.
                                                             (line 1622)
* Special Elements id names, customizing: Customizing Special Elements Output Names.
                                                             (line 1622)
* Special Elements target names, customizing: Customizing Special Elements Output Names.
                                                             (line 1622)
* String expansion context:              Init File Expansion Contexts.
                                                             (line  520)
* Style commands, customizing HTML for:  Simple Output Customization for Simple Commands with Braces.
                                                             (line  621)
* Table of contents, output unit:        Output Units.       (line  781)
* Target names, customizing:             Customizing Output Target Names.
                                                             (line 1527)
* texi2any-config.pm init files loaded:  Loading Init Files. (line  170)
* Texinfo tree output units:             Output Units.       (line  750)
* Texinfo::Convert::Converter, error reporting: Error Reporting in User Defined Functions.
                                                             (line 1214)
* Title page, customization:             HTML Title Page Customization.
                                                             (line 4430)
* Top output unit:                       Output Units.       (line  771)
* Translated direction strings:          Direction Strings.  (line  984)
* Type, of direction information:        Output Unit Direction Information Type.
                                                             (line  928)
* Unit type:                             Output Units in User Defined Functions.
                                                             (line 2266)
* unit_command element:                  Output Units in User Defined Functions.
                                                             (line 2276)
* URL protection:                        Protection of URLs. (line 1405)
* User defined functions, registering:   User Defined Functions are Registered.
                                                             (line 1157)