\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-2024 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.  @c You can also add new variables.

The customization variables also valid in the main program out of the HTML
converter are handled differently if their associated values are strings or
arrays.  Conversely, customization variables only relevant for the conversion
phase set in the main program are always set by associating a string, an array
reference or a hash references to customization variables in the same way.

This section describes customization variables set in the main program.  These
variables are in general passed to converters.  It is also possible to set
customization variables in the converters only, not in the main program.
This is explained later on (@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}:

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

For example:

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


@ignore
@c problematic for XS, need a type, to add dynamically...
@node Adding Customization Variables
@subsection Adding Customization Variables

@cindex Customization variables, adding

Trying to set a customization variable that is not known as a valid
customization variable in @command{texi2any} is an error.  It is possible, however,
to add new customization variables from init files.  To add a customization
variable, call @code{texinfo_add_valid_customization_option}:

@defun texinfo_add_valid_customization_option ($variable_name)
@var{$variable_name} is added as a valid customization variable name.
@end defun

The variable value, if set, should also be available in the converters and therefore
in the init file functions registered and called from the converters.
@end ignore

@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@{@}}.

To change the formatting of a command, the functions is
@code{texinfo_register_no_arg_command_formatting}:

@defun texinfo_register_no_arg_command_formatting ($command_name, @
    $context, $text, $html_element, $translated_string_converted, @
    $translated_string_to_convert)
@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 context, @samp{preformatted} should be used
for math context. @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.  If
@var{$translated_string_to_convert} is set, the corresponding
text is translated when the document language changes and converted from
Texinfo code to HTML.  Since the conversion is done in the appropriate
context, @var{$translated_string_to_convert} should only be set for the
@samp{normal} context. @xref{Texinfo::Translations
METHODS,,,texi2any_internals}.
@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.

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
texinfo_register_no_arg_command_formatting('enddots',
                                           'normal', '...', 'small');
texinfo_register_no_arg_command_formatting('enddots',
                                           'preformatted', '...');
@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
texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
                                           'error--&gt;');
@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 context of the translation, call
@example
texinfo_register_no_arg_command_formatting('equiv', undef, undef, undef,
                                 undef, 'is the @@strong@{same@} as');
@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 output produced by ``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}) with @code{texinfo_register_style_command_formatting}:

@defun texinfo_register_style_command_formatting ($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 context, @samp{preformatted} should be used
for math context. @xref{Init File Expansion Contexts}.  There is no string
context either, as in string context simple formatting without the need
for per command information should be sufficient.  If @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{$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}).

If @var{$html_element} is undefined and @var{$in_quotes} is not set,
the formatted argument is output as is.
@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', 0,
                                          'normal');
texinfo_register_style_command_formatting('sansserif', 'code', 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,
                                             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}).  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.}.

The function used is @code{texinfo_register_type_format_info}:

@defun texinfo_register_type_format_info ($type, $code_type, $pre_class_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}. 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_format_info('menu_comment', 1, '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 directions 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}).

@c FIXME check if the links are to output units only or also to elements
@c such as sections or nodes
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 global output units directions:

@table @emph
@item @samp{@ }
An empty button.

@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
The first 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 Output Unit Direction Information Type
@subsection Output Unit Direction Information Type

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

@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} and @code{string} also have a variant with
@samp{_nonumber} prepended, such as @code{text_nonumber} without sectioning
command number in the representation.


@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
@section 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 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 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

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

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

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

@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 LINKS_BUTTONS
Used for @code{<link>} elements if they are output in the HTML @code{<head>}.

@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

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

@anchor{Buttons Display}

@table @emph
@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{]}. If the direction is @samp{ }, the @samp{[} and @samp{]}
are omitted.

@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 scalar reference
The scalar value is printed.

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

@table @emph
@item reference to a text string
A link to the output unit associated with the output unit direction
is generated with the corresponding text used for the text link.

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

@c This buttons specification is not used anywhere in code nor
@c tests, it is certainly not worth maintaining in the long run.
@c Do not document
@ignore
@item text string
The text string is interpreted as an output unit direction information type
and the corresponding text is used for the link.
@xref{Output Unit Direction Information Type}.

For example, if the button array item is
@example
[ 'Next', 'node' ]
@end example

@noindent
Then the button will be a link to the next section with text
based on the name of the node associated with the next section output unit.
@end ignore

@end table

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

@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}).

@vindex USE_REL_REV
@cindex @code{rel} navigation
Similarly, if the @code{USE_REL_REV} customization variable is set,
the @code{rel} attribute is used in navigation.  In that case the
@code{rel} direction string is used for the @code{rel}
attribute (@pxref{Direction Strings}).


