This manual is for GNU Texinfo ‘texi2any’ program output adaptation
using customization files (version 7.2, 21 October 2024).

   Copyright © 2013-2024 Free Software Foundation, Inc.

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

GNU Texinfo ‘texi2any’ Output Customization
*******************************************

Appendices

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 Global Customization Variables (texinfo)).  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 Invoking texi2any (texinfo)).

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
Customization Variables for @-Commands (texinfo).  For the
customization variables associated with command line options, see
Customization Variables and Options (texinfo).

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 @display (texinfo)) and ‘@example’ environments
     (see @example (texinfo)), and in menu comments.  The
     preformatted regions are usually rendered using ‘<pre>’ 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 Useful Highlighting (texinfo)).

_math context_
     Math (see ‘@math’ (texinfo)).  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
     ^?Texinfo (texi2any_internals)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 ‘&shy;’ to be output for ‘@-’ in normal,
preformatted (and math) and string context, call

     texinfo_register_no_arg_command_formatting('-', undef, '&shy;');

   If you want "‘<small>...</small>’" 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--&gt;’" 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--&gt;');

   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 Customization of HTML Code Inserted (texinfo)).

     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
‘<code>ARGUMENT</code>’ 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 HTML Features Customization (texinfo)).

   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 ‘&eacute;’ 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 ‘&inodot;’, 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
     ‘<pre>’ 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 ^?Texinfo (texi2any_internals)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
Customization of Navigation and Headers (texinfo)).

   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 Splitting Output (texinfo)).  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
     HTML Output Structure Customization (texinfo)).

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

_Top output unit_

     The top output unit is the highest output unit in the document
     structure.  If the document has an ‘@top’ section (see
     @top Command (texinfo)), it is the output unit associated with
     that section; otherwise, it is the output unit associated with the
     document's ‘@node Top’ (see The Top Node (texinfo)).  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).  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.

        • When generating HTML, the _Footnotes page_ should only be
          present if the footnotes appear on a separate page (see
          Footnote Styles (texinfo)).  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 Two Paths (texinfo)).

   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 ‘<link>’ elements if they are output in the HTML ‘<head>’.

‘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
^?Texinfo (texi2any_internals)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 ^?Texinfo (texi2any_internals)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 Customization Variables for @-Commands (texinfo)).

   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 Global Customization Variables (texinfo)).
     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 Global Customization Variables (texinfo).

   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’).
     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</a>";

 -- 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’).  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 File Names and Links Customization for HTML (texinfo)).

   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 HTML Xref (texinfo)).  You can specify
external node manuals URLs in cross-references customization files
(see HTML Xref Configuration (texinfo)).  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 File Names and Links Customization for HTML (texinfo)).

   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.

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 HTML CSS (texinfo)).
     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.'</span>'
       if ($open ne '');

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

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

HTML elements with an opening element, but no closing element, such as
‘<img>’ or ‘<link>’, 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 HTML Features Customization (texinfo)).

   Examples of use:
     $description = $converter->close_html_lone_element(
         "<meta name=\"description\" content=\"$description\"");

10.1.3 Substituting Non Breaking Space
--------------------------------------

A non-breaking code should be inserted using the ‘non_breaking_space’
information, taken from the general information (see Converter General Information),
using ‘get_info’:
     my $non_breaking_space = $converter->get_info('non_breaking_space');
     my $result = '<tr><td>' .$non_breaking_space. '</tr></td>';
   In that case, there is nothing more to do.

   If a ‘&nbsp;’ 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 ‘&nbsp;’ according to customization variables values.

   See HTML Features Customization (texinfo) 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 Conditional Commands (texinfo)), 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 @copying (texinfo)).

‘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
          ^?TexinfoDocument::floats_information^?:
          (texi2any_internals)Texinfo::Document $float_types =
          floats_information($document).

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

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

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

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

     See ^?Texinfo (texi2any_internals)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 @documentdescription (texinfo)).  See Init File Expansion Contexts.

‘expanded_formats’
     Information on output formats such as ‘html’ or ‘tex’ expansion
     (see Conditional Commands (texinfo)).  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 ‘<br>’, also taking into account
     ‘USE_XML_SYNTAX’ customization variable value.

‘non_breaking_space’
     Non breaking space, can be ‘&nbsp;’, 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 ‘&para;’, but also the corresponding
     numeric entity or encoded character based on ‘OUTPUT_CHARACTERS’
     and ‘USE_NUMERIC_ENTITY’ customization variables values.  See
     HTML Features Customization (texinfo).

‘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 HTML Output Structure Customization (texinfo)).

   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</a>";
     }

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
^?Texinfo (texi2any_internals)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 = '<var>' .$result. '</var>';
         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
     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' => ' <code>HTML</code> 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
