doc/texi2any_api.texi

\input texinfo.tex    @c -*-texinfo-*-

@c this is needed by old automake versions < 1.6.2, that are still used
@c in some platforms in 2024
@setfilename texi2any_api.info

@include version-texi2any_api.texi

@settitle GNU Texinfo @command{texi2any} Output Customization

@copying
This manual is for GNU Texinfo @command{texi2any} program output
adaptation using customization files (version @value{VERSION},
@value{UPDATED}).

Copyright @copyright{} 2013-2026 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, 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.
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* texi2any customization: (texi2any_api).
                                Customizing texi2any output
@end direntry

@titlepage
@title GNU Texinfo @command{texi2any} Output Customization
@subtitle for GNU Texinfo version @value{VERSION}, @value{UPDATED}

@page

@insertcopying
@end titlepage

@summarycontents
@contents


@node Top
@top @c @command{texi2any} Output Customization

@node Overview
@chapter Overview

@cartouche
@quotation Warning
All of this information, with the exception of command-line options
and search directories associated with command line options
(@pxref{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.
@end quotation
@end cartouche

This manual describes how to customize the @command{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
(@pxref{Global Customization Variables,,, texinfo, 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 @dfn{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.

@c Do we want to describe the tree in the manual?  It is already described
@c in (texi2any_internals)Texinfo::Parser TEXINFO TREE
@c  The tree structure will be described in future versions of the
@c manual.


@node Loading Init Files
@chapter Loading Initialization Files and Search Paths

@cindex Loading init files
@cindex Initialization files, loading
@cindex Search paths, for initialization files

@c @pindex texi2any-config.pm @r{init files loaded}
@cindex @file{texi2any-config.pm} init files loaded

@quotation Warning
The @file{texi2any-config.pm} file related paths and even the use
of @file{texi2any-config.pm} files is not definitive.
@end quotation

You can write so-called @dfn{initialization files}, or @dfn{init
files} for short, to modify almost every aspect of output formatting.
The program loads init files named @file{texi2any-config.pm} each time it
is run.  The directories lookup is based on the @url{https://specifications.freedesktop.org/basedir-spec/latest/, XDG Base
Directory Specification} with defaults based on installation directories.
The @file{texi2any-config.pm} files are looked for in the
following directories:

@table @file
@c @item /usr/share/texi2any/
@c (with @file{/usr/share/} the second default directory for @env{XDG_DATA_DIRS}
@c in the XDG Base Directory Specification)

@c @item /usr/local/share/texi2any/
@c (with @file{/usr/local/share} the first default directory for
@c @env{XDG_DATA_DIRS} in the XDG Base Directory Specification)

@item @var{datadir}/texi2any/
(where @var{datadir} is the system data directory specified at
compile-time, e.g., @file{/usr/local/share})

@c @item @env{XDG_DATA_DIRS}/texi2any
@c (for each directory in the @code{:} delimited @env{XDG_DATA_DIRS} environment
@c variable, in reverse order)

@c @item /etc/xdg/texi2any/
@c (with @file{/etc/xdg} the default directory for @env{XDG_CONFIG_DIRS}
@c in the XDG Base Directory Specification)

@item @env{XDG_CONFIG_DIRS}/texi2any
(for each directory in the @code{:} delimited @env{XDG_CONFIG_DIRS}
environment variable, in reverse order)

@item @var{sysconfdir}/xdg/texi2any/
(where @var{sysconfdir} is specified at compile time, e.g.,
@file{/usr/local/etc})

@item ~/.config/texi2any/
(where @code{~} is the current user's home directory, only if
@env{XDG_CONFIG_HOME} is not set)

@item @env{XDG_CONFIG_HOME}/texi2any
(with @env{XDG_CONFIG_HOME} an environment variable)

@item ./.texi2any/
(under the current directory)

@item ./
(the current directory)
@end table

All @file{texi2any-config.pm} files found are loaded, in the above order.
Thus, @file{./texi2any-config.pm} can override entries in, say,
@file{@var{datadir}/texi2any/texi2any-config.pm}.

@c @opindex --init-file
@cindex @option{--init-file}
However, the most common way to load an initialization file path is with
the @option{--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:

@enumerate
@item The current directory @file{./};

@item @file{./.texi2any/} under the current directory;

@item @file{@env{XDG_CONFIG_HOME}/texi2any} if the @env{XDG_CONFIG_HOME}
environment is set, otherwise @file{~/.config/texi2any/} where @code{~} is the
current user's home directory;

@item @file{@var{sysconfdir}/xdg/texi2any/}
where @var{sysconfdir} is the system configuration directory
specified at compile-time, e.g., @file{/usr/local/etc};

@item if the environment variable @env{XDG_CONFIG_DIRS} is set,
@file{@var{directory}/texi2any} for each @var{directory} in the
@code{:} delimited @env{XDG_CONFIG_DIRS} environment variable value;

@c @item @file{/etc/xdg/texi2any/}

@item @file{@var{datadir}/texi2any/}
Where @var{datadir} is the system data directory specified at
compile time, e.g., @file{/usr/local/share};

@c @item if the environment variable @env{XDG_DATA_DIRS} is set,
@c @var{directory}/texi2any for each @var{directory} in the
@c @code{:} delimited @env{XDG_DATA_DIRS} environment variable value;

@c @item @file{/usr/local/share/texi2any/}

@c @item @file{/usr/share/texi2any/}

@item @file{./.texinfo/init/} under the current directory;

@c @item @file{~/.texinfo/init/} under the current home directory;

@item @file{@env{XDG_CONFIG_HOME}/texinfo/init} if the @env{XDG_CONFIG_HOME}
environment is set, otherwise @file{~/.config/texinfo/init/} where @code{~} is
the current user's home directory;

@item @file{@var{sysconfdir}/xdg/texinfo/init/} with @var{sysconfdir} as above;

@item if the environment variable @env{XDG_CONFIG_DIRS} is set,
@file{@var{directory}/texinfo/init} for each @var{directory} in the
@code{:} delimited @env{XDG_CONFIG_DIRS} environment variable value;

@c @item @file{/etc/xdg/texinfo/init/}

@item @file{@var{datadir}/texinfo/init/} with @var{datadir} as above.

@c @item if the environment variable @env{XDG_DATA_DIRS} is set,
@c @file{@var{directory}/texinfo/init} for each @var{directory} in the
@c @code{:} delimited @env{XDG_DATA_DIRS} environment variable value;

@c @item @file{/usr/local/share/texinfo/init/}

@c @item @file{/usr/share/texinfo/init/}

@item @file{@var{datadir}/texinfo/ext/} with @var{datadir} as above.
@end enumerate

The @file{@var{datadir}/texinfo/ext/} directory contains the
init files directly loaded from @command{texi2any} code.  When loaded from
@command{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 @option{--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
@option{--conf-dir} option (@pxref{Invoking @command{texi2any},,, texinfo, Texinfo}).


@node Init File Basics
@chapter Init File Basics

@cindex Init file basics
@cindex Perl, language for init files

Init files are written in Perl, and by convention have extension
@file{.init} or @file{.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 @code{Texinfo::Convert::HTML} module which implements
almost all the Texinfo HTML function described in this manual for the conversion
to HTML@footnote{The @code{Texinfo::Convert::HTML} module also implements the
HTML converter which go through the tree and call user defined functions.}.
In @code{Texinfo::Convert::HTML} the API may not be followed strictly for
performance reasons, in that case there should always be a @samp{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.

@node Init File Namespace
@section Init File Namespace

@cindex Init file namespace
@cindex Namespace, for init files
@cindex Perl namespaces, for init files

Initialization file are loaded from the main program in the
@code{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:
@example
package Texinfo::Config;
@end example
It is not required, but it may help some debugging tools determine in which
namespace the code is run.

In the @code{Texinfo::Config} namespace, the functions names beginning with
@samp{texinfo_}, @samp{GNUT_} and @samp{_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. @xref{User Defined Functions}.


@node Getting Build Constants
@section Getting Build Constants

@cindex Constants

Some constants are set independently of the output format for a Texinfo build.
They are available through @code{Texinfo::Common::get_build_constant}:

@deftypefun {@var{$value} =} Texinfo::Common::get_build_constant (@var{$name})
Retrieve build constant @var{$name} value.
@end deftypefun

Defined build constants:

@vtable @code
@item PACKAGE
@itemx PACKAGE_CONFIG
@itemx PACKAGE_AND_VERSION
@itemx PACKAGE_AND_VERSION_CONFIG
@itemx PACKAGE_NAME
@itemx PACKAGE_NAME_CONFIG
@itemx PACKAGE_VERSION
@itemx PACKAGE_VERSION_CONFIG
@itemx PACKAGE_URL
@itemx PACKAGE_URL_CONFIG

Texinfo package name and versions.  Values of build constants without
@samp{_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 @samp{_CONFIG} appended are duplicate of
the values of the build constants without @samp{_CONFIG}@footnote{They are
set to correspond to macro set in the C code.  In the C code there are no
macros with the names without @samp{_CONFIG} appended as they would clash with
the names of the customization options.}.
@end vtable


@node Managing Customization Variables
@section Managing Customization Variables

@cindex Customization variables, setting and getting

The basic operations on customization variables are to set and
retrieve their values.

@ignore
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.
@end ignore

This section describes customization variables set in the main program.  These
variables are in general passed to converters.  You can also retrieve the
default converter values for customization variables.  It is also possible to
set customization variables in the converters only, not in the main program.
This is explained later on (@pxref{Conversion Customization Variables}).

@node Setting Main Program String Variables
@subsection Setting Main Program String Variables

To set the value of a string customization variable from an initialization file,
use @code{texinfo_set_from_init_file}:

@defun texinfo_set_from_init_file ($variable_name, $variable_value)
@var{$variable_name} is a string containing the name of the variable
you want to set, and @var{$variable_value} is the value to which you
want to set it.  @var{$variable_value} may be @samp{undef}.
@end defun

For example,

@example
texinfo_set_from_init_file('documentlanguage', 'fr');
@end example

@noindent overrides the @code{@@documentlanguage} from the
document.  It would be overridden by @option{--document-language} on
the command line.
Another example:

@example
texinfo_set_from_init_file('SPLIT', 'chapter');
@end example

@noindent overrides the default splitting of the document.  It would be
overridden by @option{--split} on the command line.

A final example:

@example
texinfo_set_from_init_file('NO_CSS', 1);
@end example

@noindent overrides the default value for @code{NO_CSS}.  It would be
overridden by @code{--set-init-variable NO_CSS=1} on the command line.

Setting the output format cannot be done by setting the customization variable
@code{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
@code{texinfo_set_format_from_init_file} function:

@defun texinfo_set_format_from_init_file ($output_format)
@var{$output_format} is the output format; sets the output format,
without overriding formats set from the command line.
@end defun

Any output format can be set, but since only HTML can be customized,
the main use of @code{texinfo_set_format_from_init_file} is to
set the format to @samp{html}, such that HTML is generated
instead of Info in the default case.

For the customization variables associated with @@-commands, see
@ref{Customization Variables for @@-Commands,,, texinfo, Texinfo}.  For the
customization variables associated with command line options, see
@ref{Customization Variables and Options,,, texinfo, Texinfo}.


@node Modifying Main Program Array Variables
@subsection Modifying Main Program Array Variables

@quotation Warning
The main program customization variables associated with arrays
are not documented.
@end quotation

Customization variables for the main program associated with an array of values
are handled differently. You can use @code{texinfo_add_to_option_list} to
add values to the array and @code{texinfo_remove_from_option_list} to
remove values from the array associated with the customization variable:

@defun texinfo_add_to_option_list ($variable_name, $variable_values_array_reference, $prepend)
@defunx texinfo_remove_from_option_list ($variable_name, $variable_values_array_reference)
@var{$variable_name} is the name of the variable; the values in the
array reference @var{$variable_values_array_reference} are added to the
list associated with the variable with @code{texinfo_add_to_option_list}, and removed with
@code{texinfo_remove_from_option_list}.

If the optional argument of @code{texinfo_add_to_option_list} @var{$prepend}
is set, the values are prepended instead of being appended.
@end defun


@node Setting Converter Variables in Main Program
@subsection 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
@code{texinfo_set_from_init_file}.  For example:

@example
my @@SECTION_BUTTONS =
  (
   \&singular_banner,
   'Back', 'Forward',   'FastBack', 'FastForward',
   'Up', 'Top', 'Contents', 'Index', 'About'
  );

texinfo_set_from_init_file ('SECTION_BUTTONS', \@@SECTION_BUTTONS);
@end example


@node Getting Main Program Variables Values
@subsection Getting Main Program Variables Values

To get the value of a variable, the function is
@code{texinfo_get_conf}:

@deftypefun {@var{$result} =} texinfo_get_conf (@var{$variable_name})
@var{$variable_name} is the name of the variable; its value (possibly
@code{undef}) is returned.
@end deftypefun

For example:

@example
if (texinfo_get_conf('footnotestyle') eq 'separate') @{ ... @}
@end example


@node Getting Converter Default Variables Values
@subsection Getting Converter Default Variables Values

To retrieve output formats specific variable value, you can call
@code{converter_defaults} on the converter class.  For HTML, this would
be:

@deftypefun {@var{\%customization} =} Texinfo::Convert::HTML->converter_defaults (\%conf)
Returns an hash reference (or @code{undef}).  Returned hash reference
keys are the HTML output format specific customization variables names,
associated to the HTML output default values.

The optional @var{\%conf} customization variable hash can be passed
with customization variables that may change the defaults.  For
HTML, this may be used to get texi2html-style defaults, by passing
@code{@{'TEXI2HTML' => 1@}}.
@end deftypefun

Note that you should load the @code{Texinfo::Convert::HTML} module
before calling @code{converter_defaults}.

This can be useful to get the default buttons arrays, for example:

@example
use Texinfo::Convert::HTML;

my $converter_defaults = Texinfo::Convert::HTML->converter_defaults();

my $section_header_buttons_list
   = $converter_defaults->@{'SECTION_BUTTONS'@};
@end example


@node Init File Loading Error Reporting
@section Init File Loading Error Reporting

@cindex Error reporting @subentry loading

If an error or a warning should be emitted when loading an init file, before
the conversion, use @code{texinfo_register_init_loading_error} for an error and
@code{texinfo_register_init_loading_warning} for a warning.

@defun texinfo_register_init_loading_error ($message)
@defunx texinfo_register_init_loading_warning ($message)
Cause an error message or a warning message based on @var{$message}
to be output, taking into account options related to error reporting
such as @option{--force} or @option{--no-warn}.
@end defun

Errors or warning emitted from user defined functions should use the
converter (@pxref{Error Reporting in User Defined Functions}).


@node Simple Formatting Customization
@chapter Simple Formatting Customization

Some change in output formatting can be specified with simple code,
not very different from simple textual configuration information.


@node Init File Expansion Contexts
@section Init File Expansion Contexts: Normal, Preformatted, Code, String, Math

@cindex Init file expansion contexts
@cindex Expansion contexts, for init files
@cindex Contexts for expansion in init files

Output formatting simple customization needs to be specified especially
for different formatting contexts. There are five expansion contexts of
interest:

@table @emph
@item normal context
@cindex Normal expansion context
Paragraphs, index entries, tables, @enddots{}

@item preformatted context
@cindex Preformatted expansion context
When spaces between words are kept.  For example, within the
@code{@@display} (@pxref{@code{@@display},,, texinfo, Texinfo}) and
@code{@@example} environments (@pxref{@code{@@example},,, texinfo, Texinfo}), and
in menu comments.  The preformatted regions
are usually rendered using @code{<pre>} elements in HTML.

@item code context
When quotes and minus are kept.  In particular @code{---}, @code{``}
and other similar constructs are not converted to dash and quote special
characters.  For example, in @code{@@code} or @code{@@option} commands
(@pxref{Useful Highlighting,,, texinfo, Texinfo}).

@item math context
@cindex Math expansion context
Math (@pxref{math,, @code{@@math}, texinfo, 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.

@item string context
@cindex String expansion 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.

@end table

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.


@node Simple Customization for Commands Without Arguments
@section Simple Customization for Commands Without Arguments

@cindex HTML customization for commands without arguments
@cindex Commands without arguments, customizing HTML for
@cindex Insertion commands, customizing HTML for

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

You can set directly the formatting of those commands in different contexts
with @code{texinfo_register_no_arg_command_formatting}:

@defun texinfo_register_no_arg_command_formatting ($command_name, @
        $context, $text, $html_element, $translated_string_converted)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$context} is @samp{normal}, @samp{preformatted} or @samp{string}.
There is no separate math nor code context, @samp{preformatted} should be used
for math and code contexts. @xref{Init File Expansion Contexts}.  If
@var{$context} is @code{undef}, the @samp{normal} context is assumed.

The remaining arguments determine the formatting.  If @var{$text} is set,
the corresponding text is output when the @@-command is formatted.  @var{$text}
can contain HTML elements if needed.  If @var{$html_element} is set, the text
is enclosed between the @var{$html_element} element opening and the element
closing.  If @var{$translated_string_converted} is set, the corresponding
text is translated when the document language changes and used as text.
@var{$translated_string_converted} should already be HTML.
@end defun

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.

You can also specify a Texinfo code string that will be translated
and converted with @code{texinfo_register_no_arg_command_texinfo}:

@defun texinfo_register_no_arg_command_texinfo ($command_name, @
     $translated_string_to_convert)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$translated_string_to_convert} is the Texinfo code used for the
command formatting.  This Texinfo code is translated when the document
language changes and converted from Texinfo to HTML in the diverse
expansion contexts.
@end defun

If both Texinfo code and explicit formatting are specified, the explicit
formatting takes precedence.

For example, if you want @code{&shy;} to be output
for @code{@@-} in normal, preformatted (and math) and string context, call

@example
texinfo_register_no_arg_command_formatting('-', undef, '&shy;');
@end example

If you want ``@code{<small>...</small>}'' to be output for @code{@@enddots}
in normal context and @code{...} to be output in other contexts, call
@example
@group
texinfo_register_no_arg_command_formatting('enddots',
                                           'normal', '...', 'small');
texinfo_register_no_arg_command_formatting('enddots',
                                           'preformatted', '...');
@end group
@end example

If you want ``@code{error--&gt;}'' to be used for @code{@@error} in every context,
with a translation when the document language changes, call

@example
@group
texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
                                           'error--&gt;');
@end group
@end example

If you want ``@code{is the @strong{same} as}'' to be used for @code{@@equiv},
translated when the document language changes, and converted from Texinfo to
HTML in the different expansion contexts, call
@example
@group
texinfo_register_no_arg_command_texinfo('equiv',
                                        'is the @@strong@{same@} as');
@end group
@end example

@xref{Translated Strings Customization} for
customization of translated strings.


@node Simple Customization for Simple Commands with Braces
@section Simple Customization for Simple Commands with Braces

@node Customization of Commands Converting to Uppercase
@subsection Customization of Commands Converting to Uppercase

@cindex HTML determine commands converting to uppercase

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

@defun texinfo_register_upper_case_command ($command_name, $value)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$value} sets or unsets uppercasing of argument.
@end defun

For example, to prevent @code{@@sc} argument from being uppercased and set
@code{@@var} argument to be uppercased:

@example
texinfo_register_upper_case_command('sc', 0);
texinfo_register_upper_case_command('var', 1);
@end example

@node Simple Output Customization for Simple Commands with Braces
@subsection Simple Output Customization for Simple Commands with Braces

@cindex HTML customization for simple commands
@cindex Simple commands, customizing HTML for
@cindex Style commands, customizing HTML for

You can change the formatting of the ``indicator'' and font
commands (e.g., @code{@@code}, @code{@@t}), and other simple commands with
arguments (e.g., @code{@@asis}, @code{@@clicksequence}, @code{@@sup},
@code{@@verb}).

You specify the HTML element associated to a command in a given
expansion context by calling the
@code{texinfo_register_style_command_formatting} function:

@defun texinfo_register_style_command_formatting ($command_name, @
                                                  $html_element, $context)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$context} is @samp{normal} or @samp{preformatted}.  There is no separate
math nor code context, @samp{preformatted} should be used for math and code
context. @xref{Init File Expansion Contexts}.  There is no way to specify
string context, as in string context HTML elements are not output.
If @var{$context} is @code{undef}, the @samp{normal} context is assumed.

If @var{$html_element} is set, the argument is enclosed between the
@var{$html_element} element opening and the element closing.
If @var{$html_element} is undefined, no HTML element is output.
@end defun

To specify the whether quotes should be output for an @@-command
conversion, you should call the @code{texinfo_style_command_set_quoting}
function:

@defun texinfo_style_command_set_quoting ($command_name, @
                                     $html_element, $in_quotes, $context)
@var{$command_name} is the @@-command name, without the leading @@.
@var{$context} is @samp{normal} or @samp{preformatted}.  There is no separate
math nor code context, @samp{preformatted} should be used for math and code
context. @xref{Init File Expansion Contexts}.  There is no string context
as in string context simple formatting without the need for per command
information should be sufficient.  If @var{$context} is @code{undef}, the
@samp{normal} context is assumed.

If @var{$in_quotes} is true, the result is enclosed in quotes associated with
customization variables @code{OPEN_QUOTE_SYMBOL} and @code{CLOSE_QUOTE_SYMBOL}
(@pxref{Customization of HTML Code Inserted,,, texinfo, Texinfo}).  Otherwise,
no quotes are output.
@end defun

For example, to set @code{@@sansserif@{argument@}} to be formatted as
@code{<code>@var{argument}</code>} in normal and preformatted context,
with quotes in preformatted context, use:

@example
texinfo_register_style_command_formatting('sansserif', 'code',
                                          'normal');
texinfo_register_style_command_formatting('sansserif', 'code',
                                          'preformatted');

texinfo_style_command_set_quoting('sansserif', 0, 'normal');
texinfo_style_command_set_quoting('sansserif', 1, 'preformatted');
@end example

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


@node Simple Customization of Accent Commands
@section Simple Customization of Accent Commands

@cindex HTML customization for accent commands
@cindex Accent commands, customizing HTML for
@cindex Accent command named entities

You can modify the formatting of accent commands such as @code{@@'},
@code{@@ringaccent} or @code{@@dotless} by selecting HTML general features,
to output numeric entities or characters (@pxref{HTML Features
Customization,,, texinfo, 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 @samp{e} and a postfix based on the
accent command name, for example @samp{acute} for the acute accent
@code{@@'}.  For example, @samp{@@'e} is converted to the @samp{&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
@code{texinfo_register_accent_command_formatting}:

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

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


@node Simple Customization of Containers
@section 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
(@pxref{Init File Expansion Contexts}).

Call @code{texinfo_register_type_code} to set code context for an element:

@defun texinfo_register_type_code ($type, $code_type)
@var{$type} is the type of the container.  If @var{$code_type} is set, the
container contents are assumed to be in code context. @xref{Init File Expansion
Contexts}.
@end defun

The other piece of information is the type of
preformatted environment they are, analogous with the @@-command names of
@code{@@example} or @code{@@display}@footnote{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.}.

Call @code{texinfo_register_type_pre_class} to set preformatted class:

@defun texinfo_register_type_pre_class ($type, $pre_class_type)
@var{$type} is the type of the container.  If @var{$pre_class_type} is set, the
HTML @code{<pre>} elements class attribute are based on @var{$pre_class_type},
if there are such HTML elements output for preformatted content of @var{$type}
containers.
@end defun

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

@example
texinfo_register_type_code('menu_comment', 1);
texinfo_register_type_pre_class('menu_comment', 'menu-between');
@end example

@xref{Texinfo::Parser Types of container elements,,,texi2any_internals}, for a
description of container types.


@node Simple headers customizations
@chapter 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 (@pxref{Customization of
Navigation and Headers,,, texinfo, 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 direction is the basis for navigation panel customization.


@node Output Units
@section Output Units

@cindex Output elements
@cindex Elements, main unit of output documents
@cindex Document units
@cindex Texinfo tree output units

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

@cindex Output units, defined

The output units are:

@table @emph
@item Normal output units
@cindex 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 @code{USE_NODES}
(@pxref{HTML Output Structure Customization,,, texinfo, Texinfo}).

For example, when generating Info, the nodes are the main elements; when
generating HTML, either case may happen (@pxref{Two Paths,,, texinfo,
Texinfo}).

@item Top output unit
@cindex Top output unit

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

@item Miscellaneous output units
@cindex Table of contents, output unit
@cindex Short table of contents, output unit
@cindex Overview, output unit
@cindex Footnotes, output unit
@cindex About page, output unit
The remaining output units are associated with different files if the document
is split, and also if @code{MONOLITHIC} is not set (@pxref{HTML Output
Structure Customization, texinfo,,, Texinfo}).  There are four such
miscellaneous output units, also called special output units:
@enumerate
@item Table of contents
@item Short table of contents, also called Overview
@item Footnotes page
@item About page
@end enumerate

More details:

@itemize
@item The @emph{Table of contents} should only be formatted if
@code{@@contents} is present in the document.

@item Similarly the @emph{Short table of contents} should only appear if
@code{@@shortcontents} or @code{@@summarycontents} is present.

@item The customization variables @code{contents} and
@code{shortcontents} may be set to trigger the output of the
respective output units.

@vindex CONTENTS_OUTPUT_LOCATION @subentry Output unit
@item If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{separate_element}, the
@emph{Table of contents} and @emph{Short table of contents} output units are
separate (@pxref{Contents and Short Table of Contents Customization}).
Otherwise the @emph{Table of contents} and @emph{Short table of contents}
are directly included within the document, at locations depending on the
specific @code{CONTENTS_OUTPUT_LOCATION} value (@pxref{HTML Output Structure
Customization, texinfo,,, Texinfo}.

@item When generating HTML, the @emph{Footnotes page} should only
be present if the footnotes appear on a separate page (@pxref{Footnote
Styles,,, texinfo, Texinfo}).  However, a footnote output unit is present
if the document is not split.

@vindex DO_ABOUT
@item The @emph{About page} shouldn't be present for documents
consisting of only one sectioning element, or for monolithic documents
without navigation information, or if @code{DO_ABOUT} is not set.

@end itemize
@end table

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 @dfn{external node units}
or @dfn{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 (@pxref{Navigation Panel Button
Formatting}).


@node Directions
@section Directions

@cindex Output unit directions
@cindex Links information
@cindex Directions

A variety of data items, called @dfn{output units directions}, are associated
with output units.  They may be used in the formatting functions, and/or
associated with a button (@pxref{Simple Navigation Panel Customization}).
@dfn{text directions} are used along with output units directions
but are simpler and associated to text only.


@node Default Directions
@subsection Default Directions

In the default case, there is one text direction:
@table @emph
@item Space
An empty button.
@end table

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 (@code{@@chapter},
@code{@@unnumbered}@dots{}) or by the nodes if the node pointers are
specified on @code{@@node} lines or in menus (@pxref{Two Paths,,, texinfo, Texinfo}).

Here is the list of the default global output units directions:

@table @emph
@item Top
Top output unit.

@item First
First output unit in reading order.

@item Last
Last output unit in reading order.

@item About
About (help) page.

@item Contents
Table of contents.

@item Overview
Overview: short table of contents.

@item Footnotes
Corresponds to the @code{Footnotes} output unit (@pxref{Output Units}).

@item Index
Output unit with @code{@@printindex}.

@end table

Here is the list of relative output units directions:

@table @emph
@item This
The current output unit.

@item Forward
Next output unit in reading order.

@item Back
Previous output unit in reading order.

@item FastForward
Next chapter output unit.

@item FastBack
Beginning of this chapter, or previous chapter if the output unit corresponds
to a chapter.

@item Next
Next section output unit at the same level.

@item Prev
Previous section output unit at the same level.

@item Up
Up section.

@item NodeNext
Next node output unit.

@item NodeForward
Next node output unit in node reading order.

@item NodeBack
Previous node output unit in node reading order.

@item NodePrev
Previous node output unit.

@item NodeUp
Up node output unit.

@end table

@cindex @code{FirstInFile} direction variant
@anchor{@code{FirstInFile} direction variant}
Relative direction are each associated with a variant, with
@samp{FirstInFile} prepended, which points to the direction relative
to the first output unit in file.  For example, @code{FirstInFileNodeNext}
is the next node output unit relative to the first output unit in file.
The @samp{FirstInFile} directions are usually used in footers.


@node Changing Global Directions Output Units
@subsection Changing Global Directions Output Units

The global direction associated output unit may be changed by specifying the
Texinfo code name of a @code{@@node}.  The direction should then be linked to
the output unit of that node in headers.  Use
@code{texinfo_register_global_direction} to change a direction link.

@defun texinfo_register_global_direction ($direction, $texinfo_node_name)
@var{$direction} is a global direction (@pxref{Directions}),
@var{$texinfo_node_name} is an optional node name Texinfo code.
The @var{$direction} will point to the output unit associated to the
@var{$texinfo_node_name} node name, if set and the node exists in the
Texinfo document.
@end defun

For example, to have the @emph{Index} direction be associated to the
output unit of the @samp{Main @@emph@{Index@}} node, call
@example
texinfo_register_global_direction ('Index', 'Main @@emph@{Index@}');
@end example


@node Direction Strings
@subsection Direction Strings

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

@cindex Direction strings

@table @code
@item accesskey
Direction @code{accesskey} attribute used in navigation.

@item button
Direction short name typically used for buttons.

@item description
Description of the direction.

@item example
Section number corresponding to the example used in the About special
element text.

@item rel
Direction @code{rel} attribute used in navigation.

@item text
Direction text in a few words.
@end table

@cindex Translated direction strings
@samp{button}, @samp{description} and @samp{text} are translated based
on the document language.

The @code{FirstInFile} direction variants are associated with the same
strings as the direction they are prepended to (@pxref{@code{FirstInFile}
direction variant}).  For example @code{FirstInFileNodeNext} is associated
with the same strings as @code{NodeNext}.


@node Direction Strings Customization
@subsection 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 (@pxref{About Special
Output Unit Customization}).  The direction strings can be customized with
@code{texinfo_register_direction_string_info}:

@defun texinfo_register_direction_string_info ($direction, @
          $type, $converted_string, $string_to_convert, $context)
@var{$direction} is a direction (@pxref{Directions}), @var{$type}
is the type of string (@pxref{Direction Strings}).  The other
arguments are optional.  @var{$context} is @samp{normal} or @samp{string}.
@xref{Init File Expansion Contexts}.  If
$context is @code{undef}, the @samp{normal} context is assumed.

@var{$converted_string} is the string, already converted to HTML
that is used for the specified context.  If the @samp{normal} context
@var{$converted_string} only is specified, the same string will be
used for the @samp{string} context.

Alternatively, @var{$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.

@var{$string_to_convert} is ignored for
special strings that do not need to be translated and cannot contain
Texinfo @@-commands (@samp{accesskey}, @samp{rel} and @samp{example}).
@var{$string_to_convert} is also ignored if @var{$converted_string} is set
for any context.
@end defun

For example, to set the @samp{Up} @samp{button} to be translated
as @samp{Higher}, use:
@example
texinfo_register_direction_string_info('Up', 'button', undef, 'Higher');
@end example


@node Adding Text And Global Output Units Directions
@subsection Adding Text And Global Output Units Directions

Adding new directions is a two step process.  First, you should
register the direction by calling @code{texinfo_register_text_direction}
or @code{texinfo_register_global_direction},
and then you should set the strings associated to the direction with
@code{texinfo_register_direction_string_info}.

@cindex Text direction, adding

You add a new text direction by calling @code{texinfo_register_text_direction}:
@defun texinfo_register_text_direction ($direction)
@var{$direction} is a new direction name.  The function
registers the @var{$direction} as a text direction (@pxref{Directions}).
@end defun

For example to add the @samp{Home} text direction, call:

@example
texinfo_register_text_direction('Home');
@end example

You should then set the strings associated to the text direction
(@pxref{Direction Strings}) with
@code{texinfo_register_direction_string_info}.  For a text direction, you
should at least set the @samp{text} associated string.  For example:

@example
texinfo_register_direction_string_info('Home', 'text',
 '<a href="https://myhomepage.example.com/">Home</a>', undef, 'normal');
texinfo_register_direction_string_info('Home', 'text',
 'Home myhomepage.example.com', undef, 'string');
@end example

@cindex Global direction, adding

You add a global output unit direction by calling
@code{texinfo_register_global_direction}.  You associate the global output
unit direction with a node name Texinfo code by giving the argument.
The new direction will link to the output unit associated with the node
(@pxref{Changing Global Directions Output Units}).  For example, to add a new
global direction @samp{Tutorial} associated to the @samp{My First Program}
@code{@@node}, call:

@example
texinfo_register_global_direction ('Tutorial', 'My First Program');
@end example

You should then set the direction strings associated to the new direction:

@example
texinfo_register_direction_string_info ('Tutorial', 'text', 'Tutorial');
texinfo_register_direction_string_info ('Tutorial', 'button', 'Tuto');
texinfo_register_direction_string_info ('Tutorial', 'accesskey', 't');
@end example

The following call adds a global direction without associating a node name:
@example
texinfo_register_global_direction ('Global link');
@end example

This allows to specify the direction strings associated to the new direction
even if the node name is not yet known.  @xref{Setting Global Directions
From Document Information}, for an example of association to a node name
based on the document structure.


@node Simple Navigation Panel Customization
@section Simple Navigation Panel Customization

@cindex Simple Customization, of navigation panel
@cindex Navigation panel, simple customization of

The @dfn{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 @code{ICONS} customization variable to use icons for the
navigation panel.  Setting @code{ICONS} is necessary but not sufficient to get
icons for direction buttons since no button image is specified in the default
case.  The @code{ACTIVE_ICONS} and @code{PASSIVE_ICONS} customization variables
need to be set in addition:

@vtable @code
@item ACTIVE_ICONS
@itemx PASSIVE_ICONS
Hash references with output unit and text directions as key
(@pxref{Directions}) and button image icons as values.  @code{ACTIVE_ICONS} is
used for directions actually linking to an output unit, and
@code{PASSIVE_ICONS} are used if there is no output unit to link to.  The
button images are interpreted as URLs.
@end vtable

@vindex USE_ACCESSKEY
@anchor{Accesskey and @code{rel} Navigation}
@cindex @code{accesskey} navigation
If the customization variable @code{USE_ACCESSKEY} is set, the
@code{accesskey} attribute is used in navigation.  The @code{accesskey}
direction string is then used for the @code{accesskey} attributes
(@pxref{Direction Strings}).  The @code{rel} direction string is
used for @code{rel} attributes.

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 @code{texinfo_set_from_init_file}. @xref{Setting Main Program String
Variables}.


@node Navigation Panels Buttons Arrays
@subsection Navigation Panels Buttons Arrays

The following customization variables arrays determine the
buttons present in the various navigation panels.  They should
be set or modified to change the panels direction buttons:

@vtable @code
@item 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.

@item SECTION_FOOTER_BUTTONS
@itemx CHAPTER_FOOTER_BUTTONS
@itemx 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.

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

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

@item TOP_BUTTONS
@itemx TOP_FOOTER_BUTTONS
Specifies the buttons used in the top output unit (@pxref{Output Units}).
@code{TOP_BUTTONS} buttons are used for the header and @code{TOP_FOOTER_BUTTONS}
are used for the footer.
@end vtable


@node Setting The Navigation Panel Buttons
@subsection Setting The Navigation Panel Buttons

@cindex Navigation panel button specification
@cindex Button specification, navigation panel

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 simplest way to specify
a button formatting is to use a direction name and let the navigation panel
code formatting format the button based on the direction name.

An output unit direction string is associated to a link to the corresponding
output unit, possibly formatted with an icon.  A direction text string
is associated to the text.  Default (@pxref{Default Directions}) and
added directions (@pxref{Adding Text And Global Output Units Directions}) can
be used in buttons list arrays.

For example, the following sets the section header navigation panel to
show the @code{Home} text button value, followed by a link to the Top node
output unit, a link to the next output unit, a space, and lastly a link
to the table of contents output unit:

@example
texinfo_set_from_init_file('SECTION_BUTTONS',
            ['Home', 'Top', 'Next', 'Space', 'Contents']);
@end example


@node Modifying The Navigation Panel Buttons
@subsection Modifying The Navigation Panel Buttons

If you want to modify the default navigation panel buttons instead of
specifying all the buttons, you can get the converter buttons list
(@pxref{Getting Converter Default Variables Values}), copy them
and insert or remove buttons.  It is important to copy the array
and to never modify the defaults.

A button specified as a string is not the only way to specify
the button direction.  The button direction of default navigation panel button
arrays may also be the first item of an array reference.  To get the button
direction, you can therefore use the following snippet:

@example
my $button_direction;

if (ref($button) eq '') @{
  $button_direction = $button;
@} elsif (ref($button) eq 'ARRAY') @{
  $button_direction = $button->[0];
@}
@end example

Here is an example that removes the @code{Up} direction button and
adds a @code{Tutorial} button after the @code{Next} button:

@example
use Texinfo::Convert::HTML;

my $converter_defaults = Texinfo::Convert::HTML->converter_defaults();

my $section_header_buttons_list
   = $converter_defaults->@{'SECTION_BUTTONS'@};

my @@modified_buttons_list;

foreach my $button (@@@{$section_header_buttons_list@}) @{
  my $button_direction;

  if (ref($button) eq '') @{
    $button_direction = $button;
  @} elsif (ref($button) eq 'ARRAY') @{
    $button_direction = $button->[0];
  @}

  if ($button_direction ne 'Up') @{
    push @@modified_buttons_list, $button;
    if ($button_direction eq 'Next') @{
      push @@modified_buttons_list, 'Tutorial';
    @}
  @}
@}

texinfo_set_from_init_file('SECTION_BUTTONS', \@@modified_buttons_list);

@end example

This concludes the simple navigation headers customization.  More advanced
possibilities for customization are described later on (@pxref{Customizing HTML
Footers@comma{} Headers and Navigation Panels}).


@node User Defined Functions
@chapter 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.


@node User Defined Functions are Registered
@section User Defined Functions are Registered

@cindex User defined functions, registering

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, @code{my_formatting_function} is
passed as a function reference @code{\&my_formatting_function} to the
fictitious registering function @code{texinfo_register_some_formatting}, with
the string specifying the formatting done by the function being
@samp{format_thing}:

@example
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);
@end example

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 @code{\@@array} to indicate a reference to an array
(a.k.a.@: list, in Perl terminology), @code{\%hash} for a reference
to a hash and @code{\&function} for a reference on a function.

To illustrate these conventions, here is the prototype for the
function associated with @samp{format_thing}:

@defblock
@defline {Function Reference} @var{$text} format_thing (@var{$arg1}, @var{\@@arg2})
A function reference associated with @samp{format_thing} has a first argument
@var{$arg1}, a second argument a reference to an array @var{\@@arg2}, and
returns the formatted text @var{$text}.
@end defblock


@node Converter Object and Conversion Functions
@section 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 converter.
The converter can be used for error reporting (@pxref{Error
Reporting in User Defined Functions}).
The converter can also be used for in-document strings translation.
@xref{Translations in Output and Customization} on translated strings in output.


@node User Defined Functions Common Tasks
@chapter 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.


@node Error Reporting in User Defined Functions
@section Error Reporting in User Defined Functions

@cindex Error reporting @subentry conversion
@cindex @code{Texinfo::Convert::Converter} @subentry error reporting

To report a warning or an error not specific of an element conversion,
use @code{converter_document_warn} or @code{converter_document_error}:

@defun @var{$converter}->converter_document_error ($text, $continuation)
@defunx @var{$converter}->converter_document_warn ($text, $continuation)
Register a document-wide error or warning.  @var{$text} is the error
or warning message.

The optional @var{$continuation} argument, if set, conveys that the message
is a continuation of the previous registered message.
@end defun

To report a warning or an error in element conversion, use
@code{converter_line_warn} or @code{converter_line_error}:
@defun @var{$converter}->converter_line_error ($text, \%location_info, $continuation)
@defunx @var{$converter}->converter_line_warn ($text, \%location_info, $continuation)
Register a warning or an error.  @var{$text} is the text of the
error or warning.  The @var{\%location_info} holds the information on the
error or warning location.  The @var{\%location_info} reference on hash may be
obtained from Texinfo elements @code{source_info} keys.

The optional @var{$continuation} argument, if set, conveys that the message
is a continuation of the previous registered message.
@end defun

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


@node Conversion Customization Variables
@section Setting and Getting Conversion Customization Variables

The conversion customization variables are set as follows.
First, variables set in the main program, in particular from init files, are
passed to the converter.  Some variables are especially set in the converter
to default values (@pxref{Getting Converter Default Variables Values}).
Next, variables are set in the converter based on the main
program customization variables values.  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
(@pxref{Customization Variables for @@-Commands,,, texinfo, 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
(@pxref{Managing Customization Variables}).

To get the value of a variable in a converter @code{$converter},
the function is @code{get_conf}:

@deftypefun {@var{$result} =} @var{$converter}->get_conf (@var{$variable_name})
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} (possibly @code{undef}) is returned.
@end deftypefun

For example:

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

To set a variable in a converter @code{$converter},
the function is @code{set_conf}:

@defun @var{$converter}->set_conf ($variable_name, $variable_value)
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} is set to @var{$variable_value}.  The @var{$variable_name}
value will not be overidden if it was set from the command line or from an init
file.
@end defun

For example:

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

Customization variables are
mainly set and accessed during conversion, using the current value obtained
from the command-line, init files or @@-commands in the document.  However,
they may also be accessed before starting the conversion for example for the
conversion of the title obtained from commands such as @code{@@settitle}.  In
that case, the values customization variables had before the conversion, at the
end of the preambule or at the end of the document could be used.

This has consequences on how early you should set the values for customizations
variables in your code, especially for the customization variables associated
with @@-commands.  If a value set by @code{set_conf} is intended to be found
when pre-conversion value is needed, or preambule or end of document value is
needed and there are are no @@-commands at those locations in the Texinfo
manual, @code{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
@samp{setup} stage (@pxref{Init File Calling at Different Stages}).

The values set in converter with @code{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
@code{force_conf} function can be used:

@defun @var{$converter}->force_conf ($variable_name, $variable_value)
@var{$variable_name} is the name of the variable; its value in the converter
@var{$converter} is set to @var{$variable_value}, overriding any previous value.
@end defun


@node Encoding and Decoding File Path Strings
@section Encoding and Decoding File Path Strings


@node Encoding File Path Strings
@subsection Encoding File Path Strings

In general, the strings in the customization functions are character strings.
For most purposes, this is right, and output files content encoding 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 @code{encoded_output_file_name}:

@vindex DOC_ENCODING_FOR_OUTPUT_FILE_NAME
@vindex LOCALE_OUTPUT_FILE_NAME_ENCODING
@deftypefun {(@var{$encoded_name}, @var{$encoding}) =} @var{$converter}->encoded_output_file_name (@var{$character_string_name})
Encode @var{$character_string_name} in the same way as other file name are
encoded in the converter. Use @code{OUTPUT_FILE_NAME_ENCODING} value for the
file name encoding if set.  Otherwise, if
@code{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 (@pxref{Global Customization Variables,,, texinfo, Texinfo}).
Return the encoded name and the encoding used to encode the name.
@end deftypefun

@vindex INPUT_FILE_NAME_ENCODING
@vindex DOC_ENCODING_FOR_INPUT_FILE_NAME
There is also a similar function for the input file names encoding,
@code{encoded_input_file_name}, which uses @code{INPUT_FILE_NAME_ENCODING}
and @code{DOC_ENCODING_FOR_INPUT_FILE_NAME} and is less likely to be useful.

@vindex COMMAND_LINE_ENCODING
When calling external commands, the command line arguments should also
be encoded.  To do similarly with other codes, the customization variable
@code{COMMAND_LINE_ENCODING} should be used.  Already encoded file
names may be used.  For example

@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('COMMAND_LINE_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));
@}
@end example


@node Decoding File Path Strings
@subsection Decoding File Path Strings

@vindex COMMAND_LINE_ENCODING
The following customization variables strings or arrays are binary strings:
@code{INCLUDE_DIRECTORIES}, @code{CSS_FILES}, @code{MACRO_EXPAND} and
@code{INTERNAL_LINKS}.  If they need to be decoded into character strings, for
example to appear in error messages, it is possible to use the
@code{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.  @xref{Global Customization Variables,,,
texinfo, Texinfo}.

For example:
@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);
@}
@end example

More information on Perl and encodings in
@uref{https://perldoc.perl.org/perlunifaq, perlunifaq}.


@node Protection of URLs
@section Protection of URLs

@cindex Percent encoding
@cindex URL protection
@cindex Protecting, URL

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, @samp{?} 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 @code{url_protect_url_text}.  To protect file path in URL,
including characters with a special role in URLs,
use @code{url_protect_file_text}.

@deftypefun {@var{$protected_url} =} @var{$converter}->url_protect_url_text(@var{$input_string})
Percent-encode @var{$input_string}, leaving as is all the characters with a
special role in URLs, such as @samp{:}, @samp{/}, @samp{?}, @samp{&}, @samp{#}
or @samp{%} (and a few other).  HTML reserved characters and form feeds
protected are also protected as entities (@pxref{Basic Formatting
Customization,,@code{format_protect_text}}).  This is typically used on
complete URLs pointing to diverse internet resources, such as the @code{@@url}
URL argument.

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

@deftypefun {@var{$protected_path} =} @var{$converter}->url_protect_file_text(@var{$input_string})
Percent-encode @var{$input_string} leaving as is character appearing in file
paths only, such as @samp{/}, @samp{.}, @samp{-} or @samp{_}.  All the other
characters that can be percent-protected are protected, including characters
with a special role in URLs.  For example, @samp{?}, @samp{&} and @samp{%} are
percent-protected.  HTML reserved characters and form feeds protected are also
protected as entities (@pxref{Basic Formatting Customization,,
@code{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 @code{@@image}.

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


@node Customizing Output-Related Names
@chapter 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
@code{texinfo_register_file_id_setting_function}:

@defun texinfo_register_file_id_setting_function ($customized, \@ampchar{}handler)
@var{$customized} is a string describing what the function
should set.  @var{\&handler} should be a reference on the user
defined function.  The different functions that can be registered
have different arguments and return values.
@end defun

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

For example:
@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);
@end example

@menu
* File: Customizing Output File Names.
* Target: Customizing Output Target Names.
* External Node: Customizing External Node Output Names.
* Special Elements: Customizing Special Elements Output Names.
* Redirection: Customizing Node Redirection Files.
@end menu


@node Customizing Output File Names
@section Customizing Output File Names

@cindex Customizing output file names
@cindex Output file names, customizing

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

Two function references registered with
@code{texinfo_register_file_id_setting_function} enable further customization.
The first, @code{node_file_name} is used to customize the nodes files names.

@deftypefn {Function Reference} @var{$node_file} node_file_name (@var{$converter}, @
                                      @var{\%node_element}, @var{$file_name})
@var{$converter} is a converter object.  @var{\%node_element} is the Texinfo tree
element corresponding to the @code{@@node}.  @var{$file_name} is the node file
name that has been already set.  The function should return the node file name
(@var{$node_file}).
@end deftypefn

The other function reference, @code{unit_file_name}, is used to
customize the file names associated with each normal output unit
(@pxref{Output Units}).

@deftypefn {Function Reference} {(@var{$file}, @var{$path})} unit_file_name (@var{$converter}, @
                  @var{\%output_unit}, @var{$file_name}, @var{$file_path})
@var{$converter} is a converter object.  @var{\%output_unit} is the output unit.
@var{$file_name} is the file name that has been already set.  @var{$file_path}
is the file path that has been already set.  @var{$file_path} is @samp{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,
@var{$file}, and the file path for the output unit, @var{$path}, which should
be @samp{undef} if the file path is to be constructed by putting @var{$file}
in the destination directory.
@end deftypefn

In the user defined functions, the information that an output unit
is associated with @code{@@top} or @code{@@node Top} may be determined with:
@example
$converter->unit_is_top_output_unit(\%output_unit);
@end example
The information on tree elements may be interesting for those functions
(@pxref{Texinfo Tree Elements in User Defined Functions}).

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

@node Customizing Output Target Names
@section Customizing Output Target Names

@cindex Customizing output target names
@cindex Target names, customizing
@cindex Id names, customizing

Similar to file names, so-called target and id names may be set.  The
@dfn{id} is placed where the item is located, while the @dfn{target}
is used to construct references to that item.  An item id and target
have the same value, therefore they tend to be used interchangeably in
the following.  A function used to set both target and file name is also
described here.

@c xx, but not always, for example in the default case, the
@c xx target for a section is the node id.

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

@deftypefn {Function Reference} @var{$target} label_target_name @
           (@var{$converter}, @var{$normalized}, @var{\%element}, @var{$default_target})
@var{$converter} is a converter object.  @var{$normalized} is the
normalized node name, @var{\%element} is a reference on a
Texinfo tree command label element whose contents correspond
to the node name.
@var{$default_target} is the target that has been already set.  The function
should return the target (@var{$target}).
@end deftypefn

The element corresponding to the label can be found with
@code{converter_find_identifier_target} if the label corresponds to
an internal reference (@pxref{Target Tree Element Link}):
@example
my $element;
$element = $converter->converter_find_identifier_target($normalized)
  if (defined($normalized));
@end example

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:

@deftypefn {Function Reference} {(@var{$target}, @var{$target_contents}, @var{$target_shortcontents}, @var{$file})} @
 sectioning_command_target_name (@var{$converter}, @var{\%section_element}, @var{$default_target}, @
    @var{$default_target_contents}, @var{$default_target_shortcontents}, @var{$file_name})
@var{$converter} is a converter object. @var{\%section_element} is the Texinfo
element corresponding to the sectioning command.

@var{$default_target}, @var{$default_target_contents} and
@var{$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.  @var{$file_name} is the file name that has been already set.

The function should return the @var{$target}, @var{$target_contents} and
@var{$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 (@var{$file}).
@end deftypefn


@node Customizing External Node Output Names
@section Customizing External Node Output Names

In the default case references to external nodes are set as described in the
Texinfo manual (@pxref{HTML Xref,,, texinfo, Texinfo}).  You can specify
external node manuals URLs in cross-references customization files (@pxref{HTML
Xref Configuration,,, texinfo, 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 (@pxref{File Names and
Links Customization for HTML,,, texinfo, Texinfo}).

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

@deftypefn {Function Reference} {(@var{$target}, @var{$host_directory}, @var{$file_name})} @
  external_target_split_name(@var{$converter}, @var{$normalized}, @var{\%element}, @var{$default_target}, @
    @var{$default_host_directory}, @var{$default_file_name})
@var{$converter} is a converter object. @var{$normalized} is the
normalized node name, @var{\%element} is a reference
on an element containing information on the external node.

@var{$default_target}, @var{$default_host_directory} and
@var{$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 @var{$target}, @var{$host_directory} and
@var{$file_name} URL parts.
@end deftypefn

@deftypefn {Function Reference} {(@var{$target}, @var{$host_directory_file})} @
  external_target_non_split_name(@var{$converter}, @var{$normalized}, @var{\%element}, @var{$default_target}, @
    @var{$default_host_directory_file})
@var{$converter} is a converter object. @var{$normalized} is the
normalized node name, @var{\%element} is a reference
on an element containing information on the external node.

@var{$default_target} is the target and @var{$default_host_directory_file}
is the host and file name part of the URL that have been already
set.

The function should return the @var{$target} and @var{$host_directory_file}
URL parts.
@end deftypefn


@node Customizing Special Elements Output Names
@section Customizing Special Elements Output Names

@cindex Special Elements target names, customizing
@cindex Special Elements id names, customizing
@cindex Special Elements file names, customizing

For special output units file and target (@pxref{Output Units}), the
function reference is:

@deftypefn {Function Reference} {(@var{$target}, @var{$file})} special_unit_target_file_name @
           (@var{$converter}, @var{\%output_unit}, @var{$default_target}, @var{$file_name})
@var{$converter} is a converter object. @var{\%output_unit} is the special
output unit hash. @var{$default_target} is the
target that has been already set, and @var{$file_name} is the
file name that has been already set. The function should return the @var{$target}
and @var{$file}.
@end deftypefn

To determine the variety of the special output unit processed, the
output unit @code{special_unit_variety} hash key can be used.
@xref{Special Units Varieties}.


@node Customizing Node Redirection Files
@section Customizing Node Redirection Files

In the default case, node redirection files are done for label commands (node,
anchor and floats) if they are not output in a file that corresponds to the
HTML Xref specification (@pxref{HTML Splitting,,, texinfo, Texinfo}).

You can customize the list of redirection files output by registering the
function reference:

@deftypefn {Function Reference} {@@redirection_files} redirection_file_names @
           (@var{$converter}, @var{\%element}, @var{$element_filename}, @
            @var{$node_filename}, @var{\@@default_redirection_files})
@var{$converter} is a converter object. @var{\%element} is the node tree
element. @var{$element_filename} is the filename the element is output in.
@var{$node_filename} is the file name following the HTML Xref specification
for the element. @var{\@@default_redirection_files} is the list of
redirection files generated in the default case.

The function should return the list of the redirection files.  It can be
empty, in which case there will not be any redirection file generated for
this element.
@end deftypefn


@node Init File Calling at Different Stages
@chapter Init File Calling at Different Stages

@cindex Init file calling functions at different stages
@cindex Calling functions at different stages
@cindex Functions, 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:
@table @code
@item 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.
@c the information on input file names directories is probably available
@c somewhere, but we do not want those to be used, in general, rather
@c we mostly want document_name to be used
@c  The input file names'directories are available.

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

@item 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
(@pxref{Converter General Information}).

@item finish
Called after output generation is finished.
@end table

The function used to register a user defined functions is
@code{texinfo_register_handler}:

@defun texinfo_register_handler ($stage, \@ampchar{}handler, $priority)
@var{$stage} is one of the stages described just above. @var{\&handler}
is a reference on the user defined function. @var{$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
@code{texinfo_register_handler}.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$status} stage_handler @
           (@var{$converter}, @var{$document}, @var{$stage})
@var{$converter} is a converter object. @var{$document} is the Texinfo
parsed @code{Texinfo::Document} document. @var{$stage} is the current stage.

@vindex HANDLER_FATAL_ERROR_LEVEL
If @var{$status} is not 0 it means that an error occured.
If @var{$status} is positive, the user defined functions should
have registered an error or warning message, for example with
@code{document_error} (@pxref{Error Reporting in User Defined Functions}).
If @var{$status} is negative, the converter will emit a non specific
error message.  If the @var{$status} is lower than
-@code{HANDLER_FATAL_ERROR_LEVEL} or
higher than @code{HANDLER_FATAL_ERROR_LEVEL}, the processing stops
immediately.  Default value for @code{HANDLER_FATAL_ERROR_LEVEL}
is 100.
@end deftypefn


@node Formatting HTML Output
@chapter 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 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
(@pxref{Customization and Use of Formatting Functions}), tree elements
conversion functions (@pxref{Tree Element Conversion Customization}) and output
units conversion functions (@pxref{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.


@node Specific HTML Constructs Formatting Functions
@section 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.


@node Formatting HTML Element with Classes
@subsection Formatting HTML Element with Classes

Opening an HTML element with one or more classes should always be done through
@code{html_attribute_class}:

@deftypefun {@var{$element_open} =} @var{$converter}->html_attribute_class @
                              (@var{$html_element}, @var{\@@classes})
Formats the beginning of an HTML element @var{$html_element}.  @var{\@@classes}
is the list of classes for this element.  The element opening returned does not
include the end of element symbol @samp{>} such that it is possible to add
more attributes.

If the HTML element is @code{span}, an empty string is returned if there
is also no attribute.

@vindex NO_CSS
@vindex INLINE_CSS_STYLE
If @code{NO_CSS} is set, no attribute is set for the element.  Otherwise
a @code{class} attribute is set based on @var{\@@classes }. If
@code{INLINE_CSS_STYLE} is set, a CSS style attribute based on
CSS element class rules is also added (@pxref{HTML CSS,,, texinfo, Texinfo}).
Otherwise the information that the element class was seen is registered by
the converter.
@end deftypefun

Examples of use:
@example
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>';
@end example


@node Closing Lone HTML Element
@subsection Closing Lone HTML Element

HTML elements with an opening element, but no closing element,
such as @code{<img>} or @code{<link>}, also called @dfn{void elements} should
be closed by calling @code{close_html_lone_element}:

@deftypefun {@var{$html_element} =} @var{$converter}->close_html_lone_element @
                                                     (@var{$unclosed_element})
Close the @var{$unclosed_element}, which can contain attributes, by prepending
@samp{>} or @samp{/>} depending on the @code{USE_XML_SYNTAX} customization
variable value (@pxref{HTML Features Customization,,, texinfo, Texinfo}).
@end deftypefun

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


@node Substituting Non Breaking Space
@subsection Substituting Non Breaking Space

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

If a @code{&nbsp;} can directly appear in formatted code, however,
the corresponding text should be in a call to @code{substitute_html_non_breaking_space},
to take into account @code{OUTPUT_CHARACTERS} and @code{USE_NUMERIC_ENTITY}
customization variables:

@deftypefun {@var{$substituted_text} =} @var{$converter}->substitute_html_non_breaking_space @
                                                    (@var{$formatted_text})
Substitute @code{&nbsp;} according to customization variables values.
@end deftypefun

@xref{HTML Features Customization,,, texinfo, Texinfo} for
@code{OUTPUT_CHARACTERS} and @code{USE_NUMERIC_ENTITY} description.


@node Converter General Information
@section 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 @samp{html} or @samp{tex}
is expanded (@pxref{Conditional Commands,,, texinfo, Texinfo}), use
@code{is_format_expanded}:

@anchor{@code{is_format_expanded}}
@deftypefun {@var{$is_format_expanded} =} @var{$converter}->is_format_expanded (@var{$format})
Return true if format @var{$format} is expanded, according to
command-line and init file information.
@end deftypefun

The main method to get information from the converter is @code{get_info}:

@deftypefun {@var{$info} =} @var{$converter}->get_info (@var{$item})
Return information on @var{$item}.
@end deftypefun

The available information is about:
@table @code
@item copying_comment
Text appearing in @code{@@copying} with all the Texinfo commands
put into comments (@pxref{@code{@@copying},,, texinfo, Texinfo}).

@item date_in_header
Date formatted as metadata for HTML @code{<head>}.

@item 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.  @xref{Encoding File Path Strings}.

@item document
The @code{Texinfo::Document} parsed Texinfo document being converted.
Some information relevant for conversion is available from the document
using function accessors:

@table @code
@item floats_information
@anchor{@code{floats_information}}
Information on floats.  Hash reference whose keys are normalized float types
(the first float argument).  The value is a list of array references, one per
float of that type.  The first item of the float array reference is the float
tree element.  The second item of the float array reference is the section
relations information of the section containing the float.

@item global_commands_information
Global commands information hash reference.  The keys are @@-command names.  For
@@-commands that may appear multiple time in the Texinfo document, the
associated values are array references containing all the corresponding
tree elements.  For @@-commands that should appear only once, the associated
value is the tree element.

The @code{dircategory_direntry} key is also available, containing the
array of successive @code{@@dircategory} and @code{@@direntry}, if these
commands are present in the document.

The @code{language_commands} key is also available, containing the
the array of successive @code{@@documentlanguage}, @code{@@documentscript}
and @code{@@documentlanguagevariant}, if these commands are present in the
document and not overriden by command-line or initialization files
values, for @code{@@documentlanguage} and @code{@@documentscript}.

@c not directly used in default formatting text, probably not interesting
@c @item global_information
@c Diverse information.
@c @xref{Texinfo@asis{::}Document $info = global_information($document),,
@c Texinfo@asis{::}Document@asis{::}global_information,texi2any_internals}.

@item indices_information
@anchor{@code{indices_information}}
Information about defined indices, merged indices and index entries.
Returns a hash reference with index names as keys and hash reference with
index information as values.  For each index name, the following relevant
values are available:

@table @code
@item in_code
1 if the index entries should be formatted as code, 0 in the opposite case.

@item merged_in
In case the index is merged to another index, this key holds the name of
the index the index is merged into.  It takes into account indirectly
merged indexes.

@item index_entries
An array reference containing index entry hash references for index entries
associated with the index.  @xref{Specific Formatting for Indices}.
@end table

@item sections_list
@anchor{@code{sections_list}}
List of the sectioning commands relations associated to each of the
document sectioning commands in document order.
@xref{Sectioning Commands Elements and Document Structure}.

@item nodes_list
@anchor{@code{nodes_list}}
List of the node relations in the document associated to each of the
@code{@@node} in document order.
@xref{Node Elements and Document Structure}.
@end table

@item 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.  @xref{Encoding File Path Strings}.

@item documentdescription_string
@code{@@documentdescription} argument converted in a string context
(@pxref{@code{@@documentdescription},,, texinfo, Texinfo}).  @xref{Init File
Expansion Contexts}.

@item documentinfo_metadata
@code{@@documentinfo} content converted to HTML.  @@-commands
already registering document information such as @code{@@title},
@code{@@author} and other similar commands should already be handled
specifically, they are ignored here.

@item expanded_formats
Information on output formats such as @samp{html} or @samp{tex}
expansion (@pxref{Conditional Commands,,, texinfo, 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.

@code{expanded_formats} information should be consistent with
@code{is_format_expanded} call result (@pxref{@code{is_format_expanded}}).

@item 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
@enumerate
@item licence name
@item license URL
@item file name or source of file
@end enumerate

@item line_break_element
HTML line break element, based on @samp{<br>}, also taking into account
@code{USE_XML_SYNTAX} customization variable value.

@item non_breaking_space
Non breaking space, can be @samp{&nbsp;}, but also a non breaking
space character or the corresponding numeric entity based on
@code{OUTPUT_CHARACTERS} and @code{USE_NUMERIC_ENTITY} customization variables
values.  @xref{Substituting Non Breaking Space}.

@item paragraph_symbol
Paragraph symbol, can be @samp{&para;}, but also the corresponding numeric entity
or encoded character based on @code{OUTPUT_CHARACTERS} and
@code{USE_NUMERIC_ENTITY} customization variables values.
@xref{HTML Features Customization,,, texinfo, Texinfo}.

@item title_string
@item title_tree
@item simpletitle_tree
@item simpletitle_command_name
Some information is deduced from the title commands:
@dfn{simpletitle} reflects @code{@@settitle} vs.@:
@code{@@shorttitlepage}, and @dfn{title} is constructed by trying
all the title-related commands, including @code{@@top} and
@code{@@titlefont}, in the top element.

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

@item title_titlepage
The formatted title, possibly based on @code{@@titlepage}, or on
@code{simpletitle_tree} and similar information, depending on @code{SHOW_TITLE}
and @code{USE_TITLEPAGE_FOR_TITLE} customization variables in the default case
(@pxref{HTML Output Structure Customization,,, texinfo, Texinfo}).

@end table

@xref{Customization of CSS Rules Imports and Selectors} for an explanation on
getting information on CSS.


@node Getting Conversion Context
@section Getting Conversion Context

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


@node Conversion in String Context
@subsection 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.
@xref{Init File Expansion Contexts}.

To determine if in string context, the functions is @code{in_string}:

@deftypefun {@var{$in_string} =} @var{$converter}->in_string ()
Return true if in string context.
@end deftypefun

Example of use:

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


@node Conversion in Preformatted Context
@subsection Conversion in Preformatted Context

Conversion and formatting functions should test if in preformatted
context to convert accordingly. @xref{Init File Expansion Contexts}.

To determine if in preformatted context, the functions is
@code{in_preformatted_context}:

@deftypefun {@var{$in_preformatted} =} @var{$converter}->in_preformatted_context ()
Return true if in preformatted context.
@end deftypefun

Another function tells if within a preformatted command:
@deftypefun {@var{$inside_preformatted} =} @var{$converter}->inside_preformatted ()
Return true if within a preformatted block command such as
@code{@@preformatted}, @code{@@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.
@end deftypefun

If in preformatted context, it is possible to get preformatted @@-commands and
preformatted types nesting with @code{preformatted_classes_stack}:

@deftypefun {@var{\@@preformatted_nesting} =} @var{$converter}->preformatted_classes_stack ()
Returns an reference on an array containing the block preformatted @@-commands
such as @code{@@example}, @code{@@display} or @code{@@menu} names without
the leading @@ and the HTML attribute class preformatted container names,
in order of appearance.
@end deftypefun

The @code{%Texinfo::Commands::preformatted_code_commands}
hash can be used to determine if a preformatted command is to be formatted
as code, as is the case for @code{@@example} but not for @code{@@display}.

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

@xref{Simple Customization of Containers} on customizing containers
preformatted class.


@node Other Dynamic Information
@subsection Other Dynamic Information

To get the current output unit being converted, use @code{current_output_unit}:
@deftypefun {@var{$output_unit} =} @var{$converter}->current_output_unit ()
Return the output unit being converted, or @code{undef} if there is no
output unit.
@end deftypefun

To get the file name of the current output unit being converted,
use @code{current_filename}:
@deftypefun {@var{$filename} =} @var{$converter}->current_filename ()
Return the file name of the current output unit being converted.
@end deftypefun

To get the text filling and alignement context, determined by @code{@@flushleft}
or @code{@@center}, use @code{in_align}:

@deftypefun {@var{$align_context} =} @var{$converter}->in_align ()
If the alignment context is the default alignement context, return @code{undef}.
Otherwise, returns the command name of the alignment context.
@end deftypefun

To determine if a tree element that can be the target of cross-references
is already being converted you can call @code{is_in_referred_command_stack}.
It is used in the default case for @code{@@ref} and similar @@-command
tree element conversion to avoid infinite recursion.  Indeed, if @code{@@ref}
is inside of an @@-command and refers to that @@-command, directly or
indirectly, an infinite recursion could happen.

@deftypefun {@var{$is_being_converted} =} @var{$converter}->is_in_referred_command_stack (@var{\%element})
Return true if the @var{\%element} is being converted.  Only for @@-commands
that can be the target of links (@pxref{Target Tree Element Link}).
@end deftypefun

To determine if in a context of multiple conversions,
use @code{in_multiple_conversions}:
@deftypefun {@var{$multiple_conversion} =} @var{$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 @code{@@node}.  The main @code{@@node} element
expansion occurs where the @@-command is located.

For another example, multiple conversion for index entries could happen
if there are more than one @code{@@printindex} for an index in the converted
manual.
@end deftypefun

To determine if in a specific multiple expanded context, use
@code{multi_expanded_region}:
@deftypefun {@var{$multi_expanded_context_information} =} @var{$converter}->multi_expanded_region ()
Return a string representing the multiple expanded context, or @code{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.

Multiple expanded context happens for example in automatically-generated menu
description, captions in list of floats or printindex converted more than once.
@end deftypefun

To get the current paragraph and preformatted number, use @code{paragraph_number}
or @code{preformatted_number}:

@deftypefun {@var{$number} =} @var{$converter}->paragraph_number ()
@deftypefunx {@var{$number} =} @var{$converter}->preformatted_number ()
Return the current paragraph or preformatted container number in the
current formatting context.
@end deftypefun

To get the topmost block @@-command being converted, use @code{top_block_command}:
@deftypefun {@var{$command_name} =} @var{$converter}->top_block_command ()
Return the most recent block @@-command seen in the current formatting
context.
@end deftypefun


@node Document Structure
@section Document Structure

@cindex Document structure

The document structure information is mainly obtained from section
relations, nodes relations and headings relations information
associated to sectioning, nodes and heading elements.  Output units
also provide information on the document structure.

Sections relations can also be retrieved by calling
@code{$document->sections_list()} on the @code{$document} obtained
through @code{get_info} (@pxref{@code{sections_list}}).  Similarly,
nodes relations can also be retrieved by calling
@code{$document->nodes_list()} on the @code{$document} obtained
through @code{get_info} (@pxref{@code{nodes_list}}).

You can also find additional information on document structure associated to
node, sectioning and heading elements by looking at the tree element
@code{extra} information.


@node Sectioning Commands Elements and Document Structure
@subsection Sectioning Commands Elements and Document Structure

Sectioning commands tree elements section level, taking into account
@code{@@raisesections} and @code{@@lowersections} is available in @code{extra}
@code{section_level}.  Level 0 corresponds to @code{@@top} or @code{@@part} and
level 1 to @code{@@chapter} level sectioning commands.
@xref{Raise/lower sections,,, texinfo, Texinfo}.

Level of heading commands, such as @code{subheading} is returned by the
@code{Texinfo::Common::section_level} function:

@deftypefun {@var{$level} =} Texinfo::Common::section_level (@var{\%element})
Return the numbered level of the heading or sectioning command tree element
@var{\%element}, as modified by raise/lowersections for sections.
@end deftypefun

Call @code{Texinfo::Structuring::section_level_adjusted_command_name} for the command
name adjusted for @code{@@raisesections} and @code{@@lowersections}:

@deftypefun {@var{$command_name}} = @
  Texinfo::Structuring::section_level_adjusted_command_name (@var{\%element})
Return the sectioning command name corresponding to the sectioning
element @var{\%element}, adjusted in order to take into account raised
and lowered sections, when needed.
@end deftypefun

@cindex Sectioning command relations

Most of the information on document structure associated to a sectioning
command tree element is available in the sectioning command relations
information associated to the sectioning command tree element.  This is an hash
reference obtained by calling @code{converter_section_relations_of_section}:

@deftypefun {@var{\%section_relations} =} @var{$converter}->converter_section_relations_of_section (@var{\%element})
Return the sectioning command relations information associated to the
sectioning command tree element @var{\%element}, or @samp{undef} if it
cannot be found@footnote{If there is a document associated to the
converter and the tree element is actually a sectioning command tree
element, the relations information should always be found.}.
@end deftypefun

The following keys are in section relations hash references:

@table @code
@item element
The sectioning command Texinfo tree element associated to the section
relations.

@item associated_node
Node relations information corresponding to the node associated
to the sectioning command.

@item associated_part
Part @@-command relations information of the @code{@@part} preceding
the sectioning command.

@item section_children
The children of the section relations element in the sectioning tree.  These
children are also section relations.

@c not clearly useful in user-defined code
@c @item associated_anchor_command

@item section_directions
Hash reference with @code{up}, @code{next} and @code{prev} keys associated
to the corresponding section relations directions.

@item toplevel_directions
Hash reference with @code{up}, @code{next} and @code{prev} keys associated
to toplevel sectioning relations directions, for elements like @code{@@top},
@code{@@chapter}, @code{@@appendix}, not taking into account @code{@@part}
elements.

@item part_associated_section
For @code{@@part} tree elements only.  Sectioning command relations
following the @code{@@part}.

@item part_following_node
For @code{@@part} tree elements only.  Node relations of the node associated
to the @code{@@part}.

@end table



@node Node Elements and Document Structure
@subsection Node Elements and Document Structure

The following keys of the @code{extra} node elements hash
can be interesting in user-defined formatting and conversion functions:

@table @code
@item normalized
Normalized node name. @xref{HTML Xref,,, texinfo, Texinfo}.
@end table

@cindex Node relations

Most of the information on document structure associated to a @code{@@node}
tree element is available in the node relations
information associated to the node tree element.  This is an hash
reference obtained by calling @code{converter_node_relations_of_node}:

@deftypefun {@var{\%node_relations} =} @var{$converter}->converter_node_relations_of_node (@var{\%element})
Return the node relations information associated to the
node tree element @var{\%element}, or @samp{undef} if it
cannot be found@footnote{If there is a document associated to the
converter, the tree element is actually a @code{@@node} tree
element and is not empty, the relations information should always be found.}.
@end deftypefun

The following keys are in node relations hash references:

@table @code
@item element
The @code{@@node} Texinfo tree element associated to the node
relations.

@item associated_section
Sectioning command relations information corresponding to the sectioning
command associated to the node.

@item associated_title_command
Sectioning command, heading command or @code{@@xrefname} tree element following
the node.

@item node_preceding_part
Part @@-command relations information of the @code{@@part} associated
to the node.

@item menus
A list of menu tree elements found in the node.

@item node_directions
Hash reference with @code{up}, @code{next} and @code{prev} keys associated
to the corresponding node relations directions.

@item node_description
Tree element holding a description of the node, either a
@code{@@nodedescription} or a @code{@@nodedescriptionblock}.

@item node_long_description
Tree element holding a long description of the node,
corresponding to a @code{@@nodedescriptionblock} tree element.

@end table


@node Heading Elements and Document Structure
@subsection Heading Elements and Document Structure

@cindex Heading relations

Information on document structure associated to an heading
command or to an @code{@@xrefname} command
tree element is available in the heading relations
information associated to the tree element.  This is an hash
reference obtained by calling @code{converter_heading_relations_of_heading}:

@deftypefun {@var{\%heading_relations} =} @var{$converter}->converter_heading_relations_of_heading (@var{\%element})
Return the heading relations information associated to the
heading tree element @var{\%element}, or @samp{undef} if it
cannot be found@footnote{If there is a document associated to the
converter, the tree element is actually a heading tree element,
the relations information should always be found.}.
@end deftypefun

The following keys are in heading relations hash references:

@table @code
@item element
The Texinfo tree element associated to the heading relations.

@item associated_anchor_command
Node relations associated to the heading or @code{@@xrefname} command.
@end table


@node Output Units Information
@subsection Output Units Information

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 (@pxref{Output Units}) can be obtained as
output units conversion function arguments (@pxref{Output Units Conversion
Functions}).  The current output unit being processed is also available as
@code{$converter->current_output_unit()} (@pxref{Other Dynamic Information}).
Root command (@code{@@node} or sectioning command) @code{associated_unit} key
value points to the associated output unit.  Lastly
@code{get_element_root_command_element} may be used to get the the output
unit associated with an element
(@pxref{@code{get_element_root_command_element}}).

The following keys of output unit hashes can be interesting:

@table @code
@item unit_type
@anchor{Unit Type}
@cindex Unit type
@code{unit} for normal output units, @code{special_unit} for
special units and @code{external_node_unit} for external nodes virtual units
corresponding to references to external manuals.

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

For special units, points to a ``virtual'' tree element with type
@code{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 @code{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.

@item unit_contents
Array reference on tree elements associated with the output unit.

@item unit_filename
The associated file name.

@item tree_unit_directions
Hash with @code{next} and @code{prev} for the
next and previous output units in document order.

@item special_unit_variety
The variety of the special output unit.
For special units only. @xref{Special Units Varieties}.
@end table


@node Converting Texinfo Trees
@section 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
(@pxref{Internationalization of Output Strings}).
For example, here a Texinfo tree is returned by the @code{cdt} call,
based on the translation of the @samp{No value for @@strong@{@{item@}@}}
string, and converted to HTML with @code{convert_tree}:
@example
my $tree = $converter->cdt('No value for @@strong@{@{item@}@}',
                           @{'item' => $text_element@});
my $no_value_converted_output = $converter->convert_tree($tree);
@end example


@node Texinfo Tree Conversion Functions
@subsection Texinfo Tree Conversion Functions

The @code{convert_tree} function converts a Texinfo tree rooted at any element:

@deftypefun {@var{$converted_text} =} @var{$converter}->convert_tree (@var{\%element}, @var{$explanation})
@var{\%element} is a Texinfo tree element. @var{$explanation} is
optional, it is a string explaining why the function was called, to help
in case of debugging.  The function returns @var{\%element} converted.
@end deftypefun

@code{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 @code{@@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
@code{convert_tree_new_formatting_context} which creates a new document
formatting context appropriately.
@code{convert_tree_new_formatting_context} ultimately calls @code{convert_tree}.

@anchor{@code{convert_tree_new_formatting_context}}
@deftypefun {@var{$converted_text} =} @var{$converter}->convert_tree_new_formatting_context @
      (@var{\%element}, @var{$context}, @var{$expansion_context_flags}, @var{$multiple_pass}, @var{$global_context}, @
       @var{$block_command_name})
@var{\%element} is a Texinfo tree element.  @var{$context} is a string that
describes the new context setup to format out of the main conversion flow.
The value is used for debugging output only.  @var{$expansion_context_flags}
is an optional integer specifying the expansion context that is wanted for
the new document context, and is described next
(@pxref{Setting the Expansion Context for Conversion}).
@var{$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.
@var{$global_context} is an optional string that marks that the formatting may
be done in advance, and can be redone.  @var{$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 @var{\%element} converted, setting the conversion context
according to the arguments.
@end deftypefun


@node Setting the Expansion Context for Conversion
@subsection Setting the Expansion Context for Conversion

The expansion context is not generally customizable, as it is
implied by the Texinfo command being converted
(@pxref{Init File Expansion Contexts}).  However, it
is possible to set the code or the string expansion context
explicitly if needed.  You often need expansion in string context
for HTML elements attributes.  The
code expansion context is already set for @@-commands such as @code{@@code} or
@code{@@example}.  However, it cannot be set automatically in every situation
where it is relevant, in those cases you should set it explicitly.  For
example, node names appearing in headings,
most parts of the definition lines (except for the category), and index
entries in index defined by @code{@@defcodeindex} in
@code{@@printindex} formatting should be formatted in code expansion context.
Conversly, in some cases, you may want to unset code expansion context and
convert in the normal context.

You set the expansion context through flags passed in function arguments.  You
can set different flags concurrently, in case you want to set multiple
expansion contexts.  The flags are:

@table @code
@item $Texinfo::Convert::HTML::CTXF_string
Add this flag for an expansion in string context.

@item $Texinfo::Convert::HTML::CTXF_code
Add this flag for an expansion in code context.

@item $Texinfo::Convert::HTML::CTXF_normal
Add this flag to unset code context.
@end table

To set code expansion in the main formatting document context, call
@code{set_context_convert_tree}:

@deftypefun {@var{$converted_text} =} @var{$converter}->set_context_convert_tree (@var{\%element}, @var{$expansion_context_flags}, @var{$explanation})
@var{\%element} is a Texinfo tree element. @var{$expansion_context_flags} is
an integer specifying the expansion context that is wanted. @var{$explanation}
is optional, it is a string explaining why the function was called, to help in
case of debugging.  The function sets the expansion context and returns
@var{\%element} converted by @code{convert_tree}.

Since the main document expansion context should never be in string expansion
context string expansion context flag is ignored.
@end deftypefun

In the following example, the content of an existing tree element is copied,
text is prependended and the resulting new tree element is converted in
code expansion context:
@example
@group
my @@contents = @@@{$element->@{'contents'@}@};
push @@contents, Texinfo::TreeElement::new(@{'text' => ' HTML text '@});
my $new_element = Texinfo::TreeElement::new(@{'contents' => \@@contents@});
my $result = $converter->set_context_convert_tree($new_element,
                              $Texinfo::Convert::HTML::CTXF_code);
return "<p>".$result."</p>";
@end group
@end example

To set the expansion context in other formatting contexts, you should call
@ref{@code{convert_tree_new_formatting_context}}
and set the expansion context flags argument with flags
set for the expansions you want.  You can set different flags concurrently,
in case you want to set multiple expansion contexts.  Since a new context
is created, there cannot be a code context to unset, therefore
the normal context flag is ignored.

For example:

@example
@group
# conversion in string context
my $result_string = $converter->convert_tree_new_formatting_context(
                     $element, 'in string',
                     $Texinfo::Convert::HTML::CTXF_string);
@end group

@group
my $multi_flag = 0;
$multi_flag |= $Texinfo::Convert::HTML::CTXF_string;
$multi_flag |= $Texinfo::Convert::HTML::CTXF_code;
# conversion in code and string context
my $result_code_string
    = $converter->convert_tree_new_formatting_context(
                     $element, 'in code string', $multi_flag);
@end group

@group
if ($converter->in_string()) @{
  return $result_string;
@}
return "<i title=\"$result_string\">$text</i>\n"
        . "<i title=\"$result_code_string\">again $text</i>\n";
@end group
@end example


@node Conversion to Plain Text
@subsection Conversion to Plain Text

@findex convert_to_text
@findex Texinfo::Convert::Text::convert_to_text
The conversion to plain text can be achieved by using the @code{Texinfo::Text}
converter @code{convert_to_text} function.

@code{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 @code{$converter->@{'convert_text_options'@}}.

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

@findex Texinfo::Convert::Text::set_options_code
@findex Texinfo::Convert::Text::set_options_code
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 @code{Texinfo::Convert::Text::set_options_code} and
@code{Texinfo::Convert::Text::reset_options_code}:
@example
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'@});
@end example

@findex Texinfo::Convert::Text::set_options_encoding_if_not_ascii
If encoded characters should be used irrespective of the specified document
encoding, a possibility relevant, in general, for file names,
@code{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 @code{Texinfo::Convert::Text::reset_options_encoding}:
@example
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'@});
@end example


@node Texinfo Tree Elements in User Defined Functions
@subsection 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:

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

The following is incorrect:

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


@node Customization and Use of Formatting Functions
@chapter 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 @dfn{conversion} functions used
for output units and elements of the Texinfo tree, and other @dfn{formatting}
functions with diverse purposes, including formatting that are not based on
tree elements (for example beginning and end of file formatting).
@dfn{Conversion} functions are described in the next chapters.

This chapter describes how @dfn{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 (@pxref{Output Units}) can be considered as formatting functions, but are
registered especially (@pxref{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.


@node Registering and Getting Specific Formating Functions
@section Registering and Getting Specific Formating Functions

User defined formatting functions are registered with
@code{texinfo_register_formatting_function}:

@defun texinfo_register_formatting_function ($formatted, @
                            \@ampchar{}handler)
@var{$formatted} is a string describing the formatting
function. @var{\&handler} is the user defined function reference.
@end defun

To call a formatting function from user defined code, the
function reference should first be retrieved using @code{formatting_function}:

@deftypefun {@var{\&formatting_function} =} @var{$converter}->formatting_function (@var{$formatted})
@var{$formatted} is a string describing the formatting
function. Returns the associated formatting function reference.
@end deftypefun

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

@deftypefun {@var{\&default_formatting_function} =} @var{$converter}->default_formatting_function (@var{$formatted})
@var{$formatted} is a string describing the formatting
function. Returns the default formatting function reference.
@end deftypefun

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.


@node Basic Formatting Customization
@section Basic Formatting Customization

The following formatting functions references handle basic formatting
and are called from diverse formatting and conversion functions.
@xref{Registering and Getting 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.

@table @code
@item format_comment

@deftypefn {Function Reference} @var{$text} format_comment  @
                                       (@var{$converter}, @var{$input_text})
Return @var{$input_text} in a comment.
@end deftypefn

The following function can be used to format an XML comment:

@deftypefun {@var{$comment} =} @var{$converter}->xml_comment (@var{$text})
Returns an XML comment for @var{$text}.
@end deftypefun

@item format_heading_text

@deftypefn {Function Reference} @var{$text} format_heading_text @
  (@var{$converter}, @var{$command_name}, @var{\@@classes}, @var{$input_text}, @var{$level}, @var{$id}, @var{\%element}, @var{$target})
Returns a heading formatted using @var{$input_text} as heading text,
@var{$level} as heading level, @var{\@@classes} for a class attribute.
@var{$command_name} gives an information on the @@-command the heading is
associated with and can be @code{undef}, for instance for special output units
headings.

@var{$id} is an optional identifier, and @var{\%element} is an optional
Texinfo tree element associated with the heading.  @var{$target} is the
id of the element this heading is referring to.

In the default case, if the @var{$target} or @var{$id} are specified, a
copiable anchor will be generated and injected into the heading.  If
both are specified, @var{$id} is preferred over @var{$target}, as it is closer
to the element the user sees the anchor on.
@end deftypefn

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

A formatted headings is, in the default case, like @code{<h2>@var{$input_text}</h2>}
for a @var{$level} 2 heading.

@item format_program_string

@deftypefn {Function Reference} @var{$text} format_program_string (@var{$converter})
This function reference should return the formatted program
string.
@end deftypefn

@item format_protect_text
@deftypefn {Function Reference} @var{$text} format_protect_text  @
                                        (@var{$converter}, @var{$input_text})
Return @var{$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
@code{&@{$converter->formatting_function('format_protect_text')@}(...)}@footnote{The function called is actually the
function referenced as @code{$converter->formatting_function('format_protect_text')}
in the default case, but it is called directly to avoid an indirection}.
@end deftypefn

The following function can be used to protect XML special characters:

@deftypefun {@var{$protected_text} =} @var{$converter}->xml_protect_text (@var{$text})
Protect special XML characters (@samp{&}, @samp{<}, @samp{>}, @samp{"})
of @var{$text}.
@end deftypefun

@item format_separate_anchor

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

@deftypefn {Function Reference} @var{$text} format_separate_anchor @
                               (@var{$converter}, @var{$id}, @var{$class})
@var{$id} is the identifier.
@var{$class} is an optional class to be used in an HTML class attribute.

Return an anchor with identifier @var{$id}.
@end deftypefn

@end table

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

The default function used for separate anchors can be replaced by a user-defined
anchor formatting function using a @code{<p>} element with:
@example
@group
sub my_format_separate_anchor($$;$) @{
  my ($converter, $id, $class) = @@_;

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

texinfo_register_formatting_function('format_separate_anchor',
                                     \&my_format_separate_anchor);
@end group
@end example


@node Tree Element Conversion Customization
@chapter 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.  This corresponds to the
@code{def_line}, @code{definfoenclose_command} and @code{index_entry_command}
types.


@node Command Tree Element Conversion
@section 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.


@node Command Tree Element Conversion Functions
@subsection Command Tree Element Conversion Functions

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

@defun texinfo_register_command_formatting ($command_name, \@ampchar{}handler)
@var{$command_name} is an @@-command name, without the leading @@.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:
@deftypefn {Function Reference} @var{$text} command_conversion  @
           (@var{$converter}, @var{$command_name}, @var{\%element}, @var{\@@args}, @var{$content})
@var{$converter} is a converter object. @var{$command_name}
is the @@-command name without the @@. @var{\%element} is the Texinfo
element.

@var{\@@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 @code{undef} if the
argument is empty, or a hash reference, with keys
corresponding to possible argument formatting contexts:

@table @code
@item normal
Argument formatted in a normal context

@item monospace
Argument formatted in a context where spaces are kept as is, as well as
quotes and minus characters, for instance in @samp{--} and @samp{``}.  Both
in preformatted and code context.  @xref{Init File Expansion Contexts}.

@item monospacestring
Same as monospace, but in addition in string context. @xref{Init File Expansion Contexts}.

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

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

@item raw
Text is kept as is, special HTML characters are not protected.  Appears only
as @code{@@inlineraw} second argument.

@item string
In string context. @xref{Init File Expansion Contexts}.

@item arg_tree
The Texinfo tree element corresponding to the argument.
@xref{Texinfo Tree Elements in User Defined Functions}.

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

@end table

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

For example, @code{$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 @code{@@anchor} argument is only available
as @code{monospacestring}.

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

The @var{$text} returned is the result of the @@-command conversion.
@end deftypefn

Accent commands do not have any formatted argument prepared, because the
formatting of accent commands taking arguments is usually done differently
(@pxref{Accent Commands with Arguments Formatting}).

@float Table, HTML command arguments formatting
@multitable {@code{@@inlinefmtifelse}} {monospacestring} {filenametext} {filenametext} {filenametext} {filenametext}
@include html_default_commands_args.texi
@end multitable
@caption{HTML command arguments formatting contexts in conversion function argument}
@end float

To call a conversion function from user defined code, the function reference
should first be retrieved using @code{command_conversion}:

@deftypefun {@var{\&command_conversion} =} @var{$converter}->command_conversion (@var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
conversion function reference for @var{$command_name}, or @samp{undef} if there is none,
which should only be the case for @@-commands ignored in HTML not defined by the user.
@end deftypefun

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

It is possible to have access to the default conversion function reference.
The function used is @code{default_command_conversion}:

@deftypefun {@var{\&default_command_conversion} =} @var{$converter}->default_command_conversion (@var{$command_name})
@deftypefunx {@var{\&default_command_conversion} =} Texinfo::Convert::HTML::default_command_conversion (undef, @var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
default conversion function reference for @var{$command_name}, or @samp{undef} if there is none,
which should only be the case for @@-commands ignored in HTML.
@end deftypefun

For example, to use the same conversion function for @code{@@setchapternewpage}
as for @code{@@documentlanguage}, a function that set the customization
variable to the command argument:
@example
use Texinfo::Convert::HTML;

texinfo_register_command_formatting('setchapternewpage',
     Texinfo::Convert::HTML::default_command_conversion(undef,
                                               'documentlanguage'));
@end example


@node Command Tree Element Opening Functions
@subsection Command Tree Element Opening Functions

User defined functions called when an @@-command element is first encountered
are registered with @code{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 @code{@@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 (@pxref{Inline Text Containers
Formatting}).


@defun texinfo_register_command_opening ($command_name, \@ampchar{}handler)
@var{$command_name} is an @@-command name, with the leading @@.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} command_open @
           (@var{$converter}, @var{$command_name}, @var{\%element})
@var{$converter} is a converter object. @var{$command_name}
is the @@-command name without the @@. @var{\%element} is the Texinfo
element.

The @var{$text} returned is prepended to the formatting of the
@@-command.
@end deftypefn

It is possible to have access to the default opening function reference.
The function used is @code{default_command_open}:
@deftypefun {@var{\&default_command_open} =} @var{$converter}->default_command_open (@var{$command_name})
@deftypefunx {@var{\&default_command_open} =} Texinfo::Convert::HTML::default_command_open (undef, @var{$command_name})
@var{$command_name} is the @@-command name without the @@. Returns the
default opening function reference for @var{$command_name}, or @samp{undef} if there is none.
@end deftypefun


@node Heading Commands Formatting
@subsection 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 (@pxref{HTML Output Structure Customization,,, texinfo, Texinfo}),
by changing the links formatting (@pxref{File Names and Links Customization for
HTML,,, texinfo, Texinfo}), the navigation panels formatting
(@pxref{Customization of Navigation and Headers,,, texinfo, Texinfo}) and the
heading levels (@pxref{Specific Customization of HTML Formatting,,, texinfo,
Texinfo}).

@code{@@node} and sectioning commands default conversion function call
@code{format_heading_text} (@pxref{Basic Formatting Customization})
and @code{format_element_header} (@pxref{Element Header and Footer
Formatting}).  The @code{@@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 (@xref{Command Tree Element Conversion Functions}).

In the default formatting, when a sectioning command is encountered, a
@code{<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
@code{register_opened_section_level}:

@defun @var{$converter}->register_opened_section_level ($filename, $level, $closing_text)
@var{$filename} is the filename the section belongs to.  You could use
@code{$converter->current_filename()} for @var{$filename}.
@var{$level} is the sectioning command level.  It is typically
obtained as @code{$section->@{'extra'@}->@{'section_level'@}}
(@pxref{Sectioning Commands Elements and Document Structure}).
@var{$closing_text} is the text that should be output when the
section level @var{$level} is closed.
@end defun

The function for closing registered section extents is
@code{close_registered_sections_level}:

@deftypefun {@var{\@@closing_texts} =} @var{$converter}->close_registered_sections_level (@var{$filename}, @var{$level})
@var{$filename} is the filename the closed sections belong to.  You could use
@code{$converter->current_filename()} for @var{$filename}.
@var{$level} is the sectioning command level
(@pxref{Sectioning Commands Elements and Document Structure}).  Opened
sections are closed down to section level @var{$level}.  The closing texts
are returned in the @var{\@@closing_texts} array reference in order.
@end deftypefun

Example of use:
@example
@group
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");
@end group
@end example


@node Target Tree Element Link
@subsection Target Tree Element Link

User-defined code in functions replacing default conversion functions for
@code{@@xref} and similar @@-commands output, @code{@@menu}, @code{@@node},
sectioning commands, @code{@@printindex} and @code{@@listoffloats} formatting
requires links, labels and files information, mainly to output hyperlinks to
@dfn{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, @code{@@node}, @code{@@anchor} and @code{@@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
(@pxref{Output Units Information}).

To get the unique Texinfo tree element corresponding to an identifier, use
@code{converter_find_identifier_target}:

@deftypefun {@var{\%element} =} @
     @var{$converter}->converter_find_identifier_target (@var{$label})
Return the element in the tree that the @var{$label} string refers to.
@end deftypefun

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

Identifiers are available for target @@-commands and for @@-command referring
to target elements such as @code{@@xref} or @code{@@menu} entry node argument
as the @code{extra} @samp{normalized} element key.

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

Tree elements not associated with an identifier are obtained each differently.
For example, elements associated with index entries can be obtained using the
Texinfo parsed document index information (@pxref{@code{indices_information}}),
or through sorted indices
information (@pxref{Specific Formatting for Indices}).  Footnote elements
can be obtained through the @code{@@footnote} conversion function,
and can also be passed to footnote formatting functions
(@pxref{Customizing Footnotes}).  Floats elements in @code{@@listoffloats}
can be obtained from document information (@pxref{@code{floats_information}}).

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

@deftypefun {@var{$identifier} =} @var{$converter}->command_id (@var{\%target_element})
Returns the id specific of the @var{\%target_element} tree element.
@end deftypefun

@deftypefun {@var{$file_name} =} @var{$converter}->command_filename (@var{\%target_element})
Returns the file name of the @var{\%target_element} tree element.
@end deftypefun

@deftypefun {@var{$href} =} @var{$converter}->command_href (@var{\%target_element}, @
       @var{$source_filename}, @var{$source_command}, @var{$specified_target})
Return string for linking to @var{\%target_element} with @code{<a href>}
or @code{undef} if not found or empty.
@var{$source_filename} is the file the link comes from. If not set, the current
file name is used.  @var{$source_command} is an optional argument, the
@@-command the link comes from.  It is only used for messages.
@var{$specified_target} is an optional identifier that overrides the target
identifier if set.
@end deftypefun

To get the text of tree elements that may be used as link description, use
@code{command_text} or @code{command_name}:

@deftypefun {@var{$result} =} @var{$converter}->command_text (@var{\%target_element}, @var{$type})
@deftypefunx {@var{$result} =} @var{$converter}->command_name (@var{\%target_element}, @var{$type})
Return the information to be used for a hyperlink to @var{\%target_element}.
The information returned depends on @var{$type}:

@table @emph
@item text
Return text.

@item string
Return text in string context.  @xref{Init File Expansion Contexts}.

@item text_nonumber
Return text without the sectioning command number.

@item string_nonumber
Return text in string context without the sectioning command number.

@end table

If @code{command_name} is called, the text corresponding to the element name
is returned for commands with different arguments for the name and the cross-reference
(@code{@@namedanchor}).  For other @@-commands, the result is the same as
@code{command_text}.
@end deftypefun

Using those functions, a target element hyperlink can be constructed as:
@example
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>";
@end example

To obtain the top level command element associated with a footnote,
float or index entry target element, use @code{command_root_element_command}:

@deftypefun {@var{\%top_level_element} =} @var{$converter}->command_root_element_command @
                                                    (@var{\%target_element})
Return the top level element, either a @code{@@node} or a sectioning element
@var{\%target_element} is in.
@end deftypefun

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:

@example
my $entry_root_link = '';
my $associated_command
 =  $converter->command_root_element_command($target_element);
if (defined($associated_command)) @{
@group
  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;
  @}
@end group
@}

my $formatted_entry = "<td><tr>$hyperlink</tr>"
                  ."<tr>$entry_root_link</tr></td>\n";
@end example

To get the node element associated with a target element, use
@code{command_node}:

@deftypefun {@var{\%node_element} =} @var{$converter}->command_node (@var{\%target_element})
Return the node element associated with @var{\%target_element}.
@end deftypefun

To get the description associated with a target element, typically the
@code{@@nodedescription} associated with a @code{@@node}, use
@code{command_description}:

@deftypefun {@var{$result} =} @var{$converter}->command_description (@var{\%target_element}, @var{$type})
Return the description of @var{\%target_element}. The precise formatting
depends on @var{$type}:

@table @emph
@item text
Return text.

@item string
Return text in string context.  @xref{Init File Expansion Contexts}.
@end table
@end deftypefun

For elements that are not target elements, use
@code{get_element_root_command_element} to get the root level tree
element and the output unit containing the element:

@anchor{@code{get_element_root_command_element}}
@deftypefun {@var{\%output_unit}, @var{\%top_level_element} =} @var{$converter}->get_element_root_command_element (@var{\%element})
Return the output unit and top level element a Texinfo tree
@var{\%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
@code{USE_NODES}. If @code{USE_NODES} is set the @code{@@node} is preferred,
otherwise the sectioning command is preferred.
@end deftypefun

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


@node Type Tree Element Conversion
@section Type Tree Element Conversion

All the containers and text Texinfo tree elements
not handled with command tree elements have a @dfn{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 @code{text} type is used
to select the formatting functions, irrespective of the actual type of
such a tree element.  The @code{text} type does not exist in actual
Texinfo tree elements.


@node Type Tree Element Conversion Functions
@subsection 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
@code{texinfo_register_type_formatting}.  For containers, the user defined
function is called after conversion of the content.

@defun texinfo_register_type_formatting ($type, \@ampchar{}handler)
@var{$type} is the element type.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} type_conversion (@var{$converter}, @
        @var{$type}, @var{\%element}, @var{$content})
@var{$converter} is a converter object. @var{$type} is the element type.
@var{\%element} is the Texinfo element.  @var{$content} is text for elements
associated with text, or the formatted contents for other elements.
@var{$content} can be @code{undef} or the empty string.

The @var{$text} returned is the result of the element conversion.
@end deftypefn

To call a conversion function from user defined code, the function reference
should first be retrieved using @code{type_conversion}:

@deftypefun {@var{\&type_conversion} =} @var{$converter}->type_conversion (@var{$type})
@var{$type} is the element type.  Returns the
conversion function reference for @var{$type}, or @samp{undef} if there is none,
which should only be the case for types ignored in HTML not defined by the user.
@end deftypefun

It is possible to have access to the default conversion function reference.
The function used is @code{default_type_conversion}:

@deftypefun {@var{\&default_type_conversion} =} @var{$converter}->default_type_conversion (@var{$type})
@deftypefunx {@var{\&default_type_conversion} =} Texinfo::Convert::HTML::default_type_conversion (undef, @var{$type})
@var{$type} is the element type.  Returns the
default conversion function reference for @var{$type}, or @samp{undef} if there is none,
which should only be the case for types ignored in HTML.
@end deftypefun

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

@example
@group
sub my_tree_element_convert_paragraph_type($$$$) @{
  my ($converter, $type, $element, $content) = @@_;

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

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

@group
  my @@contents = @@@{$element->@{'contents'@}@};
  push @@contents, Texinfo::TreeElement::new(@{'text' => ' HTML text '@});
  my $new_element = Texinfo::TreeElement::new(@{'contents' => \@@contents@});
  my $result = $converter->set_context_convert_tree($new_element,
                              $Texinfo::Convert::HTML::CTXF_code);
  return "<p>".$result."</p>";
@}
@end group

texinfo_register_type_formatting('paragraph',
                        \&my_tree_element_convert_paragraph_type);
@end example

@node Type Tree Element Opening Functions
@subsection Type Tree Element Opening Functions

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

@defun texinfo_register_type_opening ($type, \@ampchar{}handler)
@var{$type} is the element type.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} type_open (@var{$converter}, @
        @var{$type}, @var{\%element})
@var{$converter} is a converter object. @var{$type} is the element type.
@var{\%element} is the Texinfo
element.

The @var{$text} returned is prepended to the formatting of the
type container.
@end deftypefn

It is possible to have access to the default opening function reference.
The function used is @code{default_type_open}:
@deftypefun {@var{\&default_type_open} =} @var{$converter}->default_type_open (@var{$type})
@deftypefunx {@var{\&default_type_open} =} Texinfo::Convert::HTML::default_type_open (undef, @var{$type})
@var{$command_name} is the element type. Returns the
default opening function reference for @var{$type}, or @samp{undef} if there is none.
@end deftypefun

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
(@pxref{Inline Text Containers Formatting}).


@node Text Tree Elements Conversion
@subsection Text Tree Elements Conversion

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

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

@example
sub my_convert_text($$$$) @{
  my ($converter, $type, $element, $text) = @@_;

  # ...

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

  # ...
@}

texinfo_register_type_formatting ('text', \&my_convert_text);
@end example

The @var{$type} free conversion function argument is the
actual type of the converted element (can be @code{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:

@table @emph
@item code

@deftypefun {@var{$in_code} =} @var{$converter}->in_code ()
Return true if in code context.  @xref{Init File Expansion Contexts}.
@end deftypefun

@item math

@deftypefun {@var{$in_math} =} @var{$converter}->in_math ()
Return true if in math context. @xref{Init File Expansion Contexts}.
@end deftypefun

@item raw

@deftypefun {@var{$in_raw} =} @var{$converter}->in_raw ()
Return true if in raw format, in @code{@@inlineraw} or in @code{@@html}.
In such a context, text should be kept as is and special HTML characters should
not be protected.
@end deftypefun

@item verbatim

@deftypefun {@var{$in_verbatim} =} @var{$converter}->in_verbatim ()
Return true if in verbatim context, corresponding to @code{@@verb} and @code{@@verbatim}.
In general, HTML characters should be protected in this context.
@end deftypefun

@item upper-case

@deftypefun {@var{$in_upper_case} =} @var{$converter}->in_upper_case ()
Return true if in upper-case context, corresponding to @code{@@sc}.
@end deftypefun

@item non-breakable space

@deftypefun {@var{$in_non_breakable_space} =} @var{$converter}->in_non_breakable_space ()
Return true if in context where line breaks are forbidden, corresponding
to @code{@@w}.
@end deftypefun

@item space protected

@deftypefun {@var{$in_space_protected} =} @var{$converter}->in_space_protected ()
Return true if in context where space and newline characters are kept,
corresponding to @code{@@verb}.
@end deftypefun
@end table

You can use the @code{xml_format_text_with_numeric_entities} method
for conversion to text if you want to output numeric entities:
@deftypefun {@var{$formatted_text} =} @var{$converter}->xml_format_text_with_numeric_entities (@var{$text})
Replace quotation marks and hyphens used to represent dash in
Texinfo code in the @var{$text} string by numeric XML entities
and return the resulting string.
@end deftypefun


@node Inline Text Containers Formatting
@subsection Inline Text Containers Paragraph and Preformatted Formatting

Text is mainly output in two @dfn{inline} text containers, @code{paragraph} for
text in paragraph and @code{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, @code{@@quotation}
argument should in general be prepended to the first paragraph in @code{@@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
@code{register_pending_formatted_inline_content}:

@defun @var{$converter}->register_pending_formatted_inline_content ($category, $content)
@var{$content} is the formatted content to be registered and output
in the next inline container.  @var{$category} is a indicator of the source
of the formatted inline content, mostly used to cancel registered content
if no inline container was seen.
@end defun

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

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 @code{cancel_pending_formatted_inline_content}:

@deftypefun {@var{$cancelled_content} =} @var{$converter}->cancel_pending_formatted_inline_content (@var{$category})
Cancel the first @var{$category} pending formatted content text found.
Returns @code{undef} if nothing was cancelled, and the cancelled
content otherwise.
@end deftypefun

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

@deftypefun {@var{$content} =} @var{$converter}->get_pending_formatted_inline_content ()
Returns the concatenated pending content.
@end deftypefun

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,
@code{associate_pending_formatted_inline_content}, and get the associated
content, @code{get_associated_formatted_inline_content}.
@code{associate_pending_formatted_inline_content} is normally called in inline
container opening code, right after
@code{get_pending_formatted_inline_content}, while
@code{get_associated_formatted_inline_content} is called in the inline
container conversion function (@pxref{Type Tree Element Conversion Functions}).

@defun @var{$converter}->associate_pending_formatted_inline_content (\%element, $content)
Associate @var{$content} to the Texinfo tree element @var{\%element}.
@end defun

@deftypefun {@var{$content} =} @var{$converter}->get_associated_formatted_inline_content (@var{\%element})
Get @var{$content} associated with the Texinfo tree element @var{\%element}.
@end deftypefun

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

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

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

@group
sub my_final_convert_paragraph_type($$$$) @{
  my ($converter, $type, $element, $content) = @@_;

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

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

@group
  my @@contents = @@@{$element->@{'contents'@}@};
  push @@contents, Texinfo::TreeElement::new(@{'text' => ' HTML text '@});
  my $new_element = Texinfo::TreeElement::new(@{'contents' => \@@contents@});
  my $result = $converter->set_context_convert_tree($new_element,
                                $Texinfo::Convert::HTML::CTXF_code);
  return "<p>".$prepended.$result."</p>";
@}
@end group

texinfo_register_type_formatting('paragraph',
                             \&my_final_convert_paragraph_type);
@end example


@node Output Units Conversion Functions
@chapter Output Units Conversion Functions

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

User defined functions called for the conversion of an output unit
are registered with @code{texinfo_register_output_unit_formatting}.  The user
defined function is called after conversion of the content.

@defun texinfo_register_output_unit_formatting ($unit_type, \@ampchar{}handler)
@var{$unit_type} is the output unit type.
@var{\&handler} is the user defined function reference.
@end defun

The call of the user defined functions is:

@deftypefn {Function Reference} @var{$text} output_unit_conversion (@var{$converter}, @
        @var{$unit_type}, @var{\%output_unit}, @var{$content})
@var{$converter} is a converter object. @var{$unit_type} is the output unit
type. @var{\%output_unit} is the output unit.  @var{$content} the formatted
contents.  @var{$content} can be @code{undef} or the empty string.

The @var{$text} returned is the result of the output unit conversion.
@end deftypefn

To call a conversion function from user defined code, the function reference
should first be retrieved using @code{type_conversion}:

@deftypefun {@var{\&output_unit_conversion} =} @var{$converter}->output_unit_conversion (@var{$unit_type})
@var{$unit_type} is the output unit type.  Returns the
conversion function reference for @var{$unit_type}, or @samp{undef} if there is none.
@end deftypefun

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

@deftypefun {@var{\&default_output_unit_conversion} =} @var{$converter}->default_output_unit_conversion (@var{$unit_type})
@var{$unit_type} is the output unit type.  Returns the
default conversion function reference for @var{$unit_type}, or @samp{undef}
if there is none.
@end deftypefun

Normal output units with output unit type @code{unit} default conversion
involves calling the formatting reference
@code{format_element_footer} (@pxref{Element Header and Footer Formatting}).

Special units conversion is achieved by calling
@code{special_unit_body_formatting} (@pxref{Special Unit Body Formatting
Functions}), @code{format_navigation_header} (@pxref{Navigation Panel and
Navigation Header Formatting}), @code{format_heading_text} (@pxref{Basic
Formatting Customization}) and @code{format_element_footer} (@pxref{Element
Header and Footer Formatting}).  Special units type is @code{special_unit}.


@c TODO where to put that?
@node Shared Conversion State
@chapter 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 @dfn{shared conversion state}.
Each data piece in the @dfn{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 @code{@@abbr}, @code{@@footnote},
@code{@@node}, sectioning commands, @code{@@quotation} and @code{@@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 (@pxref{Customization and Use of Formatting
Functions}), tree elements (@pxref{Tree Element Conversion Customization}) and output
units conversion functions (@pxref{Output Units Conversion Functions}).


@node Define Get and Set Shared Conversion State
@section Define, Get and Set Shared Conversion State

Four types for selectors and value are currently considered:

@table @code
@item string
A string.
@item integer
An integer
@item element
A Texinfo tree element.
@item index_entry.
An index entry reference as appearing in index data structures.
@xref{Specific Formatting for Indices}.
@end table

New shared infomation is defined with @code{define_shared_conversion_state}:

@defun @var{$converter}->define_shared_conversion_state ($cmdname, $name, \@@specification)
@var{$cmdname} is an @@-command name, without leading @@. @var{name} is the name
associated with the data.  The @code{top} command name is conventionally used if
there is no natural association with another @@-command.
@var{\@@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@footnote{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.}.

For example, @code{['integer', 'element', 'string']} specifies a @samp{string}
type for the value, and two selectors, the first with @samp{integer} type,
and the second with @samp{element} type.  @code{['integer']} specifies
an integer for the value and no selector.
@end defun

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

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 @code{get_shared_conversion_state} is used to get information:

@deftypefun {@var{$value} =} @var{$converter}->get_shared_conversion_state (@var{$cmdname}, @var{$name}, [@var{$selector} @dots{}])
Return the reference @var{$value} associated with @var{$cmdname}
and @var{$name}. The number of selectors given in argument should match
the number of selectors in the definition (possibly none).
@end deftypefun

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

The function @code{set_shared_conversion_state} is used to set
shared information:

@defun @var{$converter}->define_shared_conversion_state (@var{$cmdname}, @var{$name}, [@var{$selector} @dots{}], @var{$value})
Sets @var{$value} associated with @var{$cmdname}
and @var{$name}. The number of selectors given in argument should match
the number of selectors in the definition (possible none).
@end defun

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

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

@node Shared Conversion State in Default Formatting
@section Shared Conversion State in Default Formatting

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

@multitable {@code{nodedescription}} {@code{formatted_index_entries}} {(@code{@@nodedescription} tree} {integer}
@headitem Command @tab Name @tab Selectors @tab Value
@item @code{abbr} @tab @code{explained_commands} @tab string (first argument) @tab string
@item @code{acronym} @tab @code{explained_commands} @tab string (first argument) @tab string
@item @code{footnote} @tab @code{footnote_number} @tab @tab integer
@item @code{footnote} @tab @code{footnote_id_numbers} @tab string (footnote id) @tab integer
@item @code{listoffloats} @tab @code{formatted_listoffloats} @tab string (normalized argument) @tab integer
@item @code{menu} @tab @code{html_menu_entry_index} @tab @tab integer
@item @code{printindex} @tab @code{formatted_index_entries} @tab index_entry (index entry hash) @tab integer
@item @code{top} @tab @code{in_skipped_node_top} @tab @tab integer
@item @code{nodedescription} @tab @code{formatted_nodedescriptions} @tab element (@code{@@node} tree element) @tab integer
@end multitable

These shared information data correspond to:
@vtable @code
@item explained_commands
Associate the explanation given in a previous @code{@@abbr} or
@code{@@acronym} second argument to first @code{@@abbr} or
@code{@@acronym} arguments.
@item footnote_number
The current number of footnotes formatted in document.
@item 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 @code{@@copying}
and multiple @code{@@insertcopying}.
@item formatted_listoffloats
Associate a list of float type to the number of time it was formatted.
@item html_menu_entry_index
Current number of menu entries in a menu. Reset to 0 at @code{@@menu} beginning.
@item formatted_index_entries
Associate an index entry to the number of time it was formatted.
@item in_skipped_node_top
Set to 1 in a @code{Top} node being skipped, in case
@code{NO_TOP_NODE_OUTPUT} is set.
@item formatted_nodedescriptions
Associate a @code{@@node} tree element to the number of time
its description was formatted.
@end vtable


@node Translations in Output and Customization
@chapter Translations in Output and Customization

Translated strings can be specified in customization functions, for
@@-commands without arguments (@pxref{Simple Customization for Commands
Without Arguments}), for direction strings (@pxref{Direction Strings
Customization}) and for specific elements headings such as footnotes,
contents or about (@pxref{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, @code{cdt}, @code{cdt_string} or @code{pcdt}.

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.

@xref{Internationalization of Document Strings,,, texinfo, Texinfo} for additional
information on the default case.

@node Internationalization of Output Strings
@section Internationalization of Output Strings

@c old name
@anchor{Internationalization of Strings Function}

@vindex texinfo_document @r{Gettext domain}
The subroutines @code{cdt}, @code{cdt_string} or @code{pcdt}, are used for
strings translations:

@deftypefun {@var{$translated_tree} =} @var{$converter}->cdt (@var{$string}, @var{\%variables_hash}, @var{$translation_context})
@deftypefunx {@var{$translated_string} =} @var{$converter}->cdt_string (@var{$string}, @var{\%variables_hash}, @var{$translation_context})
@deftypefunx {@var{$translated_tree} =} @var{$converter}->pcdt (@var{$translation_context}, @var{$string}, @var{\%variables_hash})
@var{$string} is the string to be translated, @var{\%variables_hash}
is a hash reference holding the variable parts of the translated
string.   @var{$translation_context} is an optional translation context
that limits the search of the translated string to that context
(@pxref{Contexts,,,gettext,GNU gettext tools}).

The result returned is a Perl Texinfo tree for @code{cdt} and @code{pcdt}
and a string for @code{cdt_string}.  With @code{cdt_string} the substitutions
may only be strings.

If called as @code{pcdt}, @var{$translation_context} is not optional
and is the first argument.
@end deftypefun

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

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

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

@cindex @code{_converted} special text element
@cindex Special text element, @code{_converted}
When combining conversion and translation, it can be useful to insert
already converted text.  A special text element with type @code{_converted}
can be used for that purpose, the text of this text element is considered
to be already formatted.

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

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


@node Translated Strings Customization
@section Translated Strings Customization

To customize strings translations, register the @code{format_translate_message}
function reference:

@deftypefn {Function Reference} @var{$translated_string} format_translate_message @
  (@var{$converter}, @var{$string}, @var{$lang_info}, @var{$translation_context})
@var{$string} is the string to be translated, @var{$lang_info} holds information on
the language.  @var{$translation_context} is an optional translation context.

The language can be accessed through @var{$lang_info}.  Two representations are
available, as an @dfn{XPG locale} (@pxref{Locale Names,,,gettext,
GNU @code{gettext} utilities}) or as a @uref{BCP47 language tag,
https://www.rfc-editor.org/rfc/rfc5646.html}:
@table @asis
@item XPG locale
@cindex XPG locale
@code{@var{$lang_info}->xpg_locale()}
@item BCP47 language tag
@cindex BCP47 language tag
@code{@var{$lang_info}->bcp47_tag()}
@end table
The returned string may be empty if @code{@@documentlanguage} is not set.
In that case you can return the string untranslated.  Unless
@code{@@documentscript} or @code{@@documentlanguagevariant} are used, the
two representations are similar and return the @code{@@documentlanguage}, except that
the BCP47 language tag have @samp{-} instead of @samp{_} as separator.

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

@xref{Internationalization of Output Strings} for more information on
strings translations function arguments.
@end deftypefn

This function reference is not set in the default case.
@xref{Registering and Getting Specific Formating Functions} for information on how to
register and get the function reference.

@anchor{New translated strings example}
Here is an example with new translated strings added and definition
of @code{format_translate_message} to translate the strings:

@example
texinfo_register_no_arg_command_formatting('error', undef, undef,
                                                undef, 'error--&gt;');
my %translations = (
 'fr' => @{
           'error--&gt;' => @{'' => 'erreur--&gt;',@},
           # @dots{}
         @},
 'de_AT' => @{
           'error--&gt;' => @{'' => 'Fehler--&gt;',@},
           # @dots{}
         @}
 # @dots{}
);

sub my_format_translate_message($$$;$) @{
  my ($self, $string, $lang_info, $translation_context) = @@_;

  my $lang = $lang_info->xpg_locale();
  return $string if (!defined($lang) or $lang eq '');
  $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);

@end example


@node Translation Contexts
@section Translation Contexts

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

For direction strings, the translation context is based on the direction
name (@pxref{Directions}), with @samp{direction} prepended and another
string prepended, depending on the type of string:

@table @code
@item button
@samp{button label} is prepended

@item description
@samp{description} is prepended

@item text
@samp{string} is prepended
@end table

For example, the @code{Top} direction @code{button} direction string
translation context is @samp{Top direction button label}.

As an exception, the @code{This} direction has @samp{(current section)}
prepended to have a more explicit translation context.  The @code{This}
direction @code{text} direction string translation context is thus @samp{This
(current section) direction string}.

For special output unit headings, the translation context is obtained by
prepending @samp{section heading} to the special output unit variety (@pxref{Special
Units Varieties}).  For example, the @code{footnotes} special output unit
variety heading translation context is @samp{footnotes section heading}.

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

@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@{@}',@},
          @}
   @dots{}
);

@end example

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


@node Customizing Footnotes@comma{} Tables of Contents and About
@chapter 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 (@pxref{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
@ref{Special Units Varieties}.

@float Table, Special Units Varieties
@multitable {Short table of contents} {Special Unit Variety}
@headitem Special Unit @tab Special Unit Variety
@item Table of contents @tab @code{contents}
@item Short table of contents @tab @code{shortcontents}
@item Footnotes @tab @code{footnotes}
@item About @tab @code{about}
@end multitable
@caption{Association of special elements names with their special element variety}
@end float

The variety of special elements is the special unit
hash value associated with the @code{special_unit_variety} key.

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

@deftypefun {(@var{$special_unit_variety}, @var{\%output_unit}, @var{$class_base}, @var{$output_unit_direction}) =} @
  @var{$converter}->command_name_special_unit_information (@var{$command_name})
@var{$command_name} is an @@-command name without the leading @@.
If the @var{$command_name} is not associated with a special output unit, returns
@code{undef}.  Otherwise, return the @var{$special_unit_variety}
(@pxref{Special Units Varieties}), the @var{\%output_unit} output
unit, a @var{$class_base} string for HTML class attribute and the
@var{$output_unit_direction} direction corresponding to that special
elements (@pxref{Directions}).
@end deftypefun

In the current setup, special output units are associated with @code{@@contents},
@code{@@shortcontents} and @code{@@summarycontents} and with @code{@@footnote}.


@node Special Units Information Customization
@section Special Units Information Customization

To customize special output units formatting, a simple possibility is to
change the information associated with the special output units.
Two types of item can be customized, simple items and Texinfo code.
The Texinfo code is translated and converted.

The following simple items may be customized:

@table @code
@item class
String for special element HTML class attributes.

@item direction
Direction corresponding to the special element. @xref{Directions}.

@item order
Index determining the sorting order of special elements.

@item file_string
File string portion prepended to the special element file names, such as
@samp{_toc}.

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

@end table

The following Texinfo code item  may be customized:

@table @code
@item heading
Special element heading Texinfo code.
@end table

To set both type of information, use @code{texinfo_register_special_unit_info}
in an init file:

@defun texinfo_register_special_unit_info ($item_type, @
                           $special_unit_variety, $value)
Set @var{$item_type} information for the special unit variety
@var{$special_unit_variety} to @var{$value}.  @var{$value} may be
@samp{undef}, or an empty string, but only @code{heading} and
@code{target} should be set to that value as a non-empty value is
needed for the other items for formatting.
@end defun

To get the list of varieties, use @code{get_special_unit_info_varieties} on
a simple item:

@deftypefun {@var{$list} =} @var{$converter}->get_special_unit_info_varieties @
               (@var{$item_type})
@var{$item_type} is the simple item information to be retrieved as described above.
The list of the special units varieties with information for the
@var{$item_type} is returned.
@end deftypefun

To retrieve simple item information for formatting, use @code{special_unit_info}:

@deftypefun {@var{$value} =} @var{$converter}->special_unit_info @
                  (@var{$item_type}, @var{$special_unit_variety})
@var{$item_type} is the simple item to be retrieved as described above.
@var{$special_unit_variety} is a special unit variety, the corresponding
value is returned.
@end deftypefun

To get converted text corresponding to a Texinfo code item use
@code{special_unit_info_text}:

@deftypefun {@var{$result} =} @var{$converter}->special_unit_info_text @
                  (@var{$item_type}, @var{$special_unit_variety}, @
                   @var{$context})
@var{$item_type} is a Texinfo code item as described above.
@var{$special_unit_variety} is a special unit variety.  @var{$context} is
@samp{normal} or @samp{string}.  @xref{Init File Expansion Contexts}.  If
@var{$context} is @code{undef}, the @samp{normal} context is assumed.
The corresponding Texinfo code is translated, parsed to a Texinfo tree,
converted in the specified expansion context and the result is returned.
@end deftypefun


@node Customizing Footnotes
@section Customizing Footnotes

@vindex NUMBER_FOOTNOTES
@vindex NO_NUMBER_FOOTNOTE_SYMBOL
In the default case footnotes are numbered.  If @code{NUMBER_FOOTNOTES}
is set to 0, a @samp{*} is used instead, or the @code{NO_NUMBER_FOOTNOTE_SYMBOL}
customization variable value, if set.

Redefinition of @code{@@footnote} conversion reference and footnote formatting
references is needed for further customization.

@code{@@footnote} @@-commands appearing in the Texinfo elements tree
are converted like any other elements associated with @@-commands
(@pxref{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
@code{@@footnote} command at the location they appear in the document and the
functions formatting their argument elsewhere, two functions are available:
@code{register_footnote} to be called where they appear in the document, and
@code{get_pending_footnotes} to be called where they are formatted.

@defun @var{$converter}->register_footnote (\%element, $footnote_id, @
  $foot_in_doc_id, $number_in_doc, $footnote_location_filename, $multi_expanded_region)
@var{\%element} is the footnote Texinfo tree element. @var{$footnote_id} is the
identifier for the location where the footnote arguments are expanded.
@var{$foot_in_doc_id} is the identifier for the location where the footnote
appears in the document.  @var{$number_in_doc} is the number of the footnote
in the document.  @var{$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 @var{$multi_expanded_region} (@pxref{Other Dynamic Information}).
@end defun

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

@deftypefun {@var{\@@pending_footnotes_information} =} @var{$converter}->get_pending_footnotes ()
Returns in @var{\@@pending_footnotes_information} the information gathered
in @code{register_footnote}.  Each of the array reference
element in @var{\@@pending_footnotes_information} is an array reference
containing the arguments of @code{register_footnote} in the same order.
@end deftypefun

The formatting of footnotes content is done by the
@code{format_footnotes_sequence} formatting reference
(@pxref{Registering and Getting Specific Formating Functions}):

@deftypefn {Function Reference} @var{$footnotes_sequence} format_footnotes_sequence @
                                                  (@var{$converter})
Formats and returns the footnotes that need to be formatted.  This function
normally calls @code{get_pending_footnotes}.  The default function also calls
@code{footnote_location_href} to link to the location in the document where
the footnote appeared, and the @code{format_single_footnote} formatting
function to format a single footnote.
@end deftypefn

The formatting of one footnote is done by the @code{format_single_footnote}
formatting reference:

@deftypefn {Function Reference} @var{$footnote} format_single_footnote @
  (@var{$converter}, @var{\%element}, @var{$footnote_id}, @var{$number_in_doc}, @
   @var{$footnote_location_href}, @var{$footnote_mark})
Formats and returns a single footnote.
@var{\%element} is the footnote Texinfo tree element. @var{$footnote_id} is the
identifier for the location where the footnote arguments are expanded.
@var{$number_in_doc} is the number of the footnote
in the document.
@var{$footnote_location_href} is the href that links to the footnote location
in the main document.  @var{$footnote_mark} is the footnote number or mark.
@end deftypefn

If footnotes are in a separate output unit (@pxref{Output Units}), the
default footnote special output unit body formatting function calls
@code{format_footnotes_sequence} (@pxref{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
@code{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.

@deftypefn {Function Reference} @var{$footnotes_segment} format_footnotes_segment @
                                                        (@var{$converter})
Returns the footnotes formatted.  In the default case, the function reference
calls @code{format_footnotes_sequence} and also sets up a header with
@code{format_heading_text} (@pxref{Basic Formatting Customization}), using the
customization variables @code{FOOTNOTE_END_HEADER_LEVEL} and
the special @code{footnotes} element @code{heading} information
(@pxref{Special Units Information Customization}).
@end deftypefn

To get the id of a footnote in the main document, use
@code{footnote_location_target}:

@deftypefun {@var{$target} =} @var{$converter}->footnote_location_target (@var{\%footnote_element})
Return the id for the location of the footnote @var{\%footnote_element}
in the main document (where the footnote number or symbol appears).
@end deftypefun

To get an href to link to a footnote location in the main document, use
@code{footnote_location_href}:

@deftypefun {@var{$href} =} @var{$converter}->footnote_location_href (@var{\%footnote_element}, @
     @var{$source_filename}, @var{$specified_target}, @var{$target_filename})
Return string for linking to @var{\%footnote_element} location
in the main document with @code{<a href>}.  @var{$source_filename} is the file
the link comes from. If not set, the current file name is used.
@var{$specified_target} is an optional identifier that overrides the
target identifier if set.  @var{$target_filename} is an optional file name
that overrides the file name href part if set.
@end deftypefun

@xref{Target Tree Element Link} to get
link information for the location where footnote text is output.


@node Contents and Short Table of Contents Customization
@section Contents and Short Table of Contents Customization

@cindex Customization of tables of contents elements
@cindex Contents, customizing elements
@cindex Short table of contents element, customizing
@cindex Overview element, customizing

@c FIXME this is already documented in the Customization variables
@c documentation in the Texinfo manual.  Keep it anyway as it is
@c slightly more informative here?

@vindex CONTENTS_OUTPUT_LOCATION
You can set the customization variable @code{CONTENTS_OUTPUT_LOCATION}
to determine where the table of contents and short table of content
are output in the document (@pxref{HTML Output Structure Customization,,,
texinfo, Texinfo}):

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

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

@item 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 @code{FORMAT_MENU} set
to @samp{menu}.

@item after_title
The tables of contents are merged into the title material, which in turn is not
output by default; @pxref{HTML Title Page Customization}.
@end table

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

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

@deftypefn {Function Reference} @var{$toc_result} format_contents @
   (@var{$converter}, @var{$command_name}, @var{\%element}, @var{$filename})
@var{$command_name} is the @@-command name without leading @@, should be
@samp{contents}, @samp{shortcontents} or @samp{summarycontents}.
@var{\%element} is optional.  It corresponds to the @var{$command_name} Texinfo
tree element, but it is only set if @code{format_contents} is called from a
Texinfo tree element conversion, and not as a special element body formatting.
@var{$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 (@pxref{Converter General Information}),
and @code{command_contents_href} and @code{command_href}
(@pxref{Target Tree Element Link})
are used for links.  If @var{$filename} is unset, the current file name
is used, using @code{$converter->current_filename()}.

Return formatted table of contents or short table of contents.
@end deftypefn

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

To get id and link href of sectioning commands in table of contents
and short table of contents, use @code{command_contents_target} and
@code{command_contents_href}:

@deftypefun {@var{$target} =} @var{$converter}->command_contents_target @
    (@var{\%sectioning_element}, @var{$contents_or_shortcontents})
Returns the id for the location of @var{\%sectioning_element} sectioning
element in the table of contents, if @var{$contents_or_shortcontents} is
@samp{contents}, or in the short table of contents, if
@var{$contents_or_shortcontents} is set to @samp{shortcontents} or
@samp{summarycontents}.
@end deftypefun

@deftypefun {@var{$href} =} @var{$converter}->command_contents_href @
   (@var{\%sectioning_element}, @var{$contents_or_shortcontents}, @var{$source_filename})
Return string for linking to the @var{\%sectioning_element} sectioning element
location in the table of contents, if @var{$contents_or_shortcontents} is
@samp{contents} or in the short table of contents, if
@var{$contents_or_shortcontents} is set to @samp{shortcontents} or
@samp{summarycontents}.  @var{$source_filename} is the file the link comes
from. If not set, the current file name is used.
Returns @code{undef} if no string is found or the string is empty.
@end deftypefun


@node About Special Output Unit Customization
@section About Special Output Unit Customization

@cindex Customization of About special output unit
@cindex About special output unit, customizing

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

@vindex PROGRAM_NAME_IN_ABOUT
@code{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 @code{about} special output unit body
reference function may be overridden
(@pxref{Special Unit Body Formatting Functions}).


@node Special Unit Body Formatting Functions
@section 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
(@pxref{Output Units}), the special output units varieties are used, as
described in @ref{Special Units Varieties}.
Special element body formatting user defined functions are registered with
@code{texinfo_register_formatting_special_unit_body}:

@defun texinfo_register_formatting_special_unit_body ($special_unit_variety, @
                            \@ampchar{}handler)
@var{$special_unit_variety} is the element variety
(@pxref{Special Units Varieties}).  @var{\&handler} is the user defined
function reference.
@end defun

The call of the user defined functions is:
@deftypefn {Function Reference} @var{$text} special_unit_body (@var{$converter}, @
                                @var{$special_unit_variety}, @var{\%special_unit})
@var{$converter} is a converter object. @var{$special_unit_variety} is the
unit variety.  @var{\%special_unit} is the special output unit.

The @var{$text} returned is the formatted special output unit body.
@end deftypefn

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

@deftypefun {@var{\&special_unit_body_formatting} =} @var{$converter}->special_unit_body_formatting @
                                              (@var{$special_unit_variety})
@var{$special_unit_variety} is the special output unit variety.  Returns the
conversion function reference for @var{$variety}, or @samp{undef} if there is none,
which should not happen for the special output units described in this manual.
@end deftypefun

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

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

@deftypefun {@var{\&default_special_unit_body_formatting} =} @
               @var{$converter}->defaults_special_unit_body_formatting @
                                               (@var{$special_unit_variety})
@var{$special_unit_variety} is the special output unit variety.  Returns the
default conversion function reference for @var{$special_unit_variety}, or
@code{undef} if there is none, which should not happen for the special output units
described in this manual.
@end deftypefun

@xref{Customizing Footnotes} for more on footnotes
formatting.  @xref{Contents and Short Table of Contents Customization}
for more on the @code{contents} and @code{shortcontents} formatting.
@xref{About Special Output Unit Customization} for more on the @code{about}
special output unit body formatting.


@node Customizing HTML Footers@comma{} Headers and Navigation Panels
@chapter Customizing HTML Footers, Headers and Navigation Panels

@command{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;
@pxref{Headings,, Page Headings, texinfo, Texinfo}.)

In the event that your needs are not met by setting customization variables
(@pxref{Customization of Navigation and Headers,,, texinfo, Texinfo}) and
changing the navigation buttons using directions names
(@pxref{Simple Navigation Panel Customization}), you can use more advanced
navigation buttons formatting specifications.  You can also completely control
the formatting of navigation panels by redefining function references.
@xref{Registering and Getting 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.


@node Setting Global Directions From Document Information
@section Setting Global Directions From Document Information

@cindex Setting global directions node
@cindex Global direction, set from node name

Global directions may be added or modified before any conversion takes
place (@pxref{Adding Text And Global Output Units Directions}).  It is also
possible to associate a global output unit direction with a node name Texinfo
code using the converted document information, by registering a user-defined
function (@pxref{Init File Calling at Different Stages}) to call
@code{set_global_direction} on the converter at the @samp{setup} stage.  The
direction needs to be a default global direction, or to have been registered
previously, this function cannot be used to add a new direction, only to set
the association to a node.  It is not a real limitation, as a new direction
needs to be registered early such that associated direction strings can be set.

@defun @var{$converter}->set_global_direction ($direction, $texinfo_node_name)
@var{$direction} is a global direction (@pxref{Directions}),
@var{$texinfo_node_name} is an optional node name Texinfo code.
The @var{$direction} will point to the output unit associated to the
@var{$texinfo_node_name} node name, if set and the node exists in the
Texinfo document.
@end defun

For example, to associate the first @code{@@appendix} command to the
@samp{Appendix} direction by using section and node relations
(@pxref{Document Structure}):

@example
use Texinfo::Common;
use Texinfo::Convert::Texinfo;

texinfo_register_global_direction ('Appendix');

texinfo_register_direction_string_info (@dots{})
@dots{}

@group
sub _set_appendix_direction_node_name @{
  my ($self, $document, $stage) = @@_;

  my $sections_list = $document->sections_list();

  if (!defined($sections_list) or !scalar(@@@{$sections_list@})) @{
    return 0;
  @}

  foreach my $section_relations (@@@{$sections_list@}) @{
    my $section = $section_relations->@{'element'@};
    if ($section->@{'cmdname'@} eq 'appendix') @{
      if (exists($section_relations->@{'associated_node'@})) @{
        my $node_relations = $section_relations->@{'associated_node'@};
        my $node = $node_relations->@{'element'@};
        my $label_element = Texinfo::Common::get_label_element($node);
        if (defined($label_element)) @{
          my $node_name = Texinfo::Convert::Texinfo::convert_to_texinfo(
                         @{'contents' => $label_element->@{'contents'@}@});
          $self->set_global_direction('Appendix', $node_name);
        @}
      @}
      last;
    @}
  @}

  return 0;
@}
@end group

texinfo_register_handler('setup',
            \&_set_appendix_direction_node_name);
@end example


@node Advanced Navigation Panel Buttons Specification
@section Advanced Navigation Panel Buttons Specification

The button specification for simple headers customizations is a direction name
string (@pxref{Simple Navigation Panel Customization}).  This is not the only
way to specify how navigation panel buttons should be formatted.  Other
possibilities involve functions that may be specified for more control
other the buttons formatting.  The detailed description of the different
possibilities for the array item values is the following:

@anchor{Buttons Display}

@table @emph
@item string with a text direction
If icons are not used, button is the @code{text} direction string.
If icons are used, the button is an image whose file is determined by
the value associated with the output unit direction in the @code{ACTIVE_ICONS}
variable hash.  The button name is given as HTML attribute to have a textual
description of the icon.  The button name corresponds to the
@code{button} direction string in @emph{string} context.

@item 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 @code{text} direction string
(@pxref{Direction Strings}), surrounded by @samp{[} and
@samp{]}.

@vindex ACTIVE_ICONS
@vindex PASSIVE_ICONS
@cindex Icons, in navigation buttons
If icons are used, the button is an image whose file is determined by
the value associated with the output unit direction in the
@code{ACTIVE_ICONS} variable hash if the link leads to an output unit, or in the
@code{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 @code{button} direction string for the button name
and the @code{description} for a more detailed description (@pxref{Direction
Strings}).

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

@item array reference of length 2
Here, the first array item should be a an output unit direction,
and the second array item a reference to a function.
The function 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.

@end table

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


@node Navigation Panel Button Formatting
@section Navigation Panel Button Formatting

The function reference @code{format_button} does the formatting of
one button, corresponding, in general, to a link to a direction:

@anchor{@code{format_button}}
@deftypefn {Function Reference} @var{$formatted_button} format_button @
           (@var{$converter}, @var{$button}, @var{$source_command})
@var{$button} holds the specification of the button (@pxref{Buttons Display}).
@var{$source_command} is an optional argument, the @@-command the link comes from.

Returns the formatted result in @var{$formatted_button}.

The buttons images can be formatted with @code{format_button_icon_img}
(see below).

Simple navigation panel
customization (@pxref{Simple Navigation Panel Customization}),
@code{USE_ACCESSKEY} and direction strings
customization (@pxref{Direction Strings Customization})
can be relevant for the
formatting of a button.
@end deftypefn

@cindex Direction strings, getting

To get direction strings typically used for formatting of buttons or hyperrefs
leading to that direction, use @code{direction_string}:

@deftypefun {@var{$string} =} @var{$converter}->direction_string @
                    (@var{$direction}, @var{$string_type}, @var{$context})
Retrieve the @var{$direction} (@pxref{Directions}) string of type
@var{$string_type} (@pxref{Direction Strings}).  @var{$context} is
@samp{normal} or @samp{string}.  @xref{Init File Expansion Contexts}.  If
@var{$context} is @code{undef}, the @samp{normal} context is assumed.
The string will be translated if needed.  May return @code{undef}.
@end deftypefun

@cindex Global directions output units, getting

To get the Texinfo special output unit associated with
a special output unit direction, such as @samp{About} or @samp{Contents},
as well as output unit associated with other global directions, such as
@samp{Top} or @samp{Index}, use
use @code{global_direction_unit}:

@deftypefun {@var{\%output_unit} =} @var{$converter}->global_direction_unit (@var{$direction})
Return the output unit associated with direction @var{$direction}, or
@code{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.
@end deftypefun

@cindex Text directions, determining

To determine if a direction is a text direction (@pxref{Directions}),
use @code{global_direction_text}:
@deftypefun {@var{$is_text_direction} =} @var{$converter}->global_direction_text (@var{$direction})
Return 1 if direction @var{$direction} is a text direction not associated
with an output unit, such as the @samp{Space} direction.
@end deftypefun

To get link information for relative and global
directions, use @code{from_element_direction}:

@deftypefun {@var{$result} =} @var{$converter}->from_element_direction (@var{$direction}, @var{$type}, @
   @var{$source_element}, @var{$source_filename}, @var{$source_command})
Return a string for linking to @var{$direction}, or the information
to be used for a hyperlink to @var{$direction}, depending on @var{$type}.
@var{$source_element} is the output unit the link comes from. If not set,
the current output unit is used.  @var{$source_filename} is the file the
link comes from. If not set, the current file name is used.
@var{$source_command} is an optional argument, the @@-command the link comes
from. It is only used for messages.  The returned string is determined
dynamically depending on the current output, for instance on the output unit
whose navigation panel is being formatted.

@anchor{Output Unit Direction Information Type}
@cindex Direction information type
@cindex Type, of direction information

The possible values for @var{$type} are:
@table @code
@item href
A string that can be used as an href attribute linking to the output unit
corresponding to the direction.

@item string
A string representing the direction that can be used in
context where only entities are available (attributes).
@xref{Init File Expansion Contexts}.

@item text
A string representing the direction to be used in contexts
with HTML elements (preformatted and normal contexts).
@xref{Init File Expansion Contexts}.

@item node
Same as @code{text}, but selecting the node associated with the
output unit direction in priority.

@item section
Same as @code{text}, but selecting the sectioning command
associated with the output unit direction in priority.

@end table

@code{text}, @code{string} and @code{section} also have a variant with
@samp{_nonumber} prepended, such as @code{text_nonumber} without sectioning
command number in the representation.

@end deftypefun

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

@deftypefn {Function Reference} @var{$text} format_button_icon_img @
                  (@var{$converter}, @var{$button}, @var{$icon}, @var{$name})
@var{$button} is a button name, typically obtained from the @code{button}
direction string (@pxref{Direction Strings}).
@var{$icon} is an image file name to be used as icon.  @var{$name} is the
direction heading, typically formatted in string context.  @xref{Init File
Expansion Contexts}.

Returns a formatted icon image.
@end deftypefn

@xref{Directions} for the list of directions.


@node Navigation Panel and Navigation Header Formatting
@section Navigation Panel and Navigation Header Formatting

@c In the unusual case that this isn't enough, it is also possible to
@c redefine the function doing the navigation panel formatting.

@cindex Navigation panel formatting functions
@cindex Formatting functions, for navigation panel

The overall display of navigation panels is controlled via this
function reference, @code{format_navigation_header}:

@anchor{@code{format_navigation_header}}
@deftypefn {Function Reference} @var{$navigation_text} format_navigation_header @
   (@var{$converter}, @var{\@@buttons}, @var{$command_name}, @var{\%element})
@var{\@@buttons} is an array reference holding the specification of
the buttons for the navigation panel
(@pxref{Simple Navigation Panel Customization}). @var{\%element} is the
element in which the navigation header is formatted. @var{$command_name} is
the associated command (sectioning command or @code{@@node}).  It may be @code{undef}
for special output units.

Returns the formatted navigation header and panel. The navigation
panel itself can be formatted with a call to @code{format_navigation_panel}.

The customization variable @code{VERTICAL_HEAD_NAVIGATION} should be relevant
(@pxref{Customization of Navigation and Headers,,, texinfo, Texinfo}).
@end deftypefn

The navigation panel display is controlled via @code{format_navigation_panel}:

@deftypefn {Function Reference} @var{$navigation_text} format_navigation_panel @
  (@var{$converter}, @var{\@@buttons}, @var{$command_name}, @var{\%element}, @var{$vertical}, @var{$in_header})
@var{\@@buttons} is an array reference holding the specification of the buttons
for that navigation panel.   @var{\%element} is the element in which the
navigation header is formatted. @var{$command_name} is the associated command
(sectioning command or @code{@@node}).  It may be @code{undef} for special
elements.  @var{$vertical} is true if the navigation panel should be vertical.
@var{$in_header} is true if the navigation panel is for a header, not
for a footer.

Returns the formatted navigation panel in @var{$navigation_text}. The buttons
in the navigation panel can be formatted with a call to
@code{format_button} (@pxref{@code{format_button}}).
@end deftypefn


@node Element Header and Footer Formatting
@section Element Header and Footer Formatting

@cindex Customizing HTML page headers
@cindex Headers, customizing for HTML

By default, the function associated with @code{format_element_header}
formats the header and navigation panel of an output unit.

@deftypefn {Function Reference} @var{$formatted_header} format_element_header @
    (@var{$converter}, @var{$command_name}, @var{\%element}, @var{\%output_unit})
@var{\%element} is the element in which the navigation header is formatted
(sectioning command, @code{@@node} or special output unit). @var{$command_name} is
the associated command name.  It may be @code{undef} for special output units.
@var{\%output_unit} is the associated output unit (@pxref{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
(@pxref{Simple Navigation Panel Customization}).  The navigation header can
then be formatted with a call to @code{format_navigation_header}
(@pxref{@code{format_navigation_header}}).  It is also
possible to format directly the navigation panel, depending on customization
variables values and location in file.
@end deftypefn

Similarly, the function associated with @code{format_element_footer}
formats the footer and navigation panel of a output unit.

@deftypefn {Function Reference} @var{$formatted_footer} format_element_footer @
   (@var{$converter}, @var{$output_unit_type}, @var{\%output_unit}, @
    @var{$content}, @var{$command})
@var{\%output_unit} is the output unit in which the
navigation footer is formatted.  @var{$output_unit_type} is the associated type.
@var{$content} is the formatted element content.  @var{$content} can be
@code{undef}. @var{$command} is an optional argument, the @@-command
associated with the @var{\%output_unit}.

Returns the formatted navigation footer and panel.

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

Many customization variables have an effect on the footer
formatting, such as @code{SPLIT} (@pxref{HTML Splitting,,, texinfo, Texinfo}),
customization variables used for the customization of headers such
as @code{HEADERS} or @code{WORDS_IN_PAGE}
(@pxref{Customization of Navigation and Headers,,, texinfo, Texinfo})
and customization variables setting inserted HTML code such as
@code{DEFAULT_RULE} (@pxref{Customization of HTML Code Inserted,,, texinfo,
Texinfo}).
@end deftypefn

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 @code{unit_is_top_output_unit}:

@deftypefun {@var{$is_top_output_unit} =} @var{$converter}->unit_is_top_output_unit (@var{\%output_unit})
Returns true if the @var{\%output_unit} output unit is the Top output unit
(@pxref{Output Units}) and is either associated with the
@code{@@top} sectioning command or with the @code{Top} @code{@@node}.
@end deftypefun


@node Element Counters in Files
@section 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
@code{count_elements_in_filename}:

@deftypefun {@var{$count} =} @var{$converter}->count_elements_in_filename @
                                     (@var{$specification}, @var{$file_name})
Return output unit counter for @var{$file_name}, or @code{undef} if
the counter does not exist.  The counter returned depends on @var{$specification}:

@table @emph
@item current
Return the number of output units associated with @var{$file_name}
having already been processed.
@item remaining
Return the number of output units associated with @var{$file_name}
that remains to be processed.
@item total
Return the total number of output units associated with the file.
@end table
@end deftypefun

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


@node Beginning and Ending Files
@chapter 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.

@xref{Registering and Getting Specific Formating Functions} for information on how to
register and get the functions references.


@node Customizing HTML File Beginning
@section Customizing HTML File Beginning

@c The following information is also in the HTML Customization
@c variables dicumentation in the Texinfo manual.  We keep it here too,
@c as the organization is different, here the customization variables
@c are grouped together because they appear at the file beginning.

@vindex DOCTYPE
You can set the variable @code{DOCTYPE} to replace the default.
The @code{DOCTYPE} is output at the very beginning of each output
file.

@vindex EXTRA_HEAD
@vindex AFTER_BODY_OPEN
@cindex @code{<head>} block, adding to
You can define the variable @code{EXTRA_HEAD} to add text within the
@code{<head>} HTML element.  Similarly, the value of
@code{AFTER_BODY_OPEN} is added just after @code{<body>} is output.
These variables are empty by default.

@c @vindex BODY_ELEMENT_ATTRIBUTES@r{, in customization}
@vindex BODY_ELEMENT_ATTRIBUTES
@cindex @code{<body>} tag, attributes of
The @code{<body>} element attributes may be set by defining the
customization variable @code{BODY_ELEMENT_ATTRIBUTES}.

@vindex OUTPUT_ENCODING_NAME
@cindex Encoding, in HTML output
By default, the encoding name from @code{OUTPUT_ENCODING_NAME} is used.  If
this variable is not defined, it is automatically determined.

@vindex DATE_IN_HEADER
@cindex Date, in header
A date is output in the header if @code{DATE_IN_HEADER} is set.

@cindex Document description, in HTML output
The description from @code{@@documentdescription} (or a value set as a
customization variable) is used in the header
(@pxref{@code{@@documentdescription},,, texinfo, Texinfo}).

@vindex USE_LINKS
@vindex LINKS_DIRECTIONS
@code{<link>} elements are used in the header if @code{USE_LINKS} is
set, in which case the @code{LINKS_DIRECTIONS} customization variable
array determines which links are used and the @code{rel} direction string
(@pxref{Direction Strings}) determines the link type associated with the
@code{rel} attribute.  @xref{Navigation Panel Button Formatting}.

@vindex HTML_ROOT_ELEMENT_ATTRIBUTES
You can set @code{HTML_ROOT_ELEMENT_ATTRIBUTES} to add attributes to
the @code{<html>} element.

@vindex SECTION_NAME_IN_TITLE
If @code{SECTION_NAME_IN_TITLE} is set, the sectioning command argument
is used in the @code{<title>} HTML element instead of the @code{@@node}
argument.

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

@deftypefn {Function Reference} @var{$file_begin} format_begin_file @
               (@var{$converter}, @var{$filename}, @var{\%output_unit})
@cindex @code{<body>} tag, outputting
@var{$filename} is the name of the file output.
@var{\%output_unit} is the first output unit of the file.
This function should print the page header, in HTML,
including the @code{<body>} element.
@end deftypefn


@node Customizing HTML File End
@section Customizing HTML File End

@cindex Customizing HTML page footers
@cindex Footer, customizing for HTML

@vindex PRE_BODY_CLOSE
@vindex PROGRAM_NAME_IN_FOOTER
You can define the variable @code{PRE_BODY_CLOSE} to add text just
before the HTML @code{</body>} element.  Nothing is added by default.
If @code{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 (@pxref{JavaScript Interface and Licenses,,, texinfo,
Texinfo}).

The @code{format_end_file} function reference give full control over the page
footer formatting done at the bottom of each HTML output file.

@deftypefn {Function Reference} @var{$file_end} format_end_file @
                 (@var{$converter}, @var{$filename}, @var{\%output_unit})
@var{$filename} is the name of the file output.
@var{\%output_unit} is the last output unit of the file.
@cindex @code{</body>} tag, outputting
This function should print the page footer, including
the @code{</body>} element.
@end deftypefn


@node Associating Information to an Output File
@section 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, @code{register_file_information} can be
used to associate integer information, and @code{get_file_information} to
retrieve that information.

@defun @var{$converter}->register_file_information ($key, $value)
Associate the current output file name file to the key @var{$key}, itself
associated with the integer value @var{$value}.
@end defun

@deftypefun {@var{$value} =} @var{$converter}->get_file_information (@var{$key}, @var{$file_name})
Return the value associated with the key @var{$key} and file name
@var{$file_name}.
@end deftypefun

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


@node Titlepage@comma{} CSS and Redirection Files
@chapter Titlepage, CSS and Redirection Files

@node HTML Title Page Customization
@section HTML Title Page Customization

@cindex Title page, customization

@vindex SHOW_TITLE
@vindex NO_TOP_NODE_OUTPUT
@vindex USE_TITLEPAGE_FOR_TITLE
If @code{SHOW_TITLE} is not set, no title is output.  @code{SHOW_TITLE} is
@samp{undef} in the default case.  If @samp{undef}, @code{SHOW_TITLE} is set if
@code{NO_TOP_NODE_OUTPUT} is set.  The ``title page'' is used to format the
HTML title if @code{USE_TITLEPAGE_FOR_TITLE} is set, otherwise the
@code{simpletitle} is used.  @code{USE_TITLEPAGE_FOR_TITLE} is set in the
default case.  @xref{HTML Output Structure Customization,,, texinfo, Texinfo}.

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

@deftypefn {Function Reference} @var{$title_titlepage} format_title_titlepage (@var{$converter})
Returns the formatted title or ``title page'' text.

In the default case, return nothing if @code{SHOW_TITLE} is not set, return the
output of @code{format_titlepage} if @code{USE_TITLEPAGE_FOR_TITLE} is set, and
otherwise output a simple title based on @code{simpletitle}.
@end deftypefn

@deftypefn {Function Reference} @var{$title_page} format_titlepage (@var{$converter})
Returns the formatted ``title page'' text.

In the default case, the title page formatting uses, in order:
@table @code
@item @@titlepage
If found in global information.
@item @@maketitle
If @code{@@maketitle} is found in global information, @code{@@documentinfo}
content is used (through
@code{Texinfo::Convert::Utils::get_document_documentinfo}).
@item simpletitle
@xref{Converter General Information}.
@end table
@end deftypefn

You can use the @code{get_document_documentinfo} function to
get @code{@@documentinfo} information:
@deftypefun {@var{\%documentinfo_info} =} Texinfo::Convert::Utils::get_document_documentinfo @
  (@var{$converter}, @var{$document})
@var{$document} is a Texinfo parsed document.  If @code{@@documentinfo} is
found in the document, return an hash reference with @@-command names appearing
in @code{@@documentinfo} as keys associated to an array reference as value
containing the @@-commands Texinfo tree elements.  Otherwise, returns
@code{undef}.

@end deftypefun

@node CSS Customization
@section CSS Customization

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


@node Customization of CSS Rules Imports and Selectors
@subsection Customization of CSS Rules, Imports and Selectors

@cindex Customizing CSS @subentry Rules
@cindex Customizing CSS @subentry Imports
@cindex Customizing CSS @subentry Selectors
@cindex CSS customization

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 @option{--css-include=@var{file}} files, as
described in @ref{HTML CSS,,, texinfo, 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, @code{@var{element}.@var{class}}
strings with @var{element} an HTML element and @var{class} an attribute class
associated with that element.

The functions can only be used on a converter, from
functions registered and called with a converter.
The functions used are @code{css_get_info} and @code{css_get_selector_style}
to get information and @code{css_add_info} and @code{css_set_selector_style}
to modify:

@defun @var{$converter}->css_get_info ($specification)
@defunx @var{$converter}->css_add_info ($specification, $css_info)

With @code{css_get_info}, the returned information depends on @var{$specification}.
Use @code{'rules'} to get the CSS rules lines array reference, use
@code{'imports'} to get the CSS import lines array reference.
Use any other value to get the list of HTML elements and
class attributes selectors.

With @code{css_add_info}, @var{$css_info} is an additional entry added to CSS
rules lines if @var{$specification} is set to @code{'rules'} or an additional
entry added to CSS import lines if @var{$specification} is set to
@code{'imports'}.

@end defun

@defun @var{$converter}->css_get_selector_style ($selector)
@defunx @var{$converter}->css_set_selector_style ($selector, $css_style)
@code{css_get_selector_style} returns the CSS style corresponding to the HTML
element and class attribute selector @var{$selector}, or @code{undef} if not
found.

With @code{css_set_selector_style}, the style rule associated to the
@var{$selector} CSS rule selector is set to @var{$css_style}.  If
@var{$css_style} is @code{undef}, @var{$selector} is removed from the list of
selectors with associated style.
@end defun


Some examples of use:

@example
my $all_included_rules = $converter->css_get_info('rules');
foreach my $rule (@@$all_included_rules) @{...@}

my $all_default_selectors = $converter->css_get_info('styles');
my $titlefont_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");
@end example

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
HTML output file. @xref{Customizing the CSS Lines}.

The simplest way to modify CSS rules would be to use a function
registered for the @samp{structure} stage:

@example
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);
@end example


@node Customizing the CSS Lines
@subsection Customizing the CSS Lines

@cindex Customizing CSS @subentry Lines output
@cindex CSS customization

The CSS @var{element}.@var{class} that appeared in a file, gathered through
@code{html_attribute_class} calls (@pxref{Formatting HTML Element with
Classes}) are available through the @code{html_get_css_elements_classes}
function:

@deftypefun {@var{\@@css_element_classes} =} @var{$converter}->html_get_css_elements_classes @
    (@var{$file_name})
Returns a reference on an array containing @code{element.class} pairs of elements
and classes appearing in @var{$file_name}.
@end deftypefun

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

@deftypefn {Function Reference} @var{$css_lines} format_css_lines @
    (@var{$converter}, @var{$file_name})
This function returns the CSS lines and @code{<script>} HTML element
for @var{$file_name}.

In the default case, the function reference uses @code{CSS_REFS} corresponding
to command-line @option{--css-ref}, @code{html_get_css_elements_classes},
@code{css_get_info} and @code{css_element_class_rule}
(@pxref{Customization of CSS Rules Imports and Selectors}) to determine the
CSS lines.
@end deftypefn


@node Customizing Node Redirection Pages
@section Customizing Node Redirection Pages

Node redirection pages are output if @code{NODE_FILES} is set (@pxref{Invoking
@command{texi2any},,, texinfo, Texinfo}).

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

@deftypefn {Function Reference} @var{$node_redirection_file_content} @
   format_node_redirection_page (@var{$converter}, @var{\%element})
@var{\%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 (@pxref{HTML Xref,,, texinfo, Texinfo}).

Returns the content of the node redirection file.
@end deftypefn


@node Specific Functions for Specific Elements
@chapter Specific Functions for Specific Elements

This chapter describes functions and data that you can use to format
Texinfo tree elements in user-defined conversion functions registered to be
called by the converter.  They are used in the default HTML formatting
functions.

@xref{Command Tree Element Conversion} for functions that should be
called for formatting.

For @@-commands accepting only a simple textual argument, such as
@code{@@enumerate} or @code{@@U}, you can get the @@-command argument without
leading and trailing spaces with @code{Texinfo::Common::simple_arg_text}:

@deftypefun {(@var{$arg}, @var{$surplus}) =} Texinfo::Common::simple_arg_text (@var{$element})
The @var{$element} Texinfo tree element should be an @@-command argument.
Returns the argument as string in @var{$arg}, an empty string if the argument
is empty or @code{undef} for an unexpected argument (such as an @@-command).
Set @var{$surplus} to a true value if an unexpected content follows the textual
argument (such as an @@-command).
@end deftypefun

You can get the information that an @@-command argument is empty except
maybe for leading spaces, trailing space and comments by calling
@code{Texinfo::Common::empty_spaces_argument}:

@deftypefun {@var{$is_empty} =} Texinfo::Common::empty_spaces_argument (@var{$element})
The @var{$element} Texinfo tree element should be an @@-command argument.
Returns a true value if the @var{$element} contains only ignorable
leading or trailing spaces or comments.
@end deftypefun

The @code{Texinfo::Convert::NodeNameNormalization} converter, used
for normalization of labels, defines functions that can be used on Texinfo
elements trees to obtain strings that are unique and can be used in attributes:

@deftypefun {@var{$normalized} =} convert_to_identifier (@var{$element})
@deftypefunx {@var{$normalized} =} convert_to_node_identifier (@var{$element})
@deftypefunx {@var{$normalized} =} normalize_transliterate_texinfo (@var{$element})
@deftypefunx {@var{$partially_normalized} =} convert_to_normalized (@var{$element})

Texinfo tree @var{$element} is returned as a
string, normalized as described in @ref{HTML Xref,,, texinfo, Texinfo}.
@code{convert_to_identifier} leaves out the normalization of the name if it
is a @samp{Top} node name.

@code{normalize_transliterate_texinfo} transliterates non-ASCII letters as
ASCII, but is otherwise similar to @code{convert_to_identifier}.

With @code{convert_to_normalized}, ASCII 7-bit characters other than spaces and
non-ASCII characters are left as is in the resulting string instead of
being changed to hexadecimal strings representations.
@end deftypefun


@node Commands Without Arguments Formatting
@section Commands Without Arguments Formatting

The information on commands without arguments formatting obtained from defaults
and customization (@pxref{Simple Customization for Commands Without Arguments})
can be accessed through the @samp{no_arg_commands_formatting} key of the
converter.  The value is a hash, with command name keys (without @@).  The
value associated to a command name is also a hash with the following
keys corresponding to expansion contexts (@pxref{Init File Expansion Contexts}):

@table @code
@item normal
Formatting for the normal context.

@item preformatted
Formatting for the code, preformatted and math context.

@item string
Formatting for the string context.

@end table

The value associated is also a hash, with the following
keys:

@table @code
@item text
HTML text, possibly with elements (not in the string expansion context) corresponding
to the @@-command.  Can be directly specified or obtained through translation,
and also possibly through translation and conversion.

@item element
HTML element.  Directly specified.
@end table

for example, for the @code{@@equiv} command in preformatted context:
@example
@group
if ($converter->in_preformatted_context() or $converter->in_math()) @{
  my $specification
   = $converter->@{'no_arg_commands_formatting'@}->@{'equiv'@}
                                             ->@{'preformatted'@};
  my $text = '';
  if (exists($specification->@{'text'@})) @{
    $text = $specification->@{'text'@};
  @}
  if (exists($specification->@{'element'@})) @{
    return '<'.$specification->@{'element'@}.'>'
       . $text . '</'.$specification->@{'element'@}.'>';
  @} else @{
    return $text;
  @}
@}
@end group
@end example

@cindex @code{@@today} formatting
@code{@@today} is formatted differently, using @code{expand_today}
generic converter method and converting the resulting tree.

@deftypefun {@var{$tree} =} @var{$converter}->expand_today()
Expand today's date, as a Texinfo tree with translations.
@end deftypefun


@node Simple Commands with Braces Formatting
@section Simple Commands with Braces Formatting

The information on commands without arguments formatting obtained from defaults
and customization (@pxref{Simple Output Customization for Simple Commands with Braces})
can be accessed through the @samp{style_commands_formatting} key of the
converter.  The value is a hash, with command name keys (without @@).  The
value associated to a command name is also a hash with the following
keys corresponding to expansion contexts (@pxref{Init File Expansion Contexts}):

@table @code
@item normal
Formatting for the normal context.

@item preformatted
Formatting for the code, preformatted and math context.
@end table

The value associated is also a hash, with the following
keys:

@table @code
@item element
HTML element.

@item quote
Set if the argument is expected to be in quotes.
@end table


@node Accent Commands with Arguments Formatting
@section Accent Commands with Arguments Formatting

In the default case, accent commands with arguments are formatted using
a generic conversion fonction defined by the converter,
@code{convert_accents}.  This function does not do all the work, it
presents the nested accents, removing the need to go through the tree
but still requires a function used to convert the presented accents.

@deftypefun {@var{$result} =} @var{$converter}->convert_accents(@var{$accent_command}, @
 @var{\&format_accents}, @var{$output_encoded_characters}, @var{$in_upper_case})
@var{$accent_command} is an accent command tree elements, which may have other
accent commands tree elements nested inside.  The function returns the accents
formatted either as encoded letters if @var{$output_encoded_characters} is set,
or formatted by calling @var{\&format_accents} repeatedly starting from the
innermost accent command tree element within @var{$accent_command}.  The
innermost accent command argument (usually a letter), is also converted, by
calling @code{convert_tree}. If @var{$in_upper_case} is set, the result should
be uppercased.
@end deftypefun

The @var{\&format_accents} function is called by @code{convert_accents} like:

@deftypefn {Function Reference} @var{$text} format_accents (@var{$converter}, @
 @var{$text}, @var{$command}, @var{$index_in_stack}, @var{$accents_stack}, @
 @var{$in_upper_case})
@var{$converter} is the converter in the call to @code{convert_accents}.
For the innermost accent command, @var{$text} is the text appearing within
the accent command converted.  For the other accent commands,
@var{$text} is the result of the previously converted
accent command.  @var{$accent_command} the Texinfo tree element corresponding
to the accent command being converted.  @var{$index_in_stack} is the position
in the @var{$accents_stack} of the accent command being converted.  The
@var{$accents_stack} is an array holding the nested accent command
Texinfo tree elements.  The innermost tree element command is last.
@var{$in_upper_case} is optional, and, if set, the text should be put
in upper case.  The function should return the converted accent argument
to be processed by the following accent command.
@end deftypefn

You can use @code{xml_numeric_entity_accent} to format an accent command
as a numeric entity:

@deftypefun {@var{$result} =} Texinfo::Convert::Converter::xml_numeric_entity_accent @
 (@var{$accent_command_name}, @var{$text})
@var{$accent_command_name} is the name of an accent command.  @var{$text} is
the text appearing within the accent command.  Returns the accented letter as
XML numeric entity, or @code{undef} if there is no such entity.
@end deftypefun

You can also use the following variable, used in the formatting in the default
case:

@defvar %Texinfo::UnicodeData::unicode_accented_letters
Associates Texinfo
accent command names to a hash reference with letters as keys and
the accented character unicode codepoint strings (in hexadecimal) as value.
@end defvar


@node Specific Formatting for Indices
@section Specific Formatting for Indices

Index formatting customization is achieved through registering a conversion
function for @code{@@printindex} (@pxref{Command Tree Element Conversion
Functions}).  The Texinfo parsed document indices information directly
obtained from the Texinfo manual parsing is available in document information
(@pxref{@code{indices_information}}).  Sorted index entries, which are
usually used for index formatting are available through
@code{get_converter_indices_sorted_by_letter}:

@deftypefun {@var{\%sorted_index_entries} = } @var{$converter}->get_converter_indices_sorted_by_letter ()
Returns an hash reference holding index entries sorted by index and letter
for each of the indices.  The keys are index names, the values are
array reference of letter hash references.   Each letter hash reference has two
keys, a @code{letter} key with the letter, and an @code{entries} key with an
array reference of sorted index entries beginning with the letter.

This function should be called each time sorted indices are needed,
in case the sorting depends on the @code{@@documentlanguage} value.
@end deftypefun

The index entry information hash reference available from
@code{indices_information} @code{index_entries} or letter @code{entries}
has the following keys:

@table @code
@item index_name
The index name associated to the command.  Not modified if the corresponding
index is merged in another index (with @code{@@synindex}, for example).

@item entry_element
The Texinfo tree element associated with the @@-command holding the
index entry.

@item entry_number
The number of the index entry in the index.
@end table

You can also use helper functions to collect or prepare index entries,
@code{@@subentry}, @code{@@seeenentry} and @code{@@seealso}:

@deftypefun {@var{$entry_content_element} =} Texinfo::Common::index_content_element @
  (@var{$element}, @var{$prefer_reference_element})
Return a Texinfo tree element corresponding to the content of the index
entry associated to @var{$element}.  If @var{$prefer_reference_element} is set,
prefer an untranslated element.  If the element is an index command like
@code{@@cindex} or an @code{@@ftable} @code{@@item}, the content element is the
argument of the command.  If the element is a definition line, the index entry
element content is based on the name and class.
@end deftypefun

@deftypefun {(@var{$text}, @var{$command}) =} Texinfo::Indices::index_entry_first_letter_text_or_command (@var{$index_entry})
Return the @var{$index_entry} leading text @var{$text} or textual command
Texinfo tree hash reference @var{$command}.  Here textual commands means accent
commands, brace commands without arguments used for character and glyph
insertion and @code{@@U}.

This method can in particular be used to format the leading letter
of an index entry using @var{$command} instead of using the sort string letters
returned by @code{get_converter_indices_sorted_by_letter}.
@end deftypefun

@deftypefun {@var{$referred_element} =} Texinfo::Common::index_entry_referred_entry @
     (@var{$element}, @var{$cmdname})
Return the tree element of @var{$cmdname}, which should be set to
@samp{seeenentry} or @samp{seealso} in index command (or @code{@@subentry})
tree element @var{$element}, recursing into @code{@@subentry}.  Returns
@code{undef} if not found.
@end deftypefun

@defun Texinfo::Common::collect_subentries (@var{$element}, @var{\@@subentries})
Collect @code{@@subentry} within @var{$element} (an index entry or a
@code{@@subentry}) recursively in @var{\@@subentries}.
@end defun

@deftypefun {@var{$contents_element} =} Texinfo::Convert::Utils::comma_index_subentries_tree @
  (@var{$entry}, @var{$separator})
@var{$entry} is a Texinfo index entry tree element. The function sets up an
array with the @var{$entry} @code{@@subentry} contents. The result is returned
as contents in the @var{$contents_element} tree element.  @code{undef} is
returned is there is no such content. @var{$separator} is an optional separator
argument used, if given, instead of the default: a comma followed by a space.
@end deftypefun


@node Image Formatting
@section Image Formatting

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

@deftypefun {(@var{$image_file}, @var{$image_basefile}, @var{$image_extension}, @var{$image_path}, @var{$image_path_encoding}) =} @
 @var{$converter}->html_image_file_location_name (@var{$command_name}, @var{\%element}, @var{\@@args})
@var{$command_name}, @var{\%element} and @var{\@@args} should be the arguments
of an @code{@@image} @@-command formatting (@pxref{Command Tree Element
Conversion Functions}).

The return values gives information on the image file if found, or fallback values.
@var{$image_file} is the relative image file name.  It is the file name used in
formatting of the @code{@@image} command in the default case.  @var{$image_basefile}
is the base file name of the image, without extension, corresponding to the
@code{@@image} @@-command first argument.  @var{$image_extension} is the image
file extension (without a leading dot).  @var{$image_path} is the path to the
actual image file, @code{undef} if no file was found.  @var{$image_path} is
returned as a binary string, the other strings returned are character strings.
@var{$image_path_encoding} is the encoding used to encode the image path to a
binary string.
@end deftypefun


@node @code{@@verbatiminclude} Formatting
@section @code{@@verbatiminclude} Formatting

In the default case, an helper function provided by the generic converter is
used to read @code{@@verbatiminclude} argument file content and provide with a
tree element, that could then be converted:

@deftypefun {@var{$tree} =} @var{$converter}->expand_verbatiminclude(@var{$verbatiminclude})
@var{$verbatiminclude} is a @code{@@verbatiminclude} tree element.  This
function returns a @code{@@verbatim} tree elements containing the included
file content after finding and reading the @code{@@verbatiminclude}
file argument.
@end deftypefun


@node Definition Commands Formatting
@section Definition Commands Formatting

In the default case, information on definition commands such as
@code{@@deffun} as well as helper functions that gather information
from the @@-command Texinfo tree element are used:

@deftypefun {(@var{$category}, @var{$class}, @var{$type}, @var{$name}, @var{$arguments}) =} @
  Texinfo::Convert::Utils::definition_arguments_content (@var{$def})
@var{$def} should be a @code{@@def*} Texinfo tree element. The @var{$category},
@var{$class}, @var{$type}, @var{$name} are tree elements corresponding to the
definition @@-command line. Texinfo elements on the @-command line
corresponding to arguments in the function definition are returned in the
@var{$arguments} tree element. Arguments correspond to text following the other
elements on the @@-command line. If there is no argument, @var{$arguments} will
be @code{undef}.
@end deftypefun

@deftypefun {@var{$tree} =} Texinfo::Convert::Utils::definition_category_tree (@var{$def_line}, undef, undef, @var{$converter})
@var{$def_line} is a @code{def_line} Texinfo tree container. This function
returns a Texinfo tree corresponding to the category of the @var{$def_line}
taking the class into account, if there is one.  @var{$converter} is the
HTML converter, the arguments with @code{undef} as value in the function call
are obtained from the @var{$converter}.
@end deftypefun

@defvar %Texinfo::Common::def_aliases
Associates an aliased command to the original command, for
example @code{defun} is associated to @code{deffn}.
@end defvar

@defvar %Texinfo::Common::def_no_var_arg_commands
Associates a definition command name with a true value if the argument on the
definition command line can contain non-metasyntactic variables. For instance,
it is true for @code{deftypevr} but false for @code{defun}, since
@code{@@defun} argument is supposed to contain metasyntactic variables only.
@end defvar


@node Float and List of Floats Formatting
@section Float and List of Floats Formatting

@deftypefun {(@var{$caption}, @var{$prependend}) =} @var{$converter}->float_name_caption (@var{$float})
@var{$float} is a Texinfo tree @code{@@float} element. This function returns
the caption tree element that should be used for the float formatting and the
@var{$prepended} Texinfo tree combining the type and label of the float.
@end deftypefun

@deftypefun {(@var{$caption}, @var{$shortcaption}) =} Texinfo::Common::find_float_caption_shortcaption (@var{$float})
Returns the @var{$caption} and @var{$shortcaption} tree elements associated
to the @var{$float} tree element if present, or @code{undef}.
@end deftypefun


@node Block Commands with @code{@@item}
@section Block Commands with @code{@@item}

You can call @code{table_item_content_tree} to apply the block command
@@-command argument to an @code{@@item} or @code{@@itemx}:

@deftypefun {@var{$table_item_tree} =} @var{$converter}->table_item_content_tree (@var{$element})
@var{$element} should be an @code{@@item} or @code{@@itemx} tree element.
Returns a tree in which the @-command in argument of @code{@@*table}
of the @var{$element} has been applied to the @var{$element} line argument,
or @code{undef}.

For example, with the following Texinfo code:
@example
@@table @@code
@@item first
...
@@end table
@end example
@code{table_item_content_tree} applied to the first table item returns the
Texinfo tree corresponding to @code{@@code@{first@}}.
@end deftypefun

@code{@@itemize} normally have an @@-command as argument, but can also have
some text or no argument at all.  You can call helper functions to simplify
the handling of the @code{@@itemize} argument.  In general, the
@code{@@itemize} argument is obtained from the @var{$itemize} @code{@@itemize}
Texinfo tree element with:

@example
my $arguments_line = $itemize->@{'contents'@}->[0];
my $element = $arguments_line->@{'contents'@}->[0];
@end example

@code{Texinfo::Common::itemize_line_prepended_element} returns a tree
element representing the argument that can be prepended to
@code{@@itemize} @code{@@item}:

@deftypefun {@var{$prepended_element} =} Texinfo::Common::itemize_line_prepended_element (@var{\%element})
@var{\%element} is the @code{@@itemize} argument.  If the argument
is an @-command or some non-empty text, it is returned, otherwise the
default @code{@@itemize} argument @@-command is returned as a Texinfo tree
element.
@end deftypefun

If the argument of @code{@@itemize} is some Texinfo code,
@code{html_convert_css_string_for_list_mark} can be used to convert that
argument to text usable in CSS style specifications.

@deftypefun {@var{$text_for_css} =} @var{$converter}->html_convert_css_string_for_list_mark @
             (@var{\%element}, @var{$explanation})
@var{\%element} is the Texinfo element that is converted to CSS text.
@var{$explanation} is an optional string describing what is
being done that can be useful for debugging.

Returns @var{\%element} formatted as text suitable for CSS.
@end deftypefun

A multitable @@-commant columnfractions tree element is returned
by @code{Texinfo::Common::multitable_columnfractions}:

@deftypefun {@var{$columnfractions_element} =} Texinfo::Common::multitable_columnfractions (@var{$multitable})
@var{$multitable} is a multitable @@-command tree element.  Returns the
associated columnfractions @@-command tree element if it exists, @code{undef}
otherwise.
@end deftypefun


@node Informative Commands
@section Informative Commands

Informative @@-commands with a textual argument (or without argument) are
considered customization variables to unify their handling, whether
they come from the command-line, initialization files or from the Texinfo
document (@pxref{Customization Variables for @@-Commands,,, texinfo, Texinfo}).

The @code{Texinfo::Common::set_informative_command_value} function sets
the value of the customization variable associated to an @@-command to
the @@-command argument:

@deftypefun {@var{$status} =} Texinfo::Common::set_informative_command_value (@var{$converter}, @var{$element})
Set the Texinfo customization variable corresponding to the tree element
@var{$element}.  The command associated to the tree element should be a command
that sets some information, such as @code{@@documentlanguage},
@code{@@contents} or @code{@@footnotestyle}.  Returns true if the
command argument was found and the customization variable was set.
@end deftypefun

@xref{Conversion Customization Variables} for more
on customization variables in conversion.


@node Functions Index
@appendix Functions Index

@printindex fn


@node Variables Index
@appendix Variables Index

@printindex vr


@node General Index
@appendix General Index

@printindex cp


@bye