[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: * texinfo/doc/customization_api.texi: draft of th
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: * texinfo/doc/customization_api.texi: draft of the HTML customization API documentation. |
|
Date: |
Wed, 02 Feb 2022 18:08:04 -0500 |
This is an automated email from the git hooks/post-receive script.
pertusus pushed a commit to branch master
in repository texinfo.
The following commit(s) were added to refs/heads/master by this push:
new 8ea5d7e755 * texinfo/doc/customization_api.texi: draft of the HTML
customization API documentation.
8ea5d7e755 is described below
commit 8ea5d7e7557be1cf1bef9f24f28bfb48670d8900
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Thu Feb 3 00:07:54 2022 +0100
* texinfo/doc/customization_api.texi: draft of the HTML
customization API documentation.
* TODO: update. Put 'Process Texinfo files directly' in
an entry, stating that the Texinfo project could help
with a library for Texinfo parsing, but would not implement
processing Texinfo files directly.
---
ChangeLog | 10 +
TODO | 29 +-
doc/customization_api.texi | 3354 ++++++++++++++++++++++++++++++++++++++++++++
tp/TODO | 60 -
4 files changed, 3384 insertions(+), 69 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7bfd9748cd..f4cfe94538 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2022-02-02 Patrice Dumas <pertusus@free.fr>
+
+ * texinfo/doc/customization_api.texi: draft of the HTML
+ customization API documentation.
+
+ * TODO: update. Put 'Process Texinfo files directly' in
+ an entry, stating that the Texinfo project could help
+ with a library for Texinfo parsing, but would not implement
+ processing Texinfo files directly.
+
2022-02-02 Patrice Dumas <pertusus@free.fr>
* tp/Texinfo/Convert/HTML.pm (command_href, _external_node_href):
diff --git a/TODO b/TODO
index 1393403821..b445cdf4aa 100644
--- a/TODO
+++ b/TODO
@@ -29,7 +29,8 @@ If you are interested in working on any of these, email
bug-texinfo@gnu.org.
Suggested by Sean Young, 30 Nov 2008 20:13:11 (Savannah bug tracker)
(IN PROGRESS - documentation required)
- give a warning for "makeinfo FOO.info" when "makeinfo FOO.texi" was meant
- - Improve the HTML customization API.
+ - Review and Improve the HTML customization API. Missing from the API is
+ a possibility to customize the translated strings and the translations.
- HTML: support thumbnails.
- HTML: have a library of different CSS styles.
http://mail.gnu.org/archive/html/bug-texinfo/2004-01/msg00025.html
@@ -65,8 +66,8 @@ If you are interested in working on any of these, email
bug-texinfo@gnu.org.
* Doc:
- Use/distribute pod2texi generated documentation of the perl modules in
- tp generated in doc/tp_api -- when api is stable.
- - Documentation of the HTML customization is missing.
+ tp generated in doc/tp_api.
+ - Verify/proofread Documentation of the HTML customization.
* Info:
- If K is describe-key, K M-left changes the node as M-left is
@@ -92,6 +93,22 @@ If you are interested in working on any of these, email
bug-texinfo@gnu.org.
- generate txi-??.tex from .po's to make translators' jobs easier.
From Akim and Karl E.
+* Other
+ - Process Texinfo files directly instead of converting to other formats.
+ It should be possible to turn the C XS parser to a library, probably
+ needing a bit more more perl postprocessing rewritten in C and a
+ public C API.
+
+ There is no plan to use such a library to process Texinfo files directly
+ in the Texinfo project, as it will always be easier to convert Texinfo
+ to a format with the same information and easier to process such as
+ TexinfoXML, or to a format corresponding to the tree structure of Texinfo
+ documents as parsed by the Parser.
+
+ If others are interested in processing Texinfo files directly,
+ however, it could be possible to work on providing a practical API
+ for the C XS parser in the Texinfo project.
+
***********************************************************************
* Ideas that will not be implemented:
@@ -126,12 +143,6 @@ If you are interested in working on any of these, email
bug-texinfo@gnu.org.
aren't that many manuals even in English, let alone other languages,
and there are almost no manuals in multiple languages.
-- Process Texinfo files directly instead of converting to other formats.
- [It will always be easier to convert Texinfo to a format with the
- same information and easier to process such as TexinfoXML, or to a
- format corresponding to the tree structure of Texinfo documents as
- parsed by the Parser]
-
- Call Ghostscript to get ASCII/jpg output for the @image command.
[makeinfo should not try to be make, or assume it knows how the user
wants to generate images. Too many different methods are possible.]
diff --git a/doc/customization_api.texi b/doc/customization_api.texi
new file mode 100644
index 0000000000..cd2a001a7f
--- /dev/null
+++ b/doc/customization_api.texi
@@ -0,0 +1,3354 @@
+\input texinfo.tex @c -*-texinfo-*-
+
+@setfilename customization_api.info
+
+@include version.texi
+
+@settitle GNU Texinfo @command{texi2any} HTML customization API
+
+@copying
+This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
+texi2any program output adaptation using customization files.
+
+Copyright @copyright{} 2013, 2022 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, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end quotation
+@end copying
+
+@dircategory Texinfo documentation system
+@direntry
+* Texinfo texi2any customization: (customization_api). Customizing texi2any
+ output using customization files
+@end direntry
+
+@titlepage
+@title GNU Texinfo @command{texi2any} HTML customization API
+@subtitle for GNU Texinfo version @value{VERSION}, @value{UPDATED}
+
+@page
+
+@insertcopying
+@end titlepage
+
+@summarycontents
+@contents
+
+
+@node Top
+@top @c @command{texi2any} customization API
+
+@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, and incomplete (translations
+strings customization API, in particular, is lacking),
+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
+
+
+
+@node Init files introduction
+@chapter Init files introduction
+
+
+@node Loading Init Files
+@section Loading Initialization Files and Search Paths
+
+@cindex Loading init files
+@cindex Initialization files, loading
+@cindex Search paths, for initialization files
+
+@cindex @file{Config} init files loaded
+
+@quotation Warning
+The @file{Config} file related paths and even the use
+of @file{Config} 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 HTML output formatting.
+The program loads init files named @file{Config} each time it is run.
+Those files are looked for in the following directories (where
+@var{prog} is the name of the program invoked on the command line,
+normally @code{makeinfo} or @code{texi2any}):
+
+@table @file
+@item @var{datadir}/@var{prog}/
+(where @var{datadir} is the system data directory specified at
+compile-time, e.g., @file{/usr/local/share})
+
+@item @var{sysconfdir}/@var{prog}/
+(likewise specified at compile time, e.g., @file{/usr/local/etc})
+
+@item ~/.@var{prog}/
+(where @code{~} is the current user's home directory)
+
+@item ./.@var{prog}/
+(under the current directory)
+
+@item ./
+(the current directory)
+@end table
+
+All @file{Config} files found are loaded, in the above order. Thus,
+@file{./Config} can override entries in, say,
+@file{/usr/local/share/makeinfo/Config}.
+
+@c @opindex --init-file
+@cindex @option{--init-file}
+However, the most common way to load an initialization file is with
+the @option{--init-file} option, explicitly specifying the file to be
+loaded. By default the following directories are searched, in the
+following order, where @var{prog} is the name of the program invoked
+on the command line (@command{makeinfo}, @command{texi2any}, etc.).
+Only the first file found is used:
+
+@enumerate
+@item The current directory @file{./};
+
+@item @file{./.@var{prog}/} under the current directory;
+
+@item @file{~/.@var{prog}/}
+where @code{~} is the current user's home directory;
+
+@item @file{@var{sysconfdir}/@var{prog}/}
+where @var{sysconfdir} is the system configuration directory
+specified at compile-time, e.g., @file{/usr/local/etc};
+
+@item @file{@var{datadir}/@var{prog}/}
+Where @var{datadir} is the system data directory likewise specified at
+compile time, e.g., @file{/usr/local/share};
+
+@item @file{./.texinfo/init/} under the current directory;
+
+@item @file{~/.texinfo/init/} under the current home directory;
+
+@item @file{@var{sysconfdir}/texinfo/init/} with @var{sysconfdir} as above;
+
+@item @file{@var{datadir}/texinfo/init/} with @var{datadir} as above.
+@end enumerate
+
+Additional directories may be prepended to the list with the
+@option{--conf-dir} option (@pxref{Invoking texi2any,,,texinfo}).
+
+
+@node Init File Basics
+@section 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 customization API for the conversion to
HTML@footnote{The
+@code{Texinfo::Convert::HTML} module also implements the Converter and the
conversion
+code needed for the the HTML customization API user defined functions to be
called
+during the document conversion.}.
+The Licenses conditions of the diverse files used
+as example should be taken into account when reusing code.
+
+The init files are supposed to be used to customize @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.
+
+@cindex Init file namespaces
+@cindex Namespaces, 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 mandatory, 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 conversion of Texinfo to HTML is broadly done in two steps. The first
step is the
+parsing of the Texinfo code in a tree-like structure representing the document.
+The second step is the conversion of the tree-like structure. The first step
is
+done in the main program, which reads command line options and loads init files
+before the parsing. The main programs determines informations on the document
+structure after the parsing, before the conversion of the tree. The
+conversion step is done in a @dfn{converter} which holds configuration
+information, allows to register error messages and can interact with user
+defined code. The converter is not available in the main body of the init
+files, instead it is passed to functions defined in init files and registered
+as functions to be called from the converter. @xref{User Defined Functions}.
+
+
+@node Configuration Variables in Init File
+@chapter Configuration Variables in Init File
+
+
+@node Setting and Getting Configuration Variables
+@section Setting and Getting Configuration Variables
+
+@cindex Configuration variables, setting and getting
+
+The basic operations on configuration variables are to set and
+retrieve their values. Configuration variables relevant for the main program
can be
+either string variables or arrays. It is also possible to set configuration
variables
+for the conversion phase through the main program.
+
+To set the value of a string configuration variable from an initialization
file,
+use @code{set_from_init_file}:
+
+@defun 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
+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
+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
+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
@code{TEXINFO_OUTPUT_FORMAT},
+as some additional code needs to be run. Instead, the
+@code{texinfo_set_format_from_init_file} function should be used:
+
+@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 configuration variables associated with @@-commands, see
+@ref{Configuration Variables for @@-Commands,,,texinfo}. For the configuration
+variables associated with command line options, see @ref{Configuration
+Variables and Options,,,texinfo}.
+
+Configuration variables for the main program associated with an array of values
+are handled differently. Two functions can be used in init files,
+@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 configuration variable:
+
+@defun texinfo_add_to_option_list ($variable_name,
$variable_values_array_reference)
+@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}.
+@end defun
+
+@quotation Warning
+The main program configuration variables associated with arrays
+are not documented.
+@end quotation
+
+Array and hash references configuration variables values relevant
+in converters only (not in main program) 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.
+Such arrays or shash references can be passed through
@code{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
+
+To get the value of a variable in the main program, 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
+
+
+@node Adding Configuration Variables
+@section Adding Configuration Variables
+
+@cindex Configuration variables, adding
+
+Trying to set a configuration variable that is not known as a valid
+configuration variable in @command{texi2any} is an error. It is possible,
however,
+to add new configuration variables from init files. To add a configuration
+variable, the function is @code{texinfo_add_valid_customization_option}:
+
+@defun texinfo_add_valid_customization_option ($variable_name)
+@var{$variable_name} is added as a valid configuration 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.
+
+
+@node Simple formatting customization
+@chapter Simple formatting customization
+
+Some change in output formatting can be specified with very simple code,
+not very different from simple configuration text.
+
+
+@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
+
+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{display,, @code{@@display}}) and
+@code{@@example} environments (@pxref{example,, @code{@@example}}), 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 exampe, in @code{@@code} or @code{@@option} commands.
+@c (@pxref{}) ref to Texinfo manual
+
+@item math context
+@cindex Math expansion context
+Math (@pxref{math,, @code{@@math}, texinfo}). Code or preformatted
+specifications are often used for math too. In those cases, there
+is no way to separately specify the formatting in math context.
+
+@item string context
+@cindex String expansion context
+When rendering strings without formatting elements, for example in
+@c comments (@pxref{Comments}) and
+titles.
+@c We have two string contexts,
+@c one that produces plain text, and a second that
+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)
+@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} is set, @var{$translated_string} is used
+as text and is translated when the document language changes.
+@xref{Texinfo::Translations METHODS,,,tp_api}.
+@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{­} to be output
+for @code{@@-} in normal, preformatted (and math) and string context, call
+
+@example
+texinfo_register_no_arg_command_formatting('-', undef, '­');
+@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-->} 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-->');
+@end example
+
+@quotation Warning
+There is no possibility to provide custom translations for selected
+strings, such that the translated string case cannot actually be used
+in practice.
+@end quotation
+
+
+@node Simple Customization for Simple Commands with Braces
+@section Simple Customization for Simple Commands with Braces
+
+@cindex HTML customization for simple commands
+@cindex Simple commands, customizing HTML for
+@cindex Style commands, customizing HTML for
+
+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}) can be changed 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}, @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.
+
+If @var{$html_element} is set, the argument is enclosed between the
+@var{$html_element} element opening and the element closing.
+@var{$html_element} is always ignored in @samp{string} context. If
@var{$in_quotes}
+is true, the result is enclosed in quotes
+associated with configuration variables @code{OPEN_QUOTE_SYMBOL} and
+@code{CLOSE_QUOTE_SYMBOL}.
+
+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{@@t@{argument@}} to be formatted as
+@code{<code>@var{argument}</code>} in normal and preformatted context,
+and as a quoted string in string context, use:
+
+@example
+texinfo_register_style_command_formatting ('t', 'code', 0, 'normal');
+texinfo_register_style_command_formatting ('t', 'code', 0, 'preformatted');
+texinfo_register_style_command_formatting ('t', undef, 1, 'string');
+@end example
+
+To output the formatted argument of @code{@@t} as is:
+@example
+foreach my $context ('normal', 'example', string') @{
+ texinfo_register_style_command_formatting ('t', undef, undef, $context);
+@}
+@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 some informations on their formatting set.
+The first information that can be set is whether their contents should be
considered
+in code context (@pxref{Init File Expansion Contexts}). The other 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,,,tp_api}, for a description
+of container types.
+
+
+@node Simple Customization of CSS
+@section Simple Customization of CSS Rules and Imports
+
+@cindex Customizing CSS
+@cindex CSS customization
+
+CSS in HTML output can already be modified with command line options
+(@pxref{HTML CSS,,,texinfo}) and customization options such as
+@code{NO_CSS} and @code{INLINE_CSS_STYLE}.
+
+Informations on static CSS information used in conversion and some control
+over the CSS associated output is possible. The corresponding informations are
+CSS rules lines and CSS import lines obtained from parsing
+@option{--css-include=@var{file}} files, as described in @ref{HTML
CSS,,,texinfo},
+and CSS rules associated with HTML elements and class attributes
+used in conversion. The CSS rules selectors are, classically,
+@code{@var{element}.@var{class}} strings with @var{element} an HTML element and
+@var{class} an attribute class associated to that element.
+
+The function used are @code{css_get_info} to get information and
+@code{css_add_info} to modify:
+
+@defun $converter->css_get_info ($specification, $css_info)
+@defunx $converter->css_add_info ($specification, $css_info, $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 CSS rules associated
+with HTML elements and class attributes selectors.
+
+With @code{css_get_info}, if @var{$specification} is set as @code{'rules'} or
+@code{'imports'}, the corresponding arrays are returned. Otherwise,
+if @var{$css_info} is @code{undef}, a hash reference with all the CSS rules
selector as keys
+and the corresponding styles as values is returned. If @var{$css_info} is
defined,
+it is considered to be a CSS rules selector and the corresponding CSS style is
returned,
+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'}.
+Otherwise, @var{$css_info} is a CSS rule selector and the associated
+style 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_info('styles',
'h1.titlefont');
+
+$converter->css_add_info('styles', 'h1.titlefont', 'text-align:center');
+$converter->css_add_info('imports', "\@@import \"special.css\";\n");
+@end example
+
+Note that the CSS selectors and associated styles 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.
+@c @xref{} html_attribute_class
+
+How to run code during the conversion process is described later
+(@pxref{Init File Calling at Different Stages}). The simplest way to
+use the @code{css_add_info} function would be to use a function
+registered for the @samp{structure} stage:
+
+@example
+sub my_function_set_some_css @{
+ my $converter = shift;
+
+ $converter->css_add_info('styles', 'h1.titlefont', 'text-align:center');
+ # ... more calls to $converter->css_add_info();
+@}
+
+texinfo_register_handler('structure', \&my_function_set_some_css);
+@end example
+
+@xref{Customizing CSS} for even more control on CSS lines output.
+
+
+@node Simple headers customizations
+@chapter Simple headers customizations
+
+Some customization of navigation panels appearing in header and footers in
+output can be specified 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 Element Units
+@section Output Element Units
+
+@cindex Output elements
+@cindex Elements, main unit of output documents
+@cindex Document units
+@cindex Texinfo tree element units
+
+We will call the main unit of output documents a document @dfn{unit},
+or a Texinfo tree element @dfn{unit}. An
+element unit's association with output files is determined by the split
+options (@pxref{Splitting Output}). This section describes precisely
+how these output units work, with details for customization.
+
+@cindex Output elements, defined
+
+The output elements are:
+
+@table @emph
+@item Normal document units
+@cindex Normal document units
+These are 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
+element unit. Either the node or the sectioning command is considered to
+be the main element component, depending on the values of the
+configuration variables @code{USE_NODES}
+(@pxref{@command{texi2any} Configuration Variables}).
+
+For example, when generating Info, the nodes are the units; when
+generating Docbook, sectioning commands are the main element
+unit component; and when generating HTML, either case may happen
+(@pxref{Two Paths}).
+
+@item Top element
+@cindex Top element
+
+The top element is the highest element unit in the document structure. If
+the document has an @code{@@top} section (@pxref{makeinfo top}), it is
+the element associated with that section; otherwise, it is the element
+associated with the document's @code{@@node Top} (@pxref{The Top
+Node}). If there is no @code{@@node Top}, the first element in the
+document is the top element.
+
+@item Miscellaneous elements
+@cindex Table of contents, output element unit
+@cindex Short table of contents, output element unit
+@cindex Overview, output element unit
+@cindex Footnotes, output element unit
+@cindex About page, output element unit
+The remaining element units are associated with different files if the
+document is split, and also if @code{MONOLITHIC} is not set. There
+are four such miscellaneous elements, also called special elements:
+@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{Overview} should only appear if
+@code{@@shortcontents} or @code{@@summarycontents} is present.
+
+@item The configuration variables @code{contents} and
+@code{shortcontents} may be set to trigger the output of the
+respective elements.
+
+@item If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{separate_element},
+the @emph{Table of contents} and @emph{Overview} elements are separate
+(@pxref{Contents and Short Table of Contents Customization}). Otherwise
+the @emph{Table of contents} and @emph{Overview} elements are directly
+included within the document, at locations depending on the specific
+@code{CONTENTS_OUTPUT_LOCATION} value.
+
+@item When generating HTML, the @emph{Footnotes page} should only
+be present if the footnotes appear on a separate page (@pxref{Footnote
+Styles}). However, a footnote element is present if the document is
+not split.
+
+@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 element units, especially in
+case of monolithic output. It is usually with HTML output that
+special elements may be present.
+
+The main component of elements is sections if @code{USE_NODES} is 0;
+conversely, the main component is nodes if @code{USE_NODES} is set.
+
+When sections are the main components of element units, ``isolated'' nodes
+not directly associated with a sectioning command are associated with
+the following sectioning command, while sectioning commands without
+nodes constitute an element. Conversely, when nodes are the main
+components of elements, isolated sections not associated with nodes
+are associated with the previous node, and isolated nodes are
+elements.
+
+
+@node Output Element Unit Directions
+@section Output Element Unit Directions
+
+@cindex Output element unit directions
+@cindex Links informations
+@cindex Element directions
+
+A variety of data items, called @dfn{element directions}, are associated
+with element units. They may be used in the formatting functions, and/or
+associated with a button (@pxref{Simple Navigation Panel Customization}).
+
+Each element direction has a name and a reference to the element unit they
+point to, when such an element exists. The element is either a
+global element (for example, the first element) or relative to the
+current element (for example, the next element unit). Such relative
+elements 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}).
+
+Here is the list of element units directions:
+
+@table @emph
+@item @samp{@ }
+An empty button.
+
+@item Top
+Top element.
+
+@item About
+About (help) page.
+
+@item Contents
+Table of contents.
+
+@item Overview
+Overview: short table of contents.
+
+@item Footnotes
+Corresponds to the @code{Footnotes} element (@pxref{Output Element
+Units}).
+
+@item Index
+The first element unit with @code{@@printindex}.
+
+@item This
+The current element unit.
+
+@item Forward
+Next element unit in reading order.
+
+@item First
+First element unit in reading order.
+
+@item Last
+Last element unit in reading order.
+
+@item Back
+Previous element unit in reading order.
+
+@item FastForward
+Next chapter element unit.
+
+@item FastBack
+Beginning of this chapter, or previous chapter if the element is a chapter.
+
+@item Next
+Next section element unit at the same level.
+
+@item Prev
+Previous section element unit at the same level.
+
+@item Up
+Up section.
+
+@item SectionNext
+Next element unit in section reading order.
+
+@item SectionPrev
+Previous element unit in section reading order.
+
+@item SectionUp
+Up in section reading order.
+
+@item NodeNext
+Next node element unit.
+
+@item NodeForward
+Next node element unit in node reading order.
+
+@item NodeBack
+Previous node element unit in node reading order.
+
+@item NodePrev
+Previous node element unit.
+
+@item NodeUp
+Up node element unit.
+
+@end table
+
+@anchor{Element Direction Information Type}
+The element directions also have types of information associated,
+which are in general set dynamically depending on the current element
+unit, for instance on the element unit whose navigation panel is being
+formatted:
+
+@table @code
+@item href
+A string that can be used as an href attribute linking to the element 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 tree
+A Texinfo tree element representing the direction.
+
+@item target
+A string representing target of the direction, typically used as id
+attribute in the element unit corresponding to the direction, and in href
+attribute.
+
+@item node
+Same as @code{text}, but selecting the node associated with the element unit
+direction in priority.
+
+@item section
+Same as @code{text}, but selecting the sectioning command
+associated with the element unit direction in priority.
+
+@end table
+
+@code{text}, @code{tree} and @code{string} also have a variant with
+@samp{_nonumber} prepended, such as @code{text_nonumber} without sectioning
+command number in the representation.
+
+
+@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.
+
+The configuration variables
+@code{VERTICAL_HEAD_NAVIGATION}, @code{ICONS}, @code{HEADERS},
+@code{HEADER_IN_TABLE}, @code{USE_ACCESSKEY}, @code{USE_REL_REV} and
+@code{WORDS_IN_PAGE}
+may be used to change the navigation panel formatting.
+@xref{@command{texi2any} Configuration Variables}.
+
+@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 configuration variables
+with @code{set_from_init_file}. @xref{Setting and Getting Configuration
Variables}.
+
+The following configuration 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. If the output is split at nodes or sections,
+they are also used at the page footer, and in the case of section
+navigation being enabled, at the page header.
+
+@item SECTION_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 or nodes, respectively.
+
+@item CHAPTER_BUTTONS
+Specifies the buttons appearing at the page footer if split at
+chapters, and 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 elements
+and, if the output is split, at the end of such elements.
+
+@item LINKS_BUTTONS
+Used for @code{<link>} elements if they are output in the headers.
+
+@item TOP_BUTTONS
+Specifies the buttons used in the top element (@pxref{Output Element
+Units}).
+@end vtable
+
+Each array specifies which buttons are included, and how they are
+displayed. Each array element is associated with a button of the
+navigation panel from left to right. The meaning of the array element
+values is the following:
+
+@anchor{Buttons Display}
+
+@table @emph
+@item string with an element unit direction
+@vindex BUTTONS_TEXT
+If icons are not used, the button is a link to the corresponding
+element whose text is defined by the value associated with the element
+direction in the hash associated with the @code{BUTTONS_TEXT} configuration
+variable, surrounded by @samp{[} and
+@samp{]}. If the element direction is @samp{ }, the @samp{[} and @samp{]}
+are omitted.
+
+@vindex ACTIVE_ICONS
+@vindex BUTTONS_NAME
+@vindex PASSIVE_ICONS
+@vindex BUTTONS_GOTO
+@cindex Icons, in navigation buttons
+If icons are used, the button is an image whose file is determined by
+the value associated with the element direction in the
+@code{ACTIVE_ICONS} variable hash if the link leads to an element, or in the
+@code{PASSIVE_ICONS} variable hash if there is no element to link to. If
+there is a link to the element, the icon links to that element. The
+button name and button description are given as HTML attributes to
+have a textual description of the icon. The corresponding strings are
+in the @code{BUTTONS_NAME} variable hash for the button name and
+@code{BUTTONS_GOTO} variable hash for a more detailed description.
+
+@item function reference
+The function is called with one boolean argument, true if the
+navigation panel should be vertical. Should return the formatted
+button text.
+
+@item scalar reference
+The scalar value is printed.
+
+@item array reference of length 2
+Here, the first array element should be a an element direction.
+A link to the element unit associated with the element direction
+is generated. The text of the link depends on the second array element.
+
+@table @emph
+@item reference to a text string
+In that case, the corresponding text is used.
+
+@item reference to a function
+The functions is called with two arguments, the converter object and the
+element direction and should return two scalars, the link href and text and a
boolean
+set if a delimiter is needed after that button.
+
+@item text string
+The text string is interpreted as an element direction information type
+and the corresponding text is used for the link.
+@xref{Element Direction Information Type}.
+
+For example, if the button array element 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 element unit.
+
+@end table
+
+@end table
+
+@anchor{Accesskey and @code{rel} Navigation}
+@vindex BUTTONS_ACCESSKEY
+@cindex @code{accesskey} navigation
+If the configuration variable @code{USE_ACCESSKEY} is set, the
+@code{accesskey} attribute is used in navigation. The
+@code{BUTTONS_ACCESSKEY} configuration variable hash is then used for the
+@code{accesskey} attributes.
+
+@vindex BUTTONS_REL@r{, for navigation}
+@cindex @code{rel} navigation
+Similarly, if the @code{USE_REL_REV} configuration variable is set,
+the @code{rel} attribute is used in navigation. In that case the
+@code{BUTTONS_REL} configuration variable hash is used for the @code{rel}
+attribute.
+
+
+@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
+
+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
+registering function @code{texinfo_register_command_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_command_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}:
+
+@deftypefn {Function Reference} $text format_thing ($arg1 \@@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 deftypefn
+
+
+@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,,,tp_api}). The converter
+can also be used for error reporting as it is also a @code{Texinfo::Report}
+object (@pxref{Texinfo::Report,,,tp_api}), and for in-document strings
+translation as it is also a @code{Texinfo::Translations}
+object (@pxref{Texinfo::Translations,,,tp_api}). No detail are given
+in the present manual on those modules methods, the specific module
+documentation can be used if needed.
+
+One important converter method that can be used in user defined functions
+is @code{convert_tree} that convert a Texinfo tree rooted at any element.
+There is no reason to use that function often, as the converter that calls
+the user defined functions takes care to run through the tree, but it
+can be interesting in some cases.
+
+@defun $converter->convert_tree (\%element, $explanation)
+@var{\%element} is a Texinfo tree element. @var{$explanation} is
+optional, it is a tree explaining why the function was called, to help
+in case of debugging. The function returns @var{\%element} converted.
+@end defun
+
+An example of combining conversion with translation:
+@example
+$converter->convert_tree($converter->gdt('@{explained_string@}
(@{explanation@})',
+ @{'explained_string' => @{'type' => '_converted',
+ 'text' => $result@},
+ 'explanation' => @{'type' => '_converted',
+ 'text' => $explanation_result@}@}), "convert explained
$cmdname");
+@end example
+
+@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}.
+
+@defun $converter->convert_tree_new_formatting_context (\%element, $context,@
+ $multiple_pass,
$global_context)
+@var{\%element} is a Texinfo tree element. @var{$context} is optional, a
string describing
+the new context to be started to format out of the main conversion flow. If
not
+defined, the conversion is done in the main document flow.
@var{$multiple_pass}
+is an optional string that marks that the conversion is done more than once.
+@var{$global_context} is an optional string that marks that the formatting
+may be done in advance, and can be redone.
+
+The precise string values are used for debugging, so it is better to use
+informative strings, but the values do not have influence on the output.
+
+The function returns @var{\%element} converted, setting the conversion context
+according to the arguments.
+@end defun
+
+@xref{Setting the Context for Conversion} on how to set a specific context for
+a Texinfo tree conversion.
+
+
+@node Texinfo Tree Elements in User Defined Functions
+@section 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 ok:
+
+@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 not ok:
+
+@example
+push @@@{$element->@{'contents'@}@}, @{'text' => ' my added text'@};
+@end example
+
+In addition to the elements obtained after parsing a Texinfo
+document, two elements are added,
+@code{unit} type elements that correspond to the normal document units
+(@pxref{Output Element Units}), and special elements with type
+@code{special_element} that correspond to added special elements (@pxref{Output
+Element Units}). These added elements, as well as nodes and sectioning
elements
+hold informations on the document structure in the @code{structure} element
hash
+(@pxref{Texinfo::Structuring METHODS,,,tp_api}).
+
+Normal tree unit elements have a @code{unit_command} key in the
+@code{extra} hash that points to the associated @code{@@node} or
+sectioning @@-command depending on which of nodes or sectioning commands
+are the main components of elements. @xref{Output Element Units}.
+
+The following keys of the @code{structure} hash can be interesting:
+
+@table @code
+@item associated_unit
+For sectioning and @code{@@node} @@-command elements. The associated
+tree unit element.
+
+@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.
+@c @xref{} to Texinfo manual
+
+@item unit_filename
+For tree unit elements. The associated file name.
+
+@item unit_next
+For tree unit elements. The next unit element in document order.
+
+@item unit_prev
+For tree unit elements. The previous unit element in document order.
+@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,,,tp_api}).
+
+
+@node Setting the Context for Conversion
+@section Setting the Context for Conversion
+
+Three special container types are recognized by the converter can
+be used to convert a Texinfo tree in a specific context. Those
+types cannot appear in a regular Texinfo tree. They can be the
+type directly associated with a text element, or the type of a tree.
+The types are:
+
+@table @code
+@item _code
+In this container, the conversion is done in a code context
+@xref{Init File Expansion Contexts}.
+
+@item _converted
+In this container, the texts are considered to be already formatted.
+This is more likely to be relevant as the type of a text element.
+
+@item _string
+In this container, the conversion is done in a string context.
+@xref{Init File Expansion Contexts}.
+
+@end table
+
+These contexts are typically used together with converter conversion
+functions use (@pxref{Converter Object and 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
+
+There is no context for plain text, but the conversion to plain
+text can be achived by using the @code{Texinfo::Text} converter
+(@pxref{Texinfo::Convert::Text,,,tp_api}). For example, to convert
+the Texinfo tree element @var{$element} to plain text:
+
+@example
+my $plaintext = Texinfo::Convert::Text::convert_to_text($element,
+ Texinfo::Convert::Text::copy_options_for_convert_text($converter));
+@end example
+
+@node Conversion Configuration Variables
+@section Setting and Getting Conversion Configuration Variables
+
+The configuration variables values set during the conversion process,
+and associated with a converter, may be different from the main program
+configuration 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 configuration variables. Finally,
+some variables may 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 configuration variables.
+
+In general, the functions described here should be used in user defined
+functions, and not the similar functions used to configuration variables
+from init files (@pxref{Configuration Variables in Init File}).
+
+To get the value of a variable in a converter @code{$converter},
+the function is @code{get_conf}:
+
+@defun $converter->get_conf ($variable_name)
+@var{$variable_name} is the name of the variable; its value in the converter
+@var{$converter} (possibly @code{undef}) is returned.
+@end defun
+
+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 $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
+
+The values set in converter with @code{set_conf} will not override command-line
+set configuration variables, nor variables set 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 configuration would be needed, the
+@code{force_conf} functions can be used:
+
+@defun $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 Conversion General Information
+@section Conversion General Information
+
+Some general information is available from the converter.
+
+To determine if an output format (html or tex, for example)
+@c , @pxref{}) reference on Texinfo manual
+is expanded, use @code{is_format_expanded}:
+
+@deftypefun $is_format_expanded $converter->is_format_expanded ($format)
+Return true if format @var{$format} is expanded, according to
+the command-line and init file informations.
+@end deftypefun
+
+The main method to get information from the converter is @code{get_info}:
+
+@defun $converter->get_info ($info)
+Return information on @var{$info}.
+@end defun
+
+The available informations are on:
+@table @code
+@item copying_comment
+Text appearing in @code{@@copying} with all the Texinfo commands
+put into comments (@pxref{copying,,@code{@@copying},texinfo}).
+
+@item current_filename
+The file name of the current document unit being converted.
+
+@item destination_directory
+Destination directory for the output files.
+
+@item document_name
+Base name of the document.
+
+@item documentdescription_string
+@code{@@documentdescription} argument converted in a string context.
+@xref{Init File Expansion Contexts}.
+
+@item floats
+Informations on floats. Gathered from the input Texinfo code parsing.
+@xref{Texinfo::Parser $float_types = floats_information($parser),,
+Texinfo::Parser::floats_information,tp_api}.
+
+@item global_commands
+Global commands informations. Gathered from the input Texinfo code parsing.
+@xref{Texinfo::Parser $commands = global_commands_information($parser),,
+Texinfo::Parser::global_commands_information,tp_api}.
+
+@item index_entries
+Information on indices taking into account merged indices.
+@xref{Texinfo::Structuring $merged_entries =
merge_indices($index_names),,Texinfo::Structuring::merge_indices, tp_api}.
+
+@item index_entries_by_letter
+Index entries sorted by letter. @xref{Texinfo::Structuring
($index_entries_sorted@comma{} $index_entries_sort_strings) =
sort_indices($registrar@comma{} $configuration_informations@comma{}
$merged_index_entries@comma{}
$sort_by_letter),,Texinfo::Structuring::sort_indices,tp_api}.
+
+@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
+informations 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} configuration variable value.
+
+@item non_breaking_space
+Non breaking space, can be @samp{ }, but also a non breaking
+space character or the corresponding numeric entity based on
+@code{ENABLE_ENCODING} and @code{USE_NUMERIC_ENTITY} configuration variables
+values.
+
+@item paragraph_symbol
+Paragraph symbol, can be @samp{¶}, but also the corresponding numeric
entity
+or encoded character based on @code{ENABLE_ENCODING} and
+@code{USE_NUMERIC_ENTITY} configuration variables values.
+
+@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, without the leading @@ that was used for the
simpletitle.
+
+@item structuring
+Informations on the document structure. Gathered before the conversion.
+Two hash keys correspond to interesting information, @code{sectioning_root}
+which points to the top level sectioning command tree element, and
+@code{sections_list} which holds the list of the sectioning commands in the
+document.
+
+@end table
+
+@xref{Simple Customization of CSS} for an explanation on getting
+information on CSS.
+
+
+@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, \&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) = shift;
+ # ....
+ 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.
+@end menu
+
+
+@node Customizing Output File Names
+@section Customizing Output File Names
+
+@cindex Customizing output file names
+@cindex Output file names, customizing
+
+@vindex PREFIX
+@vindex SUBDIR
+@vindex EXTENSION
+It is possible to specify the output file names with more control than
+merely the command line option @option{--output} (@pxref{Invoking
+texi2any}). The @code{PREFIX} configuration variable overrides the
+base name of the file given by @code{@@setfilename} or the file name
+and should not contain any directory components. To alter
+intermediate directories, use the @code{SUBDIR} configuration
+variable. Finally, The extension may also be overriden by the
+configuration variable @code{EXTENSION}. This variable should be
+@code{undef} if no extension is to be added.
+
+@vindex TOP_FILE
+Furthermore, the configuration variables @code{TOP_FILE} override
+the output file name for the top element.
+
+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 node file name.
+
+@deftypefn {Function Reference} $node_file node_file_name ($converter, @
+ \%node_element, $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{tree_unit_file_name}, is used to
+customize the file names associated with each element unit, and the name of
+the file associated with the special elements (@pxref{Output Element
+Units}).
+
+@deftypefn {Function Reference} $file tree_unit_file_name ($converter, @
+ \%unit_element, $file_name)
+@var{$converter} is a converter object. @var{\%unit_element} is the Texinfo
+element corresponding to the unit element. @var{$file_name} is the file
+name that has been already set. The function should return the file name for
+the unit element (@var{$file}).
+@end deftypefn
+
+In the user defined functions, the information that a unit element
+is associated with @code{@@top} or @code{@@node Top} or more generally
+considered to be the Top element may be determined with
+@example
+$converter->element_is_tree_unit_top(\%unit_element);
+@end example
+
+
+@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. Functions used to set both targets and file names are 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):
+
+@deftypefn {Function Reference} {$target} label_target_name @
+ ($converter, \%label_info, $default_target)
+@var{$converter} is a converter object. @var{\%label_info} is a hash
+reference containing a @code{normalized} key with value the
+normalized node name, a @code{node_content} key with value a reference on an
+array containing the Texinfo tree contents of the command label.
+@var{$default_target} is the target that has been already set. The function
+should return the target (@var{$target}).
+@end deftypefn
+
+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} {($target, $target_contents,
$target_shortcontents, $file)} @
+ sectioning_command_target_name ($converter, \%section_element,
$default_target, @
+ $default_target_contents, $default_target_shortcontents, $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
+
+
+For special element units (@pxref{Output Element Units}), the function
+reference is:
+
+@deftypefn {Function Reference} {($target, $file)}
special_element_target_file_name @
+ ($converter, \%element, $default_target, $file_name)
+@var{$converter} is a converter object. @var{\%element} is the Texinfo
+element corresponding to the special element unit. @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
+
+
+@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 before collecting
+the @@-commands and their text, expanding them between the collecting
+and expansion phase and doing clean-up after the expansion pass.
+
+There are four places for user defined functions:
+@vtable @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 file names.
+@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 elements, 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{Init File Global Information}).
+
+@item finish
+Called after output generation is finished.
+@end vtable
+
+The function used to register a user defined functions is
+@code{texinfo_register_handler}:
+
+@defun texinfo_register_handler ($stage, \&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} {$status} stage_handler @
+ ($converter, \%tree, $stage)
+@var{$converter} is a converter object. @var{\%tree} is the Texinfo
+tree root element. @var{$stage} is the current stage.
+
+If @var{$status} is false it means that an error occured.
+@end deftypefn
+
+
+@node User Defined Functions in Conversion
+@chapter User Defined Functions in Conversion
+
+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 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).
+
+
+@node Tree Element Conversion Functions
+@section Tree Element Conversion Functions
+
+Functions used for tree elements associated with @@-commands are
+considered separately from functions used for tree elements not
+associated with @@-commands, which includes containers with a type
+and text. There are two 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.
+
+
+@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}:
+
+@defun texinfo_register_command_opening ($command_name, \&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} {$text} command_open @
+ ($converter, $command_name, \%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:
+@defun \&default_command_open $converter->default_command_open ($command_name)
+@var{$command_name} is the @@-command name without the @@. Returns the
+default opening function reference for @var{$command_name}, or undef if there
is none.
+@end defun
+
+
+@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, \&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} {$text} command_conversion @
+ ($converter, $command_name, \%element, \@@args, $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 a hash references, 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. @xref{Converter Object and Conversion Functions}.
+
+@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}.
+
+@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 first argument of
+@code{@@email} which is both available as @samp{monospace} and
+@samp{monospacestring}.
+
+For example, @code{$args->[0]->@{'normal'@}} is the first argument converted in
+normal context.
+
+@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
+
+To call a conversion function from user defined code, the function reference
+should first be retrieved using @code{command_conversion}:
+
+@defun \&command_conversion $converter->command_conversion ($command_name)
+@var{$command_name} is the @@-command name without the @@. Returns the
+conversion function reference for @var{$command_name}, or undef if there is
none,
+which should only be the case for @@-commands ignored in HTML not defined by
the user.
+@end defun
+
+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:
+
+@defun \&default_command_conversion $converter->default_command_conversion
($command_name)
+@var{$command_name} is the @@-command name without the @@. Returns the
+default conversion function reference for @var{$command_name}, or undef if
there is none,
+which should only be the case for @@-commands ignored in HTML.
+@end defun
+
+
+@node Type Tree Element Opening Functions
+@subsection Type Tree Element Opening Functions
+
+User defined functions called when an element without @@-command but
+with a container type is first encountered are registered
+with @code{texinfo_register_type_opening}:
+
+@defun texinfo_register_type_opening ($type, \&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} {$text} type_open ($converter, @
+ $type, \%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:
+@defun \&default_type_open $converter->default_type_open ($type)
+@var{$command_name} is the element type. Returns the
+default opening function reference for @var{$type}, or undef if there is none.
+@end defun
+
+
+@node Type Tree Element Conversion Functions
+@subsection Type Tree Element Conversion Functions
+
+User defined functions called for the conversion of an element without
+@@-command but 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, \&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} {$text} type_conversion ($converter, @
+ $type, \%element, $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 @@-command conversion.
+@end deftypefn
+
+To call a conversion function from user defined code, the function reference
+should first be retrieved using @code{type_conversion}:
+
+@defun \&command_conversion $converter->command_conversion ($type)
+@var{$type} is the element type. Returns the
+conversion function reference for @var{$type}, or undef if there is none,
+which should only be the case for types ignored in HTML not defined by the
user.
+@end defun
+
+It is possible to have access to the default conversion function reference.
+The function used is:
+
+@defun \&default_type_conversion $converter->default_type_conversion
($command_name)
+@var{$type} is the element type. Returns the
+default conversion function reference for @var{$type}, or undef if there is
none,
+which should only be the case for types ignored in HTML.
+@end defun
+
+
+@node Formatting Functions
+@section Formatting Functions
+
+Most formatting functions are specific, with specific arguments,
+and a specific item formatted.
+
+User defined functions associated with
+the formatting of special elements body (@pxref{Output Element Units})
+are handled separately.
+
+The formatting functions are often called from function that can be
+replaced by a user defined function, therefore these functions may
+not be called if the replacement functions do not keep a similar
+operation.
+
+
+@node Specific formating Functions
+@subsection Specific formating Functions
+
+User defined formatting functions are registered with
+@code{texinfo_register_formatting_function}:
+
+@defun texinfo_register_formatting_function ($formatted, @
+ \&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}:
+
+@defun \&formatting_function $converter->formatting_function ($formatted)
+@var{$formatted} is a string describing the formatting
+function. Returns the associated formatting function reference.
+@end defun
+
+It is possible to have access to the default formatting function reference.
+The function used is:
+
+@defun \&default_formatting_function $converter->default_formatting_function
($formatted)
+@var{$formatted} is a string describing the formatting
+function. Returns the default formatting function reference.
+@end defun
+
+The string that should be usedd 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 Special Element Body Formatting Functions
+@subsection Special Element Body Formatting Functions
+
+To register body formating user defined functions for special element
+(@pxref{Output Element Units}), the special elements types are used, as
described
+in @ref{Special Elements Types}.
+
+@float Table, Special Elements Types
+@multitable {Short table of contents} {}
+@headitem Special Element @tab Special Element Type
+@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 type}
+@end float
+
+Special element body formatting user defined functions are registered with
+@code{texinfo_register_formatting_special_element_body}:
+
+@defun texinfo_register_formatting_special_element_body
($special_element_type, @
+ \&handler)
+@var{$special_element_type} is the element type (@pxref{Special Elements
Types}).
+@var{\&handler} is the user defined function reference.
+@end defun
+
+The call of the user defined functions is:
+@deftypefn {Function Reference} {$text} special_element_body ($converter, @
+ $special_element_type, \%element)
+@var{$converter} is a converter object. @var{$special_element_type} is the
element type.
+@var{\%element} is the Texinfo
+element.
+
+The @var{$text} returned is the formatted special element body.
+@end deftypefn
+
+To call a special element body formatting function from user defined code, the
+function reference should first be retrieved using
@code{special_element_body_formatting}:
+
+@defun \&special_element_body_formatting
$converter->special_element_body_formatting ($special_element_type)
+@var{$special_element_type} is the element type. Returns the
+conversion function reference for @var{$type}, or undef if there is none,
+which should not happen for the special elements described in this manual.
+@end defun
+
+For example:
+@example
+my $footnotes_element_body
+ = &@{$converter->special_element_body_formatting('footnotes')@}($converter,
+ 'footnotes', $element);
+@end example
+
+It is possible to have access to the default conversion function reference.
+The function used is:
+
+@defun \&default_special_element_body_formatting
$converter->defaults_special_element_body_formatting ($special_element_type)
+@var{$special_element_type} is the element type. Returns the
+default conversion function reference for @var{$special_element_type}, or undef
+if there is none, which should not happen for the special elements described in
+this manual.
+@end defun
+
+@xref{Customizing Footnotes} for more on the footnotes special element body
+formatting. @xref{Contents and Short Table of Contents Customization}
+for more on the @code{contents} and @code{shortcontents} special elements
+body formatting. @xref{About Element Customization} for more
+on the @code{about} special elements body formatting.
+
+
+@node Mandatory Conversion Function Calls
+@chapter Mandatory Conversion Function Calls
+
+There are several conventions and constraints that user defined code should
+abide to, in order to comply with configuration option values, and also
+to have information correctly registered in the converter. Here we document
+the conventions that impact many user defined functions.
+
+
+@node Formatting HTML Element with Classes Opening
+@section Formatting HTML Element with Classes Opening
+
+Opening an HTML element with one or more classes should always be done through
+@code{html_attribute_class}:
+
+@deftypefun $element_open $converter->html_attribute_class ($html_element, @
+ \@@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.
+
+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 styles is also added. 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', ['category-def']);
+$category_result = $open.'>'.$category_result.'</span>'
+ if ($open ne '');
+
+my $result = $converter->html_attribute_class('em', [$cmdname,
'tex2jax_process']).'>'
+ .'\['.$content.'\]'.'</em>';
+@end example
+
+
+@node Closing Lone HTML Element
+@section Closing Lone HTML Element
+
+HTML elements with an opening element, but no closing element,
+such as @code{<img>} or @code{<link>} should be closed by calling
+@code{close_html_lone_element}:
+
+@deftypefun $html_element $converter->close_html_lone_element ($html_element)
+Close the @var{$html_element}, which can contain attributes, by prepending
+@samp{>} or @samp{/>} depending on the @code{USE_XML_SYNTAX} configuration
+variable value.
+@end deftypefun
+
+Examples of use:
+@example
+$description = $converter->close_html_lone_element(
+ "<meta name=\"description\" content=\"$description\"");
+@end example
+
+
+@node Substituting Non Breaking Space
+@section Substituting Non Breaking Space
+
+If a @code{ } can appear in formatted code,
+the corresponding text should be in a call to
@code{substitute_html_non_breaking_space},
+to take into account @code{ENABLE_ENCODING} and @code{USE_NUMERIC_ENTITY}
+configuration variables:
+
+@deftypefun $substituted_text $converter->substitute_html_non_breaking_space @
+ ($formatted_text)
+Substitute @code{ } according to configuration variables values.
+@end deftypefun
+
+This is not needed if the @code{non_breaking_space} information is taken from
+general informations (@pxref{Conversion General Information}).
+
+
+@node Conversion in String Context
+@section Conversion in String Context
+
+Conversion and formatting functions should test 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 $in_string $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
+@section 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}:
+
+@deftypefun $in_preformatted $converter->in_preformatted ()
+Return true if in preformatted context.
+@end deftypefun
+
+If in preformatted context, it is possible to get preformatted @@-commands and
+preformatted types nesting with @code{preformatted_classes_stack}:
+
+@deftypefun @@preformatted_nesting $converter->preformatted_classes_stack ()
+Returns 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::Common::preformatted_code_commands}
+hash can be used to determine if a preformatted command is to be formatted
+as code (@pxref{Texinfo::Common %preformatted_code_commands,,,tp_api}).
+
+@example
+my @@pre_classes = $converter->preformatted_classes_stack();
+foreach my $pre_class (@@pre_classes) @{
+ if ($Texinfo::Common::preformatted_code_commands@{$pre_class@}) @{
+ $result = '<code>' .$result. '</code>';
+ last;
+ @}
+@}
+@end example
+
+@xref{Simple Customization of Containers} on customizing containers
preformatted class.
+
+
+@node Text Formatting Context
+@section Text Formatting Context
+
+Formatting of text requires to use additional 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 $in_code $converter->in_code ()
+Return true if in code context. @xref{Init File Expansion Contexts}.
+@end deftypefun
+
+@item math
+
+@deftypefun $in_math $converter->in_math ()
+Return true if in math context. @xref{Init File Expansion Contexts}.
+@end deftypefun
+
+@item raw
+@deftypefun $in_raw $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 $in_verbatim $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 $in_upper_case $converter->in_upper_case ()
+Return true if in upper-case context, corresponding to @code{@@sc}.
+@end deftypefun
+
+@item non-breakable space
+
+@deftypefun $in_non_breakable_space $converter->in_non_breakable_space ()
+Return true if in non-breakable space context, corresponding to @code{@@w}.
+@end deftypefun
+@end table
+
+
+@node Basic Formatting Customization
+@chapter Basic Formatting Customization
+
+The following formatting functions references handle basic formatting
+and are called from diverse formatting and conversion functions. @xref{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_button_icon_img
+
+Called for an active direction, if @code{ICONS} is set, when formatting
+the navigation panel (@pxref{Simple Navigation Panel Customization}).
+
+@deftypefn {Function Reference} {$text} format_button_icon_img @
+ ($converter, $button, $icon, $name)
+@var{$button} is a button name, typically obtained from the @code{BUTTONS_NAME}
+configuration variable hash using a direction as key (@pxref{Output Element
+Unit Directions}). @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
+
+@item format_comment
+
+@deftypefn {Function Reference} {$text} format_comment @
+ ($converter, $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,tp_api}
+
+@item format_heading_text
+
+@deftypefn {Function Reference} {$text} format_heading_text @
+ ($converter, $command_name, \@@classes, $input_text, $level, $id, \%element)
+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 to and can be
+@code{undef}, for instance for special elements headings.
+
+@var{$id} is an optional identifier, and @var{\%element} is an optional
+Texinfo tree element associated with the heading.
+@end deftypefn
+
+This function reference can be called for @code{@@node} and sectioning
+commands, heading commands, tree units, special elements 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} {$text} program_string ($converter)
+This function reference should return the formatted program
+string.
+@end deftypefn
+
+@item format_protect_text
+@deftypefn {Function Reference} {$text} format_comment @
+ ($converter, $input_text)
+Return @var{$input_text} with HTML special characters and form feeds
+protected.
+@end deftypefn
+
+@xref{Texinfo::Convert::Converter $protected_text =
$converter->xml_protect_text($text),,
+Texinfo::Convert::Converter::xml_protect_text,tp_api}
+
+@item format_separate_anchor
+
+This function reference is called if there is no other element to
+add an identifier attribute to.
+
+@deftypefn {Function Reference} {$text} format_separate_anchor @
+ ($converter, $id, $class)
+@var{id} is the identifier.
+@var{$class} is an optional class to be used in a class attribute.
+
+Return an anchor with identifier @var{$id}.
+@end deftypefn
+@end table
+
+
+@node Getting and Passing Conversion Informations
+@chapter Getting and Passing Conversion Informations
+
+Dynamic formatting information on the conversion can be obtained from the
+converter.
+
+For advanced customization, it is also often necessary to pass information
+during conversion between different formatting functions or between
+different calls calls of the same function.
+
+These informations are often useful for the formatting of paragraph and
+preformatted containers and @@-comands such as @code{@@abbr},
@code{@@footnote},
+@code{@@node}, sectioning commands, @code{@@quotation} and @code{@@float}.
+
+
+@node Dynamic Converter Formatting Information
+@section Dynamic Converter Formatting Information
+
+
+To get the current paragraph and preformatted number, use
@code{paragraph_number}
+or @code{preformatted_number}:
+
+@deftypefun $number $converter->paragraph_number ()
+@deftypefunx $number $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 $command_name $converter->top_block_command ()
+Return the most recent block @@-command seen in the current formatting
+context.
+@end deftypefun
+
+To get the text filling and alignement context, determined by
@code{@@flushleft}
+or @code{@@center}, use @code{in_align}:
+
+@deftypefun $align_context $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_multi_expanded}:
+@deftypefun $multi_expanded_context_information $converter->in_multi_expanded
()
+Return a string representing the multiple expanded context, or @code{undef} if
+not in a multiple expanded context.
+@end deftypefun
+
+To get the location of an image file, use @code{html_image_file_location_name}:
+
+@deftypefun {($image_file, $image_basefile, $image_extension, $image_path)} @
+ $converter->html_image_file_location_name ($command_name, \%element, \@@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 are informations 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.
+@end deftypefun
+
+@xref{Conversion in Preformatted Context} for informations on getting
+preformatted commands and container types nesting informations.
+
+
+@node Opening and Closing Sectioning Commands Extent
+@section Opening and Closing Sectioning Commands Extent
+
+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, it can be 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 $converter->register_opened_section_level($level, $closing_text)
+@var{$level} is the sectioning command level. It is typically
+obtained with @code{section->@{'structure'@}->@{'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}:
+
+@defun @@closing_texts $converter->close_registered_sections_level($level)
+@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 in order.
+@end defun
+
+Example of use:
+@example
+my $level = $opening_section->@{'structure'@}->@{'section_level'@};
+$result .= join('', $converter->close_registered_sections_level($level));
+$converter->register_opened_section_level($level, "</div>\n");
+@end example
+
+
+@node Setting Up Content for the Next Text Container
+@section Setting Up Content for the Next Text Container
+
+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,
+as is the case for HTML.
+
+Formatted text may also be prepared based on informations
+in the Texinfo elements tree while out of the inline containers. 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 $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
+
+Pending formatted content can (and should) be cancelled when it is known that
+there is was no suitable inline container to be used to output the
+text. The function is @code{cancel_pending_formatted_inline_content}:
+
+@deftypefun $cancelled_content
$converter->cancel_pending_formatted_inline_content ($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 $content $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 $converter->associate_pending_formatted_inline_content (\%element,
$content)
+Associate @var{$content} to the Texinfo tree element @var{\%element}.
+@end defun
+
+@deftypefun $content $converter->get_associated_formatted_inline_content
(\%element)
+Get @var{$content} associated to the Texinfo tree element @var{\%element}.
+@end deftypefun
+
+
+@node Associating Information to an Output File Name
+@section Associating Information to an Output File Name
+
+To be able to retrieve information associated to the current file, in general
for
+the file begin or end formatting, @code{register_file_information} can be used
+to associate information, and @code{get_file_information} to retrieve that
+information.
+
+@defun $converter->register_file_information ($key, $value)
+Associate the current output file name file to the key @var{$key}, itself
+associated to the value @var{$value}.
+@end defun
+
+@deftypefun $value $converter->get_file_information ($key, $file_name)
+Return the value associated to the key @var{$key} and file name
@var{$file_name}.
+@end deftypefun
+
+
+@node Shared Conversion State
+@section Shared Conversion State
+
+For information shared among formatting functions without involving the
+converter, the function @code{shared_conversion_state} can be used both for
+initialization of shared information and to share information:
+
+@deftypefun $reference $converter->shared_conversion_state ($name,
$initialization)
+Return the reference @var{$reference} associated with @var{$name}.
+@var{$initialization} is only read the first time @var{$name} is seen and sets
+up the reference that will be reused afterwards. If @var{$initialization} is a
+scalar (string or integer, for example), a reference on a scalar is returned,
+the associated value being set to @var{$initialization}. Otherwise,
+@var{$initialization} should be a reference on a hash or on an array.
+@end deftypefun
+
+The converter is used to hold the information, but does not use nor write.
+
+Examples of use:
+@example
+my $explained_commands_hash
+ = $converter->shared_conversion_state('explained_commands', @{@});
+$explained_commands_hash->@{'key'@} = 'value';
+
+my $foot_num_reference =
$converter->shared_conversion_state('footnote_number', 0);
+$@{$foot_num_reference@}++;
+@end example
+
+
+@node Directions@comma{} Links@comma{} Labels and Files
+@chapter Directions, Links, Labels and Files
+
+Navigation headers, navigation panels, end or beginning of files, @code{@@xref}
+and similar @@-commands output, @code{@@menu}, @code{@@node}, sectioning
+commands, @code{@@printindex} and @code{@@listoffloats} formatting requires
+directions, links, labels and files informations.
+
+
+@node Target Commands Links@comma{} Texts and Associated Commands
+@section Target Commands Links, Texts and Associated Commands
+
+Target @@-commands are @@-comands 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 and footnotes are also associated to targets.
+
+To get the unique Texinfo tree element corresponding to a label, use
+@code{label_command}:
+
+@deftypefun \%element $converter->label_command ($label)
+Return the element in the tree that @var{$label} refers to.
+@end deftypefun
+
+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 $identifier $converter->command_id (\%target_element)
+Returns the id specific of the @var{\%target_element} tree element.
+@end deftypefun
+
+@deftypefun $file_name $converter->command_filename (\%target_element)
+Returns the file name of the @var{\%target_element} tree element.
+@end deftypefun
+
+@deftypefun $href $converter->command_href (\%target_element,
$source_filename, @
+ $source_command,
$specified_target)
+Return string for linking to @var{\%target_element} with @code{<a href>}.
+@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 $result $converter->command_text (\%target_element, $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 tree
+Return a Texinfo elements tree.
+
+@item tree_nonumber
+Return a Texinfo elements tree representing text without a chapter number
+being included.
+
+@item string
+Return text in string context. @xref{Init File Expansion Contexts}.
+@end table
+@end deftypefun
+
+To obtain the top level command element associated with the target element,
+@code{@@node} or sectioning element, use @code{command_root_element_command}:
+
+@deftypefun \%top_level_element $converter->command_root_element_command @
+ (\%target_element)
+Return the top level element @var{\%target_element} is in.
+@end deftypefun
+
+To get the node element associated with the target element, use
+@code{command_node}:
+
+@deftypefun \%node_element $converter->command_node (\%target_element)
+Return the node element associated with @var{\%target_element}.
+@end deftypefun
+
+
+@node Other Links@comma{} Headings and Associated Informations for Special
Elements
+@section Other Links, Headings and Associated Informations for Special Elements
+
+To get the href and the id of footnotes in the main document, use
+@code{footnote_location_target} and @code{footnote_location_href}:
+
+@deftypefun $target $converter->footnote_location_target (\%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
+
+@deftypefun $href $converter->footnote_location_href (\%footnote_element, @
+ $source_filename, $specified_target, $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 Commands Links@comma{} Texts and Associated Commands} to get
+the links information for the location of the footnotes text arguments output.
+
+To get the id and the href of sectioning commands in table of contents
+and short table of contents, use @code{command_contents_target} and
+@code{command_contents_href}:
+
+@deftypefun $target $converter->command_contents_target (\%sectioning_element,
@
+ $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 $href $converter->command_contents_href (\%sectioning_element, @
+ $contents_or_shortcontents, $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.
+@end deftypefun
+
+To determine if a tree unit element is the top element, use
+@code{element_is_tree_unit_top}:
+
+@deftypefun $is_tree_unit_top $converter->element_is_tree_unit_top (\%element)
+Returns true if the @var{\%element} Texinfo tree element is the tree unit
+Top element (@pxref{Output Element Units}) and is either associated with the
+@code{@@top} sectioning command or with the @code{Top} @code{@@node}.
+@end deftypefun
+
+To get informations on the special element type associated with
+an @@-command command name, use
@code{command_name_special_element_information}:
+
+@deftypefun {($special_element_type, \%special_element, $class_base,
$special_element_direction)} @
+ $converter->command_name_special_element_information ($command_name)
+@var{$command_name} is an @@-command name without the leading @@.
+If the @var{$command_name} is not associated with a special element,
+returns @code{undef}. Otherwise, return the @var{$special_element_type}
+(@pxref{Special Elements Types}), the @var{\%special_element} texinfo
+tree unit, a @var{$class_base} string for HTML class attribute
+and the @var{$special_element_direction} direction corresponding to that
special elements
+(@pxref{Output Element Unit Directions}).
+@end deftypefun
+
+In the current setup, special elements are associated with @code{@@contents},
+@code{@@shortcontents} and @code{@@summarycontents} and with @code{@@footnote}.
+
+
+@node Elements and Links for Directions
+@section Elements and Links for Directions
+
+@xref{Output Element Unit Directions} for the list of directions.
+
+To get the Texinfo tree unit special element associated with
+a special element direction, such as @samp{About} or @samp{Contents},
+use @code{special_direction_element}:
+
+@deftypefun \%special_element $converter->special_direction_element
($direction)
+Return the special element associated with direction @var{$direction}, or
+@code{undef} if the direction is not a special element direction or the special
+element is not output.
+@end deftypefun
+
+To get the Texinfo tree unit element associated with
+another global element direction, such as @samp{Top} or @samp{Index}, use
+@code{global_direction_element}:
+
+@deftypefun \%element $converter->global_target_elements_directions
($direction)
+Return the Texinfo tree unit element corresponding to direction
@var{$direction}, or
+@code{undef} if the direction is not a global direction.
+@end deftypefun
+
+The function that give link information on both relative and global
+elements is @code{from_element_direction}:
+
+@deftypefun $result $converter->from_element_direction ($direction, $type, @
+ $source_element, $source_filename)
+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{Element Direction Information Type}.
+
+@var{$source_element} is the tree unit element the link comes from. If not set,
+the current tree unit element is used. @var{$source_filename} is the file the
+link comes from. If not set, the current file name is used.
+@end deftypefun
+
+
+@node Element Counters in Files
+@section Element Counters in Files
+
+The position of the tree unit element being formatted in its file
+or the total number of elements output to a file is interesting, for instance
+to format end of files, decide which 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 $count $converter->count_elements_in_filename ($specification, @
+ $file_name)
+Return tree unit element 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 unit elements associated with @var{$file_name}
+having already been processed.
+@item remaining
+Return the number of unit elements associated with @var{$file_name}
+that remains to be processed.
+@item total
+Return the total number of element units associated with the file.
+@end table
+@end deftypefun
+
+
+@node Customizing Footnotes@comma{} Tables of Contents and About
+@chapter Customizing Footnotes, Tables of Contents and About
+
+@node Customizing Footnotes
+@section Customizing Footnotes
+
+@code{NUMBER_FOOTNOTES} and @code{NO_NUMBER_FOOTNOTE_SYMBOL} configuration
variables
+can be used to change the footnotes formatting. To customize further footnotes
+conversion, the conversion of footnotes in document and some formatting
+references can be redefined.
+
+@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 location they appear in the
+document and the functions where their argument is converted, two
+functions are available, @code{register_footnote} to be called where they
+appear in the document, andd @code{get_pending_footnotes} to be called where
they are
+formatted:
+
+@defun $converter->register_footnote(\%element, $footnote_id, @
+ $foot_in_doc_id, $number_in_doc, $footnote_location_filename,
$multi_expanded_region)
+@var{\%element} is the footnoote texinfo tree element. @var{$footnote_id}
+is the location identifier where the footnote arguments are expanded.
@var{$foot_in_doc_id}
+is the location identifier where the footnote appears in the document.
+@var{$number_in_doc} is the symbol used to format the footnote in the document.
+@var{$footnote_location_filename} is the filename of the tree unit element 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{Dynamic Converter Formatting Information}).
+@end defun
+
+@code{register_footnote} is normally called in the @code{@@footnote}
+@@-command conversion footnote reference. This conversion function
+can call @code{command_href} to link to the location where the footnote
+text will be expanded (@pxref{Target Commands Links@comma{} Texts and
Associated Commands}).
+
+@deftypefun {@@pending_footnotes_information}
$converter->get_pending_footnotes ()
+Returns in @var{@@pending_footnotes_information} the informations gathered
+in @code{register_footnote}. Each of the array 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{Specific formating Functions}):
+
+@deftypefn {Function Reference} $footnotes_sequence format_footnotes_sequence @
+ ($converter)
+Formats and returns the footnotes that need to be formatted. This function
+normally calls @code{get_pending_footnotes}. This function can call
+@code{footnote_location_href} (@pxref{Other Links@comma{} Headings and
+Associated Informations for Special Elements}) to link to the location
+in the document where the footnote appeared.
+@end deftypefn
+
+If footnotes are in a separate element unit (@pxref{Output Element Units}), the
+default footnote special element body formatting function calls
+@code{format_footnotes_sequence} (@pxref{Special Element
+Body Formatting Functions}).
+
+If the footnotes are not in a separate element unit, or there is no separate
element because
+there is only one tree unit element or no tree unit element, 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} $footnotes_segment format_footnotes_segment @
+ ($converter)
+Returns the footnotes formatted. In the default case, the function reference
+calls @code{format_footnotes_segment} and also sets up a header with
+@code{format_heading_text} (@pxref{Basic Formatting Customization}), using the
+configuration variables @code{FOOTNOTE_END_HEADER_LEVEL} and
+@code{SPECIAL_ELEMENTS_HEADING} with the @code{footnotes} special element type
+key.
+@end deftypefn
+
+
+@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
+
+To begin with, the table of contents and short table of contents can
+be made to appear at different locations in the document.
+
+@vindex CONTENTS_OUTPUT_LOCATION
+By default, the configuration variable
+@code{CONTENTS_OUTPUT_LOCATION} is set to @samp{inline}, specifying
+that the tables of contents are not output as separate elements but instead
+where the corresponding @@-command, for example @code{@@contents}, is set.
+This behavior is consistent with @command{texi2dvi}.
+
+If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{separate_element},
+the tables of contents are output in separate elements, 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.
+
+If @code{CONTENTS_OUTPUT_LOCATION} is set to @samp{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}.
+
+Next, the following variables allow for some useful control of the
+formatting of table of contents and short table of contents:
+
+@vtable @code
+@item BEFORE_TOC_LINES
+Inserted before the table of contents text.
+
+@item AFTER_TOC_LINES
+Inserted after the table of contents text.
+
+@item BEFORE_SHORT_TOC_LINES
+Inserted before the short table of contents text.
+
+@item AFTER_SHORT_TOC_LINES
+Inserted after the short table of contents text.
+
+@end vtable
+
+Finally, the following function reference provides even more control
+over the table of contents and short table of contents formatting
+reference:
+
+@deftypefn {Function Reference} $toc_result format_contents @
+ ($converter, $command_name, \%element, $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 the where the
+formatting happens, for links. If unset, the current file name is used.
+
+Structuring informations are used in the default case to
+format the table of contents (@pxref{Conversion General Information}).
+The functions used for links are used in the default case, such as
+@code{command_contents_href} (@pxref{Other Links@comma{} Headings and
+Associated Informations for Special Elements}) and @code{command_href}
+(@pxref{Target Commands Links@comma{} Texts and Associated Commands}).
+
+Return formatted table of contents or short table of contents.
+
+In addition to the configuration variables described just above,
+@code{SHORT_TOC_LINK_TO_TOC} and @code{NUMBER_SECTIONS} could be relevant.
+@end deftypefn
+
+If contents are in a separate element unit (@pxref{Output Element Units}), the
default contents
+and shortcontents special element body formatting function calls
+@code{format_contents} (@pxref{Special Element Body Formatting Functions}).
+Otherwise, @code{format_contents} is called in diverse situations,
+depending on the @code{CONTENTS_OUTPUT_LOCATION} value.
+
+
+@node About Element Customization
+@section About Element Customization
+
+@cindex Customization of about element
+@cindex About element, customizing
+
+The default About element has an explanation of the buttons used in
+the document, controlled by @code{SECTION_BUTTONS}.
+The formatting of this text may be influenced by
+@code{BUTTONS_GOTO}, @code{BUTTONS_NAME}, @code{ACTIVE_ICONS}
+@pxref{Simple Navigation Panel Customization}).
+
+@vindex BUTTONS_EXAMPLE
+@code{BUTTONS_EXAMPLE} also influences the formatting. The keys of this hash
+are element directions (@pxref{Output Element Unit Directions}) and the values
+are the text from the About example, typically a section number.
+
+If the above is not enough and you want to control exactly the
+formatting of the about text, the @code{about} special element body reference
+function may be overridden (@pxref{Special Element Body Formatting Functions}).
+
+
+@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}.)
+
+In the event that your needs are not met by changing the navigation buttons
+(@pxref{Simple Navigation Panel Customization}), you can completely control the
+formatting of navigation panels by redefining function references.
+@xref{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.
+
+
+@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
+
+All the formatting functions take a converter object as first argument.
+
+The overall display of navigation panels is controlled via this
+function reference, @code{format_navigation_header}:
+
+@deftypefn {Function Reference} $navigation_text format_navigation_header @
+ ($converter, \@@buttons, $command_name, \%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 elements.
+
+Returns the formatted navigation header and panel. The navigation
+panel itself can be formatted with a
+call to @code{&@{$self->formatting_function('format_navigation_panel')@}}.
+
+The configuration variable @code{VERTICAL_HEAD_NAVIGATION} should be relevant.
+@end deftypefn
+
+The navigation panel display is controlled via @code{format_navigation_panel}:
+
+@deftypefn {Function Reference} $navigation_text format_navigation_panel @
+ ($converter, \@@buttons, $command_name, \%element,
$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{&@{$self->formatting_function('format_button')@}}.
+@end deftypefn
+
+The function reference @code{format_button} does the formatting of
+one button:
+
+@deftypefn {Function Reference} $formatted_button format_button @
+ ($converter, $button)
+@var{$button} holds the specification of the button (@pxref{Buttons Display}).
+Returns the formatted result in @var{$formatted_button}.
+
+The buttons images can be formatted with @code{format_button_icon_img}
+(@pxref{Basic Formatting Customization}).
+
+Configuration information described in @ref{Simple Navigation Panel
Customization}
+such as @code{BUTTONS_TEXT}, @code{BUTTONS_NAME}, @code{BUTTONS_GOTO},
+@code{USE_ACCESSKEY}, @code{BUTTONS_ACCESSKEY},
+@code{USE_REL_REV} and @code{BUTTONS_REL} can be relevant for the
+formatting of a 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
+
+All the formatting functions take a converter object as first argument.
+
+By default, the function associated with @code{format_element_header}
+formats the header and navigation panel of a tree unit element.
+
+@deftypefn {Function Reference} $formatted_header format_element_header @
+ ($converter, $command_name, \%element, \%tree_unit_element)
+@var{\%element} is the element in which the navigation header is formatted
+(sectioning command, @code{@@node} or special element). @var{$command_name} is
+the associated command name. It may be @code{undef} for special elements.
+@var{\%tree_unit_element} is the associated tree unit element (@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{&@{$self->formatting_function('format_navigation_header')@}}. It is also
+possible to format directly the navigation panel, depending on configuration
+options and location in file.
+@end deftypefn
+
+Similarly, the function associated with @code{format_element_footer}
+formats the footer and navigation panel of a tree unit element.
+
+@deftypefn {Function Reference} $formatted_footer format_element_footer @
+ ($converter, $tree_unit_type, \%tree_unit_element, $content)
+@var{\%tree_unit_element} is the tree unit element element in which the
navigation
+footer is formatted. @var{$tree_unit_type} is the associated
+type. @var{$content} is the formatted element content.
+
+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{&@{$self->formatting_function('format_navigation_header')@}}.
+
+Many configuration variables values may be interesting for the footer
+formatting, such as @code{SPLIT}, @code{HEADERS}, @code{DEFAULT_RULE},
+@code{BIG_RULE}, @code{WORDS_IN_PAGE} or @code{PROGRAM_NAME_IN_FOOTER}.
+@end deftypefn
+
+
+@node Heading Commands and Tree Elements Formatting
+@chapter Heading Commands and Tree Elements Formatting
+
+The configuration variables
+@code{CONTENTS_OUTPUT_LOCATION},
+@code{CHAPTER_HEADER_LEVEL}, @code{TOC_LINKS} and @code{FORMAT_MENU}
+may be used to change the sectioning commands conversion.
+@xref{@command{texi2any} Configuration Variables}.
+
+@code{@@node} and sectioning default conversion function call
+@code{format_heading_text} (@pxref{Basic Formatting Customization})
+and @code{format_element_header} (@pxref{Element Header and Footer
+Formatting}), as well as functions opening and closing sectioning commands
+extent (@pxref{Opening and Closing Sectioning Commands Extent}). 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}).
+
+Tree unit elements default conversion involves calling the formatting reference
+@code{format_element_footer} (@pxref{Element Header and Footer Formatting}).
+The conversion for these elements with type @code{unit} can be be replaced by
+user defined functions for a precise control of conversion (@pxref{Type Tree
+Element Conversion Functions}).
+
+Special elements conversion is achieved by calling
+@code{special_element_body_formatting} (@pxref{Special Element 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}). Specific configuration variable hashes taking
+special element types as keys are used in special elements formatting, such as
+@code{SPECIAL_ELEMENTS_CLASS} or @code{SPECIAL_ELEMENTS_HEADING}. The
+conversion for these elements with type @code{special_element_type} can be be
+replaced by user defined functions for a precise control of conversion
+(@pxref{Type Tree Element Conversion Functions}).
+
+
+@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 element 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{Specific formating Functions} for information on how to register and get
+the functions references.
+
+
+@node Customizing HTML File Beginning
+@section Customizing HTML 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.
+
+@vindex BODYTEXT@r{, in customization}
+@cindex @code{<body>} tag, attributes of
+The @code{<body>} element attributes may be set by defining the
+configuration variable @code{BODYTEXT}.
+
+@vindex ENCODING_NAME
+@cindex Encoding, in HTML output
+By default, the encoding name from @code{ENCODING_NAME} is used. If
+this variable is not defined, it is automatically determined
+(@pxref{Init File Encodings}).
+
+@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
+configuration variable) is used in the header
+(@pxref{documentdescription}).
+
+@vindex LINKS_BUTTONS@r{, in customization}
+@vindex BUTTONS_REL@r{, in customization}
+@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 @code{BUTTONS_REL} determines the link type associated with
+the @code{rel} attribute. @xref{Simple Navigation Panel Customization}.
+
+The configuration variables
+@code{SECTION_NAME_IN_TITLE},
+@code{PACKAGE_AND_VERSION}, @code{PACKAGE_URL} and other similar variables,
+@code{HTML_MATH} and @code{INFO_JS_DIR}
+may also be used to change the page header formatting.
+@xref{@command{texi2any} Configuration Variables}.
+
+The following function references give full control over the
+page header formatting done at the top of each HTML output file.
+
+@deftypefn {Function Reference} $file_begin format_begin_file ($converter, @
+ $filename, \%tree_unit_element)
+@cindex @code{<body>} tag, outputting
+@var{$filename} is the name of the file output.
+@var{\%tree_unit_element} is the first tree unit element of the file.
+This function should print the page header, in HTML,
+including the @code{<body>} element.
+@end deftypefn
+
+
+@node Customizing HTML Page Footers
+@section Customizing HTML Page Footers
+
+@cindex Customizing HTML page footers
+@cindex Footer, customizing for HTML
+
+@vindex PRE_BODY_CLOSE
+You can define the variable @code{PRE_BODY_CLOSE} to add text just
+before the HTML @code{</body>} element. Nothing is added by default.
+
+@vindex PROGRAM_NAME_IN_FOOTER
+If @code{PROGRAM_NAME_IN_FOOTER} is set, the date and name of the
+program that generated the output are output in the footer.
+
+The configuration variables @code{JS_WEBLABELS} and @code{JS_WEBLABELS_FILE}
+are also used in the page footer formatting. @xref{@command{texi2any}
+Configuration Variables}.
+
+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} $file_end format_end_file ($converter,
$filename)
+@var{$filename} is the name of the file output.
+@cindex @code{</body>} tag, outputting
+This function should print the page footer, including
+the @code{</body>} element.
+@end deftypefn
+
+
+@node Titlepage@comma{} CSS and Redirection Files
+@chapter Titlepage, CSS and Redirection Files
+
+@node HTML Title Page Customization
+@section HTML Title Page Customization
+
+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 not set in the default case. If @code{SHOW_TITLE} is not set, no title is
output.
+@code{SHOW_TITLE} is set in the default case.
+
+The following function reference provides full control on the ``title page''
+formatting:
+
+@deftypefn {Function Reference} $title_page format_titlepage ($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{Conversion General Information}).
+@end deftypefn
+
+If @code{USE_TITLEPAGE_FOR_TITLE} is set but there is no output of
+@code{format_titlepage} the default formatting reference falls back to
+@code{simpletitle}.
+
+@node Customizing CSS
+@section Customizing the CSS lines
+
+@xref{Simple Customization of CSS Rules and Imports} for some information on
CSS customization.
+
+The CSS @var{element}.@var{class} that appeared in a file, gathered through
+@code{html_attribute_class} (@pxref{Formatting HTML Element with Classes
+Opening}) are available from the @code{html_get_css_elements_classes}
functions:
+
+@deftypefun @@css_element_classes $converter->html_get_css_elements_classes @
+ ($file_name)
+Returns an array containing @code{element.class} pairs of elements and classes
+appearing on @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} $css_lines format_css_lines ($converter, @
+ $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}
+and @code{css_get_info} (@pxref{Simple Customization of CSS Rules and Imports})
+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}}).
+
+It is possible to change completely how node redirection pages
+are generated by redefining the following function reference:
+
+@deftypefn {Function Reference} $node_redirection_file_content @
+ format_node_redirection_page ($converter, \%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}).
+
+Returns the content of the node redirection file.
+@end deftypefn
+
+@c NOTE format_frame_files is not documented, we do not want users to use/set
this
+@c we want frames to disappear
+
+@node Specific Functions for Specific Elements
+@chapter 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, tp_api}.
+
+@item @code{@@verbatiminclude}
+@xref{Texinfo::Convert::Utils $tree =
expand_verbatiminclude($registrar@comma{} $configuration_informations@comma{}
$verbatiminclude),,
+Texinfo::Convert::Utils::expand_verbatiminclude, tp_api}.
+
+@item @code{@@def*} @@-commands
+@xref{Texinfo::Convert::Utils $arguments =
definition_arguments_content($element),,
+Texinfo::Convert::Utils::definition_arguments_content, tp_api}.
+@xref{Texinfo::Convert::Utils $tree = definition_category($converter@comma{}
$def_line),,
+Texinfo::Convert::Utils::definition_category, tp_api}.
+
+@item @code{@@float}
+@xref{Texinfo::Convert::Converter ($caption@comma{} $prepended) =
$converter->float_name_caption ($float),,
+Texinfo::Convert::Converter::float_name_caption, tp_api}.
+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, tp_api}.
+Can be called as @code{$converter->xml_accent}.
+
+@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, tp_api}.
+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, tp_api}.
+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, tp_api}. 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_informations@comma{} $element),,
+Texinfo::Common::set_informative_command_value, tp_api}.
+
+@item heading commands, such as @code{@@subheading}
+@xref{Texinfo::Common $level = section_level($section),,
+Texinfo::Common::section_level, tp_api}. This function would work
+for sectioning commands too, but for sectioning commands,
+@code{section->@{'structure'@}->@{'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, tp_api}.
+
+@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 $text_for_css
$converter->html_convert_css_string_for_list_mark(\%element, @
+
$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} special converter functions
+used for normalization of labels can be used on Texinfo elements trees to
+obtain strings that are unique and can be used in attributes.
+@xref{Texinfo::Convert::NodeNameNormalization,,,tp_api}.
+
+
+@bye
diff --git a/tp/TODO b/tp/TODO
index 57a538b134..5e2b575c14 100644
--- a/tp/TODO
+++ b/tp/TODO
@@ -30,66 +30,6 @@ Some private function used in conversion
_convert_printindex_command
_new_document_context
-To document:
------------
-
-
-
-Nav
-@menu, sectioning commands, navigation panel, @listoffloats, @printindex
-
-$self->element_is_tree_unit_top()
-Texinfo::Structuring::section_level_adjusted_command_name
-Texinfo::Common::section_level()
-$self->count_elements_in_filename($spec, filename)
-
-used in _direction_href_attributes, _get_links
-'BUTTONS_ACCESSKEY' 'BUTTONS_REL'
-'LINKS_BUTTONS'
-
-from_element_direction
-command_target command_filename command_string command_id command_href
-command_contents_href command_contents_target
-special_direction_element
-command_name_special_element_information
-command_root_element_command label_command
-footnote_location_target footnote_location_href
-
- 'format_button' => \&_default_format_button,
- 'format_element_header' => \&_default_format_element_header,
- 'format_element_footer' => \&_default_format_element_footer,
- 'format_navigation_header' => \&_default_format_navigation_header,
- 'format_navigation_panel' => \&_default_format_navigation_panel,
-
-Normal Unit Elements
-Special Elements
-
-used in _contents_inline_element
-'SPECIAL_ELEMENTS_DIRECTIONS' 'SPECIAL_ELEMENTS_CLASS'
'SPECIAL_ELEMENTS_HEADING'
-
-register_footnote
-get_pending_footnotes
-
- 'format_contents' => \&_default_format_contents,
- 'format_footnotes_segment' => \&_default_format_footnotes_segment,
- 'format_footnotes_sequence' => \&_default_format_footnotes_sequence,
-
-
- 'format_begin_file' => \&_default_format_begin_file,
- 'format_end_file' => \&_default_format_end_file,
-
-
-Other
-
- 'format_css_lines' => \&_default_format_css_lines,
- 'format_titlepage' => \&_default_format_titlepage,
-
- 'format_node_redirection_page' => \&_default_format_node_redirection_page,
-
- 'format_frame_files' => \&_default_format_frame_files,
-$self->html_get_css_elements_classes($filename);
-
-
Profiling
=========
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: * texinfo/doc/customization_api.texi: draft of the HTML customization API documentation.,
Patrice Dumas <=