^?Texinfo (texi2any_internals)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 ^?Texinfo (texi2any_internals)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
     Raise/lower sections (texinfo).

   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 ^?Texinfo (texi2any_internals)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.

   ^?Texinfo (texi2any_internals)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 ^?TexinfoConvert::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
     ‘<h2>$INPUT_TEXT</h2>’ 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 ^?TexinfoConvert::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 ‘<p>’ 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\"></p>";
     }

     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,
     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 HTML Output Structure Customization (texinfo)),
by changing the links formatting (see File Names and Links Customization for HTML (texinfo)),
the navigation panels
formatting (see Customization of Navigation and Headers (texinfo))
and the heading levels (see Specific Customization of HTML Formatting (texinfo)).

   ‘@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 ‘<div>’ 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, "</div>\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 ‘<a href>’ 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 = "<a href=\"$target_href\">$target_text</a>";

   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
           = "<a href=\"$associated_command_href\">"
               ."$associated_command_text</a>";
     } elsif (defined($associated_command_text)) {
       $entry_root_link = $associated_command_text;
     }

     my $formatted_entry = "<td><tr>$hyperlink</tr>"
                       ."<tr>$entry_root_link</tr></td>\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
     ^?TexinfoConvert::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' => ' <code>HTML</code> text ',
                        'type' => '_converted'};
       my $result = $converter->convert_tree({'type' => '_code',
                                        'contents' => \@contents });
       return "<p>".$result."</p>";
     }

     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' => ' <code>HTML</code> text ',
                        'type' => '_converted'};
       my $result = $converter->convert_tree({'type' => '_code',
                                        'contents' => \@contents });
       return "<p>".$prepended.$result."</p>";
     }

     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 ^?Texinfo (texi2any_internals)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
^?Texinfo (texi2any_internals)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 Internationalization of Document Strings (texinfo) 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
     Contexts (gettext)).

     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
^?Texinfo (texi2any_internals)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--&gt;');
     my %translations = (
      'fr' => {
                'error--&gt;' => {'' => 'erreur--&gt;',},
                # ...
              },
      'de' => {
                'error--&gt;' => {'' => 'Fehler--&gt;',},
                # ...
              }
      # ...
     );

     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
Contexts (gettext)).  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).  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 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),
     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 ‘<a href>’.  $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 HTML Output Structure Customization (texinfo)):

‘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 File Names and Links Customization for HTML (texinfo))
and change the HTML code inserted before and after the tables of
contents (see Customization of HTML Code Inserted (texinfo)).

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

   In the event that your needs are not met by setting customization
variables (see Customization of Navigation and Headers (texinfo)) 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 Customization of Navigation and Headers (texinfo)).

   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 HTML Splitting (texinfo)),
     customization variables used for the customization of headers such
     as ‘HEADERS’ or ‘WORDS_IN_PAGE’ (see Customization of Navigation and Headers (texinfo))
     and customization variables setting
     inserted HTML code such as ‘DEFAULT_RULE’ (see
     Customization of HTML Code Inserted (texinfo)).

   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
‘<head>’ HTML element.  Similarly, the value of ‘AFTER_BODY_OPEN’ is
added just after ‘<body>’ is output.  These variables are empty by
default.

   The ‘<body>’ 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
@documentdescription (texinfo)).

   ‘<link>’ 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
‘<html>’ element.

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

   You can also set a JavaScript browsing interface with customization
variables (see JavaScript Interface and Licenses (texinfo)).  See
Customization of Navigation and Headers (texinfo) for more information
on customization variables in the main Texinfo manual.  See
Customization of HTML Code Inserted (texinfo) 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 JavaScript Interface and Licenses (texinfo)).

   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 MathJax scripts (texinfo)) and
license information in end of files (see JavaScript Interface and Licenses (texinfo)).

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 HTML Output Structure Customization (texinfo).

   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 HTML CSS (texinfo)).  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
HTML CSS (texinfo), 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
Invoking texi2any (texinfo)).

   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 HTML Xref (texinfo)).

     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 ^?TexinfoConvert::Utils::expand_today^?:
     (texi2any_internals)Texinfo::Convert::Utils $tree =
     expand_today($converter).

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

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

‘@float’
     See ^?TexinfoConvert::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 ^?TexinfoConvert::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 ^?TexinfoConvert::Converter::xml_numeric_entity_accent^?:
     (texi2any_internals)^?Texinfo::Convert::Converter $result =
     xml_numeric_entity_accent($accent_command_name, $text)^?.

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

text element
     See
     ^?TexinfoConvert::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 ^?TexinfoConvert::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 ^?TexinfoConvert::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 ^?TexinfoCommon::set_informative_command_value^?:
     (texi2any_internals)^?Texinfo::Common
     set_informative_command_value($configuration_information,
     $element)^?.

heading commands, such as ‘@subheading’
     See ^?TexinfoCommon::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 ^?TexinfoStructuring::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
^?Texinfo (texi2any_internals)Convert::NodeNameNormalization^?::.