@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 @code{Texinfo::Convert::Converter}
(@pxref{Texinfo::Convert::Converter Helper methods,,,texi2any_internals}).  The
converter can be used for error reporting by using
@code{Texinfo::Convert::Converter} methods. @xref{Error
Reporting in User Defined Functions} on error reporting.
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 an error or a warning in a user defined function, use the methods
of @code{Texinfo::Convert::Converter} through a converter object
(@pxref{Converter Object and Conversion Functions}).

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.

@xref{Texinfo@asis{::}Convert@asis{::}Converter Registering error and warning
messages,,,texi2any_internals} for the converter module documentation on
errors and warning messages registration.


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

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

Some customization variables, in particular those associated with @@-commands,
can be reset to the value they had before starting the conversion.  For
example, they are reset in order to obtain their value before the conversion.
Thet are also reset to the value they had before starting the conversion when
their value at the end of the preambule or at the end of the document is
needed, but there are no @@-commands at those locations in the Texinfo manual.
If a value set by @code{set_conf} is intended to be found when the
customization variable value is reset, @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 the encoding in output files is taken
care of by the converter.  Operations on directories and file names, however,
such as the creation of a directory or the opening of a file require binary
strings.

To encode file names consistently with file name encoding used in the
conversion to HTML, there is a function @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 MESSAGE_ENCODING
When calling external commands, the command line arguments should also
be encoded.  To do similarly with other codes, the customization variable
@code{MESSAGE_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('MESSAGE_ENCODING');
if (defined($encoding)) @{
  $encoded_call_start = encode($encoding, $call_start);
@} else @{
  $encoded_call_start = $call_start;
@}
my $encoded_call = $encoded_call_start . $encoded_file_path;
my $call = $call_start . $file_name;
if (system($encoded_call)) @{
 $converter->document_error($converter,
     sprintf(__("command did not succeed: %s"),
            $call));
@}
@end example


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

@vindex COMMAND_LINE_ENCODING
The binary strings that could be accessed correspond to the customization
variables strings or arrays @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.
@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 @code{extra}
key @code{associated_section} of a node element and @code{associated_node}
of a sectioning command element may also be useful.

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

@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.  The id and target
are the same.  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{label_command}
if the label corresponds to an internal reference
(@pxref{Target Tree Element Link}):
@example
my $element;
$element = $converter->label_command($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 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 Perl Texinfo trees.  There are also several conventions and
constraints that user defined code should abide to when formatting HTML, in
order to comply with customization option values, avoid modifying structures
that should not be modified, and also to have information correctly registered
in the converter.

Formatting of HTML output should be used in formatting functions
(@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 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
Information on floats.
@xref{Texinfo::Document $float_types = floats_information($document),,
Texinfo::Document::floats_information,texi2any_internals}.

@item global_commands_information
Global commands information.
@xref{Texinfo::Document $commands = global_commands_information($document),,
Texinfo::Document::global_commands_information,texi2any_internals}.

@item global_information
Diverse information.
@xref{Texinfo@asis{::}Document $info = global_information($document),,
Texinfo@asis{::}Document@asis{::}global_information,texi2any_internals}.

@item indices_information
Information about defined indices, merged indices and index entries.
@xref{Texinfo@asis{::}Document $indices_information = $document->indices_information(),,Texinfo@asis{::}Document@asis{::}indices_information,texi2any_internals}.

@item sections_list
List of the sectioning commands in the document.
@end table

@xref{Texinfo@asis{::}Document Getting document information,,,texi2any_internals} on information available from the document.

@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 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 (@pxref{Texinfo::Commands %preformatted_code_commands,,,
texi2any_internals}).

@example
my $pre_classes = $converter->preformatted_classes_stack();
foreach my $pre_class (@@$pre_classes) @{
  if ($Texinfo::Commands::preformatted_code_commands@{$pre_class@}) @{
    $result = '<var>' .$result. '</var>';
    last;
  @}
@}
@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 the conversion is in a context converted multiple times,
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.
@end deftypefun

To determine if the a mutiple expansion context is set, use
@code{in_multi_expanded}:
@deftypefun {@var{$multi_expanded_context_information} =} @var{$converter}->in_multi_expanded ()
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.
@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 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 Strings Function}).
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 sets the context appropriately.
@code{convert_tree_new_formatting_context} ultimately calls @code{convert_tree}.

@deftypefun {@var{$converted_text} =} @var{$converter}->convert_tree_new_formatting_context @
      (@var{\%element}, @var{$context}, @var{$multiple_pass}, @var{$global_context}, @
       @var{$block_command_name})
@var{\%element} is a Texinfo tree element.  @var{$context} describes the new
context setup to format out of the main conversion flow.  @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

@xref{Setting the Context for Conversion} on how to set a specific context for
a Texinfo tree conversion.


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

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

The types are:

@table @code
@item _code
In this container, the conversion is done in a code context
@xref{Init File Expansion Contexts}.  For a container tree element.

@item _converted
The text of this text element is considered to be already formatted.

@item _string
In this container, the conversion is done in a string context.
@xref{Init File Expansion Contexts}.  For a container tree element.

@end table

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

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


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

The conversion to plain text can be achieved by using the @code{Texinfo::Text}
converter @code{convert_to_text} function
(@pxref{Texinfo::Convert::Text,,,texi2any_internals}).

@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

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

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

@cindex Document structure

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

@table @code
@item section_childs
For sectioning commands elements.  The children of the sectioning element
in the sectioning tree.

@item section_level
The level of the section, taking into account @code{@@raisesections} and
@code{@@lowersections}.  Level 0 corresponds to @code{@@top} or @code{@@part}
and level 1 to @code{@@chapter} level sectioning commands.
@xref{Raise/lower sections,,, texinfo, Texinfo}.

@end table

Detailed information on the tree elements is available in the Texinfo Parser
documentation, in particular a list of types and of information in the elements
@code{extra} hash (@pxref{Texinfo::Parser TEXINFO TREE,,,texi2any_internals}).


@node Output Units in User Defined Functions
@subsection Output Units in User Defined Functions

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

Both normal and special output units (@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 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

@pxref{Texinfo::Structuring METHODS,,,texi2any_internals} for more
on document structure information held by output units.

@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 Specific Formating Functions
@section Registering 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 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

@xref{Texinfo::Convert::Converter $comment = $converter->xml_comment($text),,
Texinfo::Convert::Converter::xml_comment,texi2any_internals}.

@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.  In the case
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')@}(...)}
instead of another function@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

@xref{Texinfo::Convert::Converter $protected_text = $converter->xml_protect_text($text),,
Texinfo::Convert::Converter::xml_protect_text,texi2any_internals}.
@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 = shift;
  my $id = shift;
  my $class = shift;

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

texinfo_register_formatting_function('format_separate_anchor',
                                     \&my_format_separate_anchor);
@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 for @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



@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:

@deftypefun {@var{\&default_command_conversion} =} @var{$converter}->default_command_conversion (@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


@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:
@deftypefun {@var{\&default_command_open} =} @var{$converter}->default_command_open (@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 with @code{section->@{'extra'@}->@{'section_level'@}}
(@pxref{Texinfo Tree Elements in User Defined Functions}).
@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.  Opened section 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 in User Defined Functions}).

To get the unique Texinfo tree element corresponding to a label, use
@code{label_command}:

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

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

Labels are available for target @@-commands and for @@-command referring
to target elements such as @code{@@xref} or @code{@@menu} entry node argument
as the 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
my $arg_node = $xref_tree_element->@{'args'@}->[0];
if ($arg_node and $arg_node->@{'extra'@}
    and defined($arg_node->@{'extra'@}->@{'normalized'@})) @{
  my $target_node
    = $converter->label_command($arg_node->@{'extra'@}->@{'normalized'@});
@}
@end example

Tree elements not associated with a label are obtained each differently.
For example, elements associated with index entries can be obtained using the
Texinfo parsed document index entries with
@code{$converter->get_info('document')->indices_information()}
(@pxref{Converter General 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 @code{$converter->get_info('document')->floats_information()}
(@pxref{Converter General 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}:

@deftypefun {@var{$result} =} @var{$converter}->command_text (@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}.
@end table
@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 get a Texinfo tree of elements that may be used as link description, use
@code{command_tree}:

@deftypefun {@var{$result} =} @var{$converter}->command_tree (@var{\%target_element}, @var{$no_number})
Return the a Texinfo tree to be used for a hyperlink to @var{\%target_element}.
If @var{$no_number} is set, return a Texinfo elements tree representing text
without a chapter number being included.
@end deftypefun

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 ($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>";
@end group
@} elsif (defined($associated_command_text)) @{
  $entry_root_link = $associated_command_text;
@}

my $formatted_entry = "<td><tr>$hyperlink</tr>"
                  ."<tr>$entry_root_link</tr></td>\n";
@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

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

@anchor{@code{get_element_root_command_element}}
@deftypefun {@var{\%top_level_element}, @var{\%output_unit} =} @var{$converter}->get_element_root_command_element (@var{\%element})
Return the top level element and output unit 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 Specific Formatting for Indices
@subsection 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 index entries information directly
obtained from the Texinfo manual parsing is available through
@code{$converter->get_info('document')->indices_information()}
(@pxref{Converter General 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 index entries sorted by index and letter.
This function should be called each time sorted indices are needed,
in case the sorting depends on the @code{@@documentlanguage} value.
@xref{Texinfo@asis{::}Convert@asis{::}Converter $sorted_indices = $converter->get_converter_indices_sorted_by_letter(),,Texinfo::Convert::Converter::get_converter_indices_sorted_by_letter,texi2any_internals}.
@end deftypefun


@node Image Formatting
@subsection 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 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:

@deftypefun {@var{\&default_type_conversion} =} @var{$converter}->default_type_conversion (@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 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 = shift;
  my $type = shift;
  my $element = shift;
  my $content = shift;

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

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

@group
  my @@contents = @{$element->@{'contents'@}@};
  push @@contents, @{'text' => ' <code>HTML</code> text ',
                   'type' => '_converted'@};
  my $result = $converter->convert_tree(@{'type' => '_code',
                                   'contents' => \@@contents @});
  return "<p>".$result."</p>";
@}
@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:
@deftypefun {@var{\&default_type_open} =} @var{$converter}->default_type_open (@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 = shift;
  my $type = shift;
  my $element = shift;
  my $text = shift;

  # ...

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

  # ...
@}

texinfo_register_type_formatting ('text', \&my_convert_text);
@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


@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 = shift;
  my $type = shift;
  my $element = shift;

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

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

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

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

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

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

Nomal 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{Texinfo@asis{::}Document index_entries,,,texi2any_internals}.
@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{@@nodedescription} 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{@@nodedescription} tree element to the number of time
it 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}
(@pxref{Texinfo@asis{::}Convert@asis{::}Converter Translations in output
documents,,, texi2any_internals}).

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 Strings Function
@section Internationalization of Strings Function

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

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

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 the default case, the functions from the @code{Texinfo::Translations}
module are used for translated strings through converter functions.  It is
possible to use user-defined functions instead as seen next.
@xref{Texinfo::Translations,,,texi2any_internals} for more on
@code{Texinfo::Translations}.

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}, @var{$translation_context})
@var{$string} is the string to be translated, @var{$lang} is the language.
@var{$translation_context} is an optional translation context.

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 Strings Function} for more information on
strings translations function arguments.
@end deftypefn

This function reference is not set in the default case, in the default case
@code{translate_string} from the @code{Texinfo::Translations} module is
called (@pxref{Internationalization of Strings Function}).
@xref{Registering 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' => @{
           'error--&gt;' => @{'' => 'Fehler--&gt;',@},
           # @dots{}
         @}
 # @dots{}
);

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

texinfo_register_formatting_function('format_translate_message',
                                  \&my_format_translate_message);

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

The following items common to all the special units 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 heading
Special element heading Texinfo code.

@item heading_tree
Special element heading Texinfo tree.

@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 heading string is set with @code{heading}, and should be a Texinfo code
string.  @code{heading_tree} cannot be set directly, but can be retrieved.
It is determined from @code{heading} after translation and conversion to
a Texinfo tree.

To set the 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}:

@deftypefun {@var{$list} =} @var{$converter}->get_special_unit_info_varieties @
               (@var{$item_type})
@var{$item_type} is the type of 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 the information for formatting, use @code{special_unit_info}:

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

The value returned is translated and converted to a Texinfo tree
for @samp{heading_tree}.
@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 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 (@pxref{Simple Navigation Panel
Customization}), you can completely control the formatting of navigation panels
by redefining function references.  @xref{Registering Specific Formating
Functions} for information on how to register the function references.

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

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


@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},
@code{USE_REL_REV} 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

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}.
The possible values for @var{$type} are described in
@ref{Output Unit Direction Information 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.
@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{\@@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.

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 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_BUTTONS @subentry In file beginning
@vindex BUTTONS_REL @subentry In file beginning
@code{<link>} elements are used in the header if @code{USE_LINKS} is
set, in which case @code{LINKS_BUTTONS} 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{Simple
Navigation Panel Customization}.

@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 @code{@@titlepage} is used if found in global information,
otherwise @code{simpletitle} is used (@pxref{Converter General Information}).
@end deftypefn


@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 function 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_get_selector_style ($selector)
@defunx @var{$converter}->css_add_info ($specification, $css_info)
@defunx @var{$converter}->css_set_selector_style ($selector, $css_style)

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

With @code{css_get_info}, array references corresponding to @var{$specification}
are returned.

@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_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'}.

With @code{css_set_selector_style}, @var{$selector} is a CSS rule selector and
the associated style rule is set to @var{$css_style}.
@end defun

Some examples of use:

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

$converter->css_set_selector_style('h1.titlefont', 'text-align:center');
$converter->css_add_info('imports', "\@@import \"special.css\";\n");
@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
document. @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
@appendix Specific Functions for Specific Elements

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

@table @asis

@item @code{@@today}
@xref{Texinfo::Convert::Utils $tree = expand_today($converter),,
Texinfo::Convert::Utils::expand_today, texi2any_internals}.

@item @code{@@verbatiminclude}
@xref{Texinfo::Convert::Utils $tree = expand_verbatiminclude($registrar@comma{} $configuration_information@comma{} $verbatiminclude),,
Texinfo::Convert::Utils::expand_verbatiminclude, texi2any_internals}.

@item @code{@@def*} @@-commands
@xref{Texinfo::Convert::Utils $arguments = definition_arguments_content($element),,
Texinfo::Convert::Utils::definition_arguments_content, texi2any_internals}.
@xref{Texinfo::Convert::Utils $tree = definition_category_tree($converter@comma{} $def_line),,
Texinfo::Convert::Utils::definition_category_tree, texi2any_internals}.

@item @code{@@float}
@xref{Texinfo::Convert::Converter ($caption@comma{} $prepended) = $converter->float_name_caption ($float),,
Texinfo::Convert::Converter::float_name_caption, texi2any_internals}.
Can be called as @code{$converter->float_name_caption}.

@item accent @@-commands
@xref{Texinfo::Convert::Converter $result = xml_accent($text@comma{} $accent_command@comma{} $in_upper_case@comma{} $use_numeric_entities),,
Texinfo::Convert::Converter::xml_accent, texi2any_internals}.
Can be called as @code{$converter->xml_accent}.

@xref{Texinfo::Convert::Converter $result = xml_numeric_entity_accent($accent_command_name@comma{} $text),,
Texinfo::Convert::Converter::xml_numeric_entity_accent, texi2any_internals}.

@xref{Texinfo::Convert::Converter $result = $converter->convert_accents($accent_command@comma{} \&format_accents@comma{} $in_upper_case),,
Texinfo::Convert::Converter::convert_accents, texi2any_internals}.

@item text element
@xref{Texinfo::Convert::Converter $formatted_text = $converter->xml_format_text_with_numeric_entities($text),,
Texinfo::Convert::Converter::xml_format_text_with_numeric_entities,
texi2any_internals}. Can be called as
@code{$converter->xml_format_text_with_numeric_entities}.

@item @code{@@item} in @code{@@table} and similar @@-commands
@xref{Texinfo::Convert::Converter $table_item_tree = $converter->table_item_content_tree($element@comma{} $contents),,
Texinfo::Convert::Converter::table_item_content_tree, texi2any_internals}.
Can be called as @code{$converter->table_item_content_tree}.

@item @code{@@*index} @code{@@subentry}
@xref{Texinfo::Convert::Converter $contents_array $converter->comma_index_subentries_tree($entry),,
Texinfo::Convert::Converter::comma_index_subentries_tree, texi2any_internals}.
Can be called as @code{$converter->comma_index_subentries_tree}.

@item global informative commands (@code{@@contents}, @code{@@footnotestyle} @enddots{})
@xref{Texinfo::Common set_informative_command_value($configuration_information@comma{} $element),,
Texinfo::Common::set_informative_command_value, texi2any_internals}.

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

@item sectioning commands
@xref{Texinfo::Structuring $command_name = section_level_adjusted_command_name($element),,
Texinfo::Structuring::section_level_adjusted_command_name, texi2any_internals}.

@item @code{@@itemize}
@code{@@itemize} normally have an @@-command as argument.  If, instead,
the argument 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.
In general, it is @code{$itemize->@{'args'@}->[0]}, with @code{$itemize} an @code{@@itemize}
Texinfo tree element.  @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
@end table

The @code{Texinfo::Convert::NodeNameNormalization} converter, used
for normalization of labels, exports functions that can be used on Texinfo
elements trees to obtain strings that are unique and can be used in attributes.
@xref{Texinfo::Convert::NodeNameNormalization,,,texi2any_internals}.

@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
