doc/texi2oldapi.texi

\input texinfo.tex
@c history and some customization sections from the texi2html manual
@c (only partly edited), excised.
@c
@c The information in the 'texi2any Output Customization' Appendix has been
@c merged in texi2any_api.texi when relevant, and therefore should
@c not be of interest anymore.
@c
@c Here (for now) for archival purposes.
@c
@c   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
@c   2001, 2002, 2003, 2004, 2009, 2010, 2011, 2013 Free Software
@c   Foundation, Inc.
@c
@c See texinfo.texi for copying conditions.
@c
@c can be converted in source with:
@c TEXINDEX=${top_builddir}/../../../../texindex/texindex ; export TEXINDEX ; TEXINDEX_SCRIPT=${top_srcdir}/../../../../texindex/texindex.awk ; export TEXINDEX_SCRIPT ; ../util/texi2dvi --pdf texi2oldapi.texi --build-dir=texi2oldapi.t2p
@c
@c ../tp/texi2any.pl --no-validate texi2oldapi.texi

@contents

@node Top
@top Archived information on Texi2HTML and early texi2any API

The early texi2any API described in @ref{texi2any Output Customization}
dates back to 2010/2012 and has been obsoleted by the texi2any_api
manual (@pxref{,,, texi2any_api, GNU Texinfo @command{texi2any}
Output Customization}).

@node Texi2HTML
@appendix Texi2HTML history and relations with @command{makeinfo}

In 2010 Texi2HTML was merged in GNU Texinfo.  The resulting program, however
was never released.  Some informations gathered at the time of the merge are
retained here, mainly for historical purposes.

@menu
* Texi2HTML history::               Texi2HTML history and makeinfo.
* Texi2HTML texi2any differences::
* Texi2HTML changes::               History of incompatibilities.
@end menu

@node Texi2HTML history
@appendixsec Texi2HTML history and merge in Texinfo

In early 1998 @command{makeinfo} wasn't able to produce
HTML output format, but people still wanted documentation in
HTML.  This was the birthing hour for @command{texi2html},
with original author Lionel Cons.  The basic purpose of 
@command{texi2html} was to convert Texinfo documents into HTML.

Since then, HTML support in @command{makeinfo} improved, but
@command{texi2html} was still stronger in some areas, including the degree to
which it allows customization.  After being briefly maintained by Karl
Berry in 1999, Olaf Bachmann was the maintainer until 2000, adding many 
features.  Adrian Aichner and Derek Price took over maintainance in 2001 
and Derek was the maintainer from 2003 to 2010, with some help from 
Patrice Dumas.

In 2010, @command{texi2html}, then hosted
at @uref{http://www.nongnu.org/texi2html/} was made
compatible with @command{makeinfo}, losing the focus on HTML to become a
more generic translator, and merged in 
@uref{https://www.gnu.org/software/texinfo/, GNU Texinfo} to
replace @command{makeinfo} in C.  That implementation, however, was
never released and was abandoned in favor of another implementation
that parses the Texinfo input into a tree for processing.


@node Texi2HTML texi2any differences
@appendixsec Differences between @command{texi2html} and @command{texi2any} invokation

There are some differences between an invokation of @command{texi2any} or
@command{makeinfo} and @command{texi2html}.  With @command{texi2html}:
@itemize @bullet
@item HTML is the default output, as with @option{--html}.
@item Command line is not parsed exactly like GNU getopt does. To be on the safe
side:
@itemize @bullet
@item always use two dashes for long options.
@item do not bundle short options, that is, use @code{-v -o -P} and not @code{-voP}.
@end itemize
@item Some options, although obsoleted are still available.
@item The defaults for the HTML formatting may be slightly different. 
Have a look at the function @code{t2h_default_set_variables_texi2html} 
in @file{texi2html.pm}.
@end itemize

@node Texi2HTML changes
@appendixsec Texi2HTML incompatibilities with previous versions

@command{texi2html} has accumulated a lot of incompatibilities in previous
versions, and more were added after the merge in Texinfo.  Many 
incompatibilities were introduced in version 1.68.  API changed also a 
lot between 1.78 and 1.80. Between 1.82 and 5.0 API changed also quite 
a bit, and more importantly, the whole internationalization handling was 
changed.

@itemize @bullet
@item API changes between 5.0 and later versions
@itemize @bullet

@item no default initialization file for latex2html.  ALso don't search in 
directories for the latex2html initialization file, simply use the file 
given in argument.

@item  don't show menu with @option{--no-headers} as said in the makeinfo documentation.

@item obsolete the @option{--iso} command line option.

@item obsolete texi2html specific variables. Here is the list with the associated
  configuration variables that may be set instead, with @option{--set-init-variable}:
@multitable {@option{--ignore-preamble-text}} {@code{IGNORE_PREAMBLE_TEXT}}
@item  @option{--toc-links}               @tab @code{TOC_LINKS}
@item  @option{--short-ext}               @tab @code{SHORTEXTN}
@item  @option{--prefix}                  @tab @code{PREFIX}
@item  @option{--short-ref}               @tab @code{SHORT_REF}
@item  @option{--idx-sum}                 @tab @code{IDX_SUMMARY}
@item  @option{--def-table}               @tab @code{DEF_TABLE}
@item  @option{--ignore-preamble-text}    @tab @code{IGNORE_PREAMBLE_TEXT}
@item  @option{--html-xref-prefix}        @tab @code{EXTERNAL_DIR}
@item  @option{--l2h}                     @tab @code{L2H}
@item  @option{--l2h-l2h}                 @tab @code{L2H_L2H}
@item  @option{--l2h-skip}                @tab @code{L2H_SKIP}
@item  @option{--l2h-tmp}                 @tab @code{L2H_TMP}
@item  @option{--l2h-file}                @tab @code{L2H_FILE}
@item  @option{--l2h-clean}               @tab @code{L2H_CLEAN}
@item  @option{--use-nodes}               @tab @code{USE_NODES}
@item  @option{--monolithic}              @tab @code{MONOLITHIC}
@item  @option{--top-file}                @tab @code{TOP_FILE}
@item  @option{--toc-file}                @tab @code{TOC_FILE}
@item  @option{--frames}                  @tab @code{FRAMES}
@item  @option{--menu}                    @tab @code{FORMAT_MENU}
@item  @option{--debug}                   @tab @code{DEBUG}
@item  @option{--doctype}                 @tab @code{DOCTYPE}
@item  @option{--frameset-doctype}        @tab @code{FRAMESET_DOCTYPE}
@item  @option{--test}                    @tab @code{TEST}
@end multitable

@item remove completly $INVISIBLE_MARK, $USE_GLOSSARY, $CHECK, $EXPAND, 
  $ENCODING, $CENTER_IMAGE, $HREF_DIR_INSTEAD_FILE, $USE_MENU_DIRECTIONS
  they have been obsolete, sometimes for many years.
@item DATE is now set as today, DOCUMENT_ENCODING as documentencoding,
  extension as EXTENSION and DOCUMENT_DESCRIPTION as documentdescription.
@item Don't use perl variables for configuration variables anymore. Instead, 
  they should be set by 
  @code{set_from_init_file('VARIABLE', value);}.
  For example 
@example
$SPLIT = 'node';
@end example
  should be replaced by
@example
set_from_init_file('SPLIT', 'node');
@end example
@item configuration variables are not in @code{Texi2HTML::THISDOC} directly 
  anymore, but in @code{Texi2HTML::THISDOC@{'variables'@}->@{$var@}}. they 
  should be accessed
  through @code{get_conf($var)}.
@item remove $Texi2HTML::THISDOC@{'program_authors'@}. $Texi2HTML::THISDOC@{'program_and_version'@}
  holds the program and version, while $Texi2HTML::THISDOC@{'program'@} is only
  the program name.
@end itemize
@item API changes between 1.82 and 5.0:
@itemize @bullet
@item complex format handling API changed. $complex_format_map is replaced by 
  a real hash %complex_format_map and the begin and end are no more 
  evaluated.
@item In the default case a gettext-like framework is now used for in document
  string translations. The old framework is still available by setting 
  $I18N_PERL_HASH.
@item Information that can be set by @@-commands should now be accessed
  through get_conf.
@item $format_list_item_texi should now modify directly the @@item argument
  and apply the @@-command given as @@table argument. Correspondingly, 
  some arguments of $table_item have been removed.
@item Formatting of titlepage changed, and @@title, @@subtitle and @@author
  are now handled by $line_command
@item $SEPARATED_FOOTNOTES has been replaced by $FOOTNOTESTYLE, that takes the 
  same argument than @@footnotestyle.
@item replace $LANG by $DOCUMENTLANGUAGE.
@item replace $DO_CONTENTS by $CONTENTS and $DO_SCONTENTS by $SHORTCONTENTS.
@item replace $TRANSLITERATE_NODE by $TRANSLITERATE_FILE_NAMES.
@item replace $SECTION_NAVIGATION by $HEADERS.
@item @@verbatiminclude is now a $raw command argument distinct from @@verbatim.
@item @@direntry is formatted like a menu and passed down to $menu_command.
@item add $NODE_FILENAMES to use node names for files associated with nodes, 
  such that $NODE_FILES is only means creating redirection files.
@item Remove the user from footer, and the corresponding USER variable and
  $Texi2HTML::THISDOC@{user@}.
@item Don't treat _setfilename as a value set. It should be available through
  get_conf. Same for all the other @@-commands previously avaiable as
  values.
@item change in class attribute for html elements:
for ul to class "no-bullet" ($NO_BULLET_LIST_ATTRIBUTE). @@top 
and @@centerchap have now their command name as class.
@@node heading class is now "node-heading", instead of "node".
The whole header is in an element with class "header" 
(was "node" when !$HEADER_IN_TABLE).
@item print_element_header is obsoleted, 
things should be directly done in element_heading.
@item Add 'inline_attribute' for an XML attribute that should be closed at
  paragraph end and reopened at paragraph begin. Consequently the closing
  and opening of 'attribute' isn't done anymore in paragraph and 
  preformatted.
@item USE_ISO now only determines if @code{''}, @code{``} @code{---} and @code{--} are transformed
  into entities. t2h_default_set_iso_symbols sets or unsets USE_ISO,
  %things_map/%pre_map/%simple_format_simple_map_texi, 
  $OPEN_QUOTE_SYMBOL and $CLOSE_QUOTE_SYMBOL.
  %iso_symbols is unused now.
@item change in the normal_text function reference API, now there is an 
  input variable true if in @@math.
@item change the external_ref API, fourth argument is now the file name and
  add the node as an extra argument.
@item rename $Texi2HTML::THISDOC@{css_lines@} as $Texi2HTML::THISDOC@{css_rule_lines@}
@end itemize
@item API changes between 1.78 and 1.80: 
@itemize @bullet
@item what was done in the beginning of the $print_section 
function reference is now done in $print_element_header.
@item there is a new argument for $normal_text.
@item there is a new argument for $menu_link and $simple_menu_link, and the 
name argument is always set, even if there is no explicit name. The new 
argument is true if there really was an explicit name.
@item $internal_ref and $external_ref don't change inforef to xref anymore.
@item in $table_item the text is not formatted with the format command,
  the text_formatted argument is.
@item definition index entries are now formatted with $definition_index_entry,
  not with $definition_category anymore.
@item $printindex is called if an index appears, even if the index is not 
defined or there are no index entries.
@item  new argument (@@-command name) for $quotation and $quotation_prepend_text.
@item change in the heading API. THIS_HEADER is not used anymore.
  New function reference, element_heading  to format a node or a section 
  heading, including navigation and label. Accordingly, print_Top and 
  one_section don't print the element header anymore. Also it is
  reported if the element is a new element, is the main element and
  more arguments, and top element heading is always done in heading.
@item  print_element_header and print_navigation now return their result.	
@item the @code{copying} key of %Texi2HTML::THISDOC is now called
@code{copying_comment}.
@item TOC_LIST_ATTRIBUTE is now called NO_BULLET_LIST_ATTRIBUTE.
@item TOC_LIST_STYLE is now called NO_BULLET_LIST_STYLE.
@item the $unknown function reference has a new argument, the pass number.
@item @option{--sec-nav} is replaced by @option{--headers}.
@item @option{--Verbose} is replaced by @option{--verbose}.
@item @option{--lang} is replaced by @option{--document-language}.
@item @option{--separated-footnotes} is replaced by @option{--footnote-style}.
@item @option{--lang} is replaced by @option{--document-language}.
@item @code{&$menu_comment} is removed, @code{menu_comment} is now handled
  like an @@-command.
@item @code{@@detailmenu} is now formatted more like @code{@@menu}, and
the @code{&$menu} function reference is replaced by @code{&$menu_command}.
@code{&$menu} is kept for backward compatibility. If @code{&$menu} is defined, 
@code{@@detailmenu} is ignored.
@item the API for the formatting of menus completly changed. $simple_menu_link
  is removed, everything should be done in $menu_link.
@item image API changed, and is unstable, so not documented.
@item image file paths are not completed anymore in the default case. 
  The previous
  behaviour can be restored with @code{$COMPLETE_IMAGE_PATHS} set to true.
@item in %misc_command @samp{texi} is not used anymore. The value and macros
are expanded as they should be unconditionnally.
@item there is a new 'style' key in $complex_format_map, to be able to 
  differentiate complex formats inheriting fonts and code_style (like 
  @@format, @@display).
@item $EXTENSION should be undef if one doesn't want an extension to be added.
@item THISDOC@{'title'@} and similar are now for @@title since only one @@title
  should appear in the document. @@settitle is tried first to set fulltitle.
@item Configuration variables are modified anymore, instead the variable
  value is put in $Texi2HTML::THISDOC@{'VAR'@}. This is the case for
  DO_CONTENTS, DO_SCONTENTS, CSS_LINES, BODYTEXT, DOCUMENT_DESCRIPTION,
  DOCUMENT_ENCODING, IN_ENCODING, ENCODING_NAME, OUT_ENCODING.

  For example, if $CSS_LINES is defined, the value is put in 
  $Texi2HTML::THISDOC@{'CSS_LINES'@} which is used for formatting, and if
  $CSS_LINES is not defined, $Texi2HTML::THISDOC@{'CSS_LINES'@} is 
  autodetected.
@item  When there is no section and $USE_NODES is not set don't split by node.
This behaviour and the previous aren't documented, so it could change
in the future.
@end itemize
@item API changes between 1.76 and 1.78: 
@itemize @bullet
@item paragraph has new arguments
with indentation information, added as the third argument, and
other context information. The formatting linked with commands
opened before the paragraph and closed after the paragraph are done
in the formatting function. Similar
things are done for preformatted.
@item normal_text 
changed completely. There
are much more arguments to give informations about the context, and
normal_text now does more text manipulation. 
@item New arguments for image the alt text, the height and width, 
the path to working dir and the path to image file relative 
to working dir. More image formatting is
done in the formatting function.
@item New argument for empty_line.
@item End of line removal is done in formatting function of definition line
formatting.
@item node_file_name now should only returns the node file, since the 
redirection file isn't used anymore. element_file_name only is used for 
file names, whatever NODE_FILES is.
@end itemize
@item changes between 1.66 and 1.68:
@itemize @bullet
@item When the manual is split the default is to put resulting files in 
a directory with name the manual file basename (previously they were left in
 the current directory). To avoid that, call texi2html with 
@option{-output .}. This has been changed to be compatible with 
@command{makeinfo} and also because it fits better with the cross
manuals reference scheme.
@item The option @option{--output} signification changed. It now
has the same meaning than for @command{makeinfo}. It seems
that in 1.66 it was the same than @option{-out-file}. 
@option{--output} new meaning allows to replace @option{-out-file} and 
@option{-subdir} with a unique option. 

More precisely @option{-out-file} forces the output to be unsplit 
while @option{--output} behaves differently when split (it specifies
the directory
where the manual files should be outputted) and unsplit (it specifies
the output file). @option{-subdir} is retained for backward compatibility.

If you want a backward compatibility you can use @option{-subdir} 
for the output directory if the document is split, and @option{-out-file}
if the document isn't split. This hasn't been tested extensively though.
@item Many options has been obsoleted but they are retained for
backward compatibility.
@item The init files are searched in new directories, however they 
are still searched for in the old directories for backward
compatibility.
@item the option @option{--glossary} doesn't do anything. Likely
nothing specific is done regarding bibliographies. This has been
decided because this added some semantics to the texinfo formatting 
language that weren't part of texinfo. 

It should be possible to do
something similar with macros. See for example @file{glossary.texi} 
for glossary and @file{my-bib-macros.texi} for bibliography
in the directory @file{examples}. In the web2c package there is
an example of use of BibTeX, see @url{http://tug.org/texlive/devsrc/Build/source/TeX/texk/web2c/doc/} (the examples for bibliography are taken from the
texinfo home page @url{https://www.gnu.org/software/texinfo/texinfo.html}).
@item don't use @code{T2H_CENTER_IMAGE}. @code{@@center} should be used
insead, it will give the right output for all the formats.
@item If a directory creation fails the program aborts. This is much safer.
@item The interface for internationalisation changed, although
the previous wasn't documented a lot.
@item the API described in this manual changed a lot. A important
change was to use the @code{Texi2HTML::Config} names space instead of
variables prefixed with @samp{T2H_} or  @samp{t2h_}. To cope with
the change the prefix should be removed from variables in init files.
Some variables are now in @code{%Texi2HTML::THISDOC}.
@item @code{@@ifinfo} regions are not expanded by default. This may lead
to warnings or errors especially if the Top node is enclosed in 
@code{@@ifinfo}, as some node won't appear in menus. The quick fix
is to call @command{texi2html} with the option @option{--ifinfo} and
the right way should be to make more use of @code{@@ifnottex}.
@item The code appearing before the first node is now outputted, it was
ignored before. @option{--ignore-preamble-text} revert to the previous
behaviour. Enclosing in @code{@@ifnothtml} would be much cleaner.

@end itemize
@end itemize


@node texi2any Output Customization
@appendix @command{texi2any} Output Customization

@cartouche
@quotation Warning 
This early texi2any API described here
dates back to 2010/2012 and has been obsoleted by the texi2any_api
manual (@pxref{,,, texi2any_api, GNU Texinfo @command{texi2any}
Output Customization}).
@end quotation
@end cartouche

@cartouche
@quotation Warning
All of this information, with the exception of command-line options
and search directories (@pxref{Loading Init Files}), may become
obsolete in a future Texinfo release.  Right now, the ``API''
described in this chapter is immature, badly designed and incomplete,
so we must keep open the possibility of incompatible, possibly major,
changes.  Of course we try to avoid incompatible changes, but it is
not a promise.
@end quotation
@end cartouche

This chapter describes how to customize many aspects of the
@command{texi2any} HTML output.  Although some of the features here
can technically be used with other output formats, it's not especially
useful to do so, so we'll write the documentation as if HTML were the
target format.

@menu
* Loading Init Files::               Finding and writing initialization files.
* Init File Basics::                 What init files can contain and do.
* Output Elements::                  The main unit of output documents.
* Navigation Panel Customization::   Navigation buttons and more.
* Customizing HTML Page Layout::     Page headers, footers, sections.
* Customizing Special Elements::     The top, toc, about, etc., elements.
* Customizing Output-Related Names:: File names and target names.
* Customizing HTML Headings::        Sectioning commands.
* Customizing Indices::              Manipulating index entries.
* Customizing CSS::                  CSS customization for HTML.
@end menu


@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

@pindex Config @r{init files loaded}

You can write so-called @dfn{initialization files}, or @dfn{init
files} for short, to modify almost every aspect of output formatting.
The program loads init files named @file{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}).


@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 (some are crucial components of the program), and can
serve as a good model for writing your own.  In particular, the
@file{texi2html.pm} file is used to set all the defaults for
Texinfo.  Although it is large, it contains many useful examples of
settings.  Smaller examples include @file{utf8.pm},
@file{html32.pm}, and plenty more.

@menu
* Init File Variables::  Configuration & other variables, function references.
* Init File Namespaces:: @code{Texi2HTML::Config}, @code{Texi2HTML}, and @code{main}.
* Init File Functions::  Redefining functions through references.
* Setting and Getting Configuration Variables::
* Init File Global Information::    Accessing document title, file name, etc.
* Init File Encodings::             Overriding input and output encodings.
* texi2any's Three Passes::         Macro expansion, document structure, output
* Init File Calling at Different Stages:: Calling functions at various times.
* Init File Formatting of Commands:: Overriding default formatting completely.
* Init File General Block Commands:: Customizing usual environments.
* Init File Expansion Contexts::     Normal, preformatted, string, math.
* Internationalization of Strings::
@end menu


@node Init File Variables
@subsection Init File Variables

@cindex Initialization file variables
@cindex Variables, in initialization files

We divide the kinds of variables that can appear in initialization
files into three general categories:

@table @asis
@item configuration variables
@cindex Configuration variables
Configuration variables are set and accessed through specific
functions in initialization files (@pxref{@command{texi2any} Configuration
Variables}).

@item scalars, lists and hashes
@cindex Perl variables
Normal Perl variables.  The order of loading of initialization files
and of command-line options is important: later changes override
earlier ones.

@item function references
@cindex Function references
These allow dynamic redefinition of functions used to produce output.

As such functions are defined by a reference name, we will always use
the reference name 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) and @code{\%hash} for a reference
to a hash.

To illustrate these conventions, here is the prototype for the
function associated with a function reference
@samp{$formatting_function}:

@deftypefn {Function Reference} $text formatting_function $arg1 \@@arg2
@code{formatting_function} 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

To redefine this function, you would write:

@example
$formatting_function = \&my_formatting_function;
sub my_formatting_function($ $)
@{
  my $arg1 = shift;
  my $arg2 = shift;
  # prepare $formatted_text
  ...
  return $formatted_text;
@}
@end example
@end table

Since the program can process more than one file on the command line,
you must ensure that you properly initialize the variables used during
formatting.  It is possible to call functions at different stages to
help with that (@pxref{Init File Calling at Different Stages}).


@node Init File Namespaces
@subsection Init File Namespaces

@cindex Init file namespaces
@cindex Namespaces, for init files
@cindex Perl namespaces, for init files

@vindex Texi2HTML::Config @r{namespace}
Initialization file are loaded from the main program via a
@code{require} call in the @code{Texi2HTML::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.  The program's own variables are declared with @code{use
vars}, so that it should be possible to use the @code{use strict}
pragma in initialization files.

@vindex Texi2HTML @r{namespace}
@vindex main @r{namespace}
To avoid accidentally altering the variables in the @code{main}
namespace, all the global variables which could be of use in init
files are available in the @code{Texi2HTML} namespace.

The functions of the main program, however, are still in the
@code{main} namespace.


@node Init File Functions
@subsection Init File Functions

@cindex Init file functions
@cindex Functions, overriding in init files
@cindex Overriding functions in init files
To redefine a function you must replace the appropriate function
reference with a reference to your function: write your function, give
it a name you ensure is unique in the @code{Texi2HTML::Config}
namespace, and then override the value of the function reference with
your own.  When another function from the main program (or anywhere
else) calls the reference, your function will be used.

For example, the function reference to the function called when
handling an anchor is called @code{$anchor}.  Thus, to override the
corresponding function you could write:

@example
# override the function reference:
$anchor = \&my_anchor_fn;

# define the function to do the work:
sub my_anchor_fn @{
# process arguments, return an html anchor
@}
@end example


@node Setting and Getting Configuration Variables
@subsection Setting and Getting Configuration Variables

@cindex Configuration variables, setting and getting

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

To set the value of a configuration variable from an initialization file,
you should 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.

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

@defun 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 (get_conf('footnotestyle') eq 'separate') @{ ... @}
@end example

For the configuration variables associated with @@-commands, see
@ref{Configuration Variables for @@-Commands}.  For the configuration
variables associated with command line options, see @ref{Configuration
Variables and Options}.


@node Init File Global Information
@subsection Init File Global Information

@c @ignore
@c FIXME those are still undocumented
@c 'split_level' 
@c 'variable_levels' 'variables'
@c do_about
@c 'FH' 'state' 'format_from_command_line'
@c command_stack
@c line_nr
@c %htmlxref
@c %hyphenation
@c @end ignore

@cindex Init files, and global information
@cindex Global information, in init files

Much global information about the document is available as the basis
for customization in init files.

@menu
* Title String Variables::           @code{@@author}, @code{@@title}, etc.
* Command Line String Variables::    Input and output file names, etc.
* Global Document String Variables:: @code{@@copying}, CSS, TOC, etc.
* Index String Variables::           @code{defindex}, @code{@@synindex}, etc.
* Init File Flag Values::            @code{@@set} values.
* Program String Customization::     For the About element and footers.
@end menu

@node Title String Variables
@subsubsection Title String Variables

@cindex Title string variables

For title-related @@-commands, such as @code{@@title},
@code{@@titlefont}, and @code{@@author}, a variety of information is
available, with diverse formatting.

@code{@@author} and @code{@@subtitle} are multiline title-related
commands, since they may appear more than once.  Multiline
title-related commands are associated with strings that are
constructed by concatenating all the command occurences.  They are
also associated with arrays, and the name of the arrays is constructed
by appending a @samp{s} to the command name, as in @code{authors}.

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

@vindex Texi2HTML::THISDOC
The information associated with @code{@@top}, @code{@@title},
@code{@@settitle}, @code{@@shorttitlepage}, @code{@@author},
@code{@@subtitle}, @code{simpletitle} and @code{fulltitle} are
associated with the following keys in the @code{%Texi2HTML::THISDOC}
hash, where @var{command} is the title @@-command:

@table @code
@item @var{command}_texi
The original Texinfo code.

@item @var{command}
The corresponding text formatted.

@item @var{command}_no_texi
The text formatted as simple plain text.

@item @var{command}_simple_format
The text formatted as a string without formatting elements
(@pxref{Init File Expansion Contexts}).

@item @var{command}_line_nr
An opaque structure corresponding with the line where the @@-comand
appeared.  Not available for @code{@@titlefont}, multiline
title-related commands and derived information.

@end table

For multiline commands, the following array references are associated
with the following keys in the @code{%Texi2HTML::THISDOC} hash, where
@var{command} is the title @@-command:

@table @code
@item @var{command}s
Reference to an array containing all lines set by
@code{@@@var{command}}, formatted.

@item @var{command}s_texi 
Reference to an array containing all the original Texinfo lines.

@item @var{command}s_line_nr
Reference to an array of opaque structures corresponding with the 
line where the @@-command lines appeared.

@end table


@node Command Line String Variables
@subsubsection Command Line String Variables

@cindex Command-line string variables

These entries in the @code{%Texi2HTML::THISDOC} hash are related to
the command-line processing:

@table @code
@item destination_directory
Destination directory for the output files.

@item file_base_name
Base name of the Texinfo input file.

@item filename
This is a reference to a hash that holds the filenames for special
elements.  These files may not be used in certain cases, for example
the @code{toc} element file name may not be relevant if table of
contents is not output separately.  The keys are:

@table @code
@item doc
If not split, the document file; if split, the top element file.

@item top
Top element file name.

@item toc 
Table of contents element file name.

@item stoc
Overview (a.k.a.@: short table of contents) element file name.

@item about
About element file name.

@item foot
Footnotes element file name.

@item frame
Main frame file.

@item toc_frame
Table of contents frame file name.

@end table

@item input_directory
Path to the directory containing the Texinfo input file being processed.

@item input_file_name
Name of the Texinfo input file as given on the command line.

@item input_file_number
Number of the Texinfo input file from the command line which is
currently being processed.

@item program
The name of the command generating the output.

@item program_and_version
The name and version of the command generating the output.

@item program_homepage
Home page of the command generating the output.

@end table


@node Global Document String Variables
@subsubsection Global Document String Variables

@cindex Global document strings

These entries in the @code{%Texi2HTML::THISDOC} hash provide other
global document information.

@table @code
@item copying_comment
Text appearing in @code{@@copying} with all the Texinfo commands
put into comments (@pxref{copying,,@code{@@copying}}).

@item css_import_lines
Reference to an array containing the @code{@@import} lines of
@acronym{CSS} files (@pxref{HTML CSS}).

@item css_rule_lines
Reference to an array containing the normal lines of @acronym{CSS}
files.

@item dircategory_texi
The Texinfo @code{@@dircategory} argument (@pxref{Installing Dir Entries}).

@item dircategory
The formatted @code{@@dircategory} argument.

@item inline_contents
A reference to a hash containing two keys, one for each type of table
of contents: @code{contents} and @code{shortcontents}.  Each
associated value is a reference to an array containg the lines
resulting from formatting the respective type of table of contents,
including a heading and a reference.

@item stoc_file
The file name of the Overview (short table of contents).

@item toc_file
The file name of the table of contents.

@end table


@node Index String Variables
@subsubsection Index String Variables

@cindex Index strings

These entries in the @code{%Texi2HTML::THISDOC} hash provide other
index-related information.

@table @code
@item defindex 
@itemx defcodeindex
References to arrays holding the corresponding @@-command 
arguments.

@item merged_index 
Reference to a hash whose keys are the index names merged in
the values.

@item index_letters_array
@itemx index_entries_array
@itemx index_entries_region_array
@itemx index_entries
@itemx indices_numbers
@itemx indices
References to hashes holding information about the index entries
and whole indices.

@item synindex
@itemx syncodeindex
Reference to arrays containing array references with two elements, 
the two arguments of @code{@@synindex}
(@pxref{synindex,,@code{@@synindex}}).

@end table


@node Init File Flag Values
@subsubsection Init File Flag Values

@cindex Init file flag values
@cindex Flag values, in init files

@cindex @code{@@set} values, in init files
@vindex %main::value
Flags defined with @code{@@set} (@pxref{set value})
may be accessed through the @code{%main::value} hash.  The key is the
flag name, and the value is the flag value.


@node Program String Customization
@subsubsection Program String Customization

@cindex Program string customization
@cindex Customization of program string
@vindex PROGRAM_NAME_IN_FOOTER

The following function reference may be used to construct a string
advertising the program used to generate the output.  It may be used
in the @code{About} element, and in the footers if
@code{PROGRAM_NAME_IN_FOOTER} is set.

@deftypefn {Function Reference} $program_string_formatted program_string
This function reference should return the formatted program
string.
@end deftypefn


@node Init File Encodings
@subsection Init File Encodings

@cindex Init file encodings
@cindex Encodings, in init files

There are four encoding-related variables, which are autodetected
if not set:

@vtable @code
@item documentencoding
This configuration variable may be set, overriding any encoding
set by @code{@@documentencoding} (@pxref{documentencoding,,
@code{@@documentencoding}}).

@item IN_ENCODING
The encoding of the Texinfo files may be set independently with this
variable.  If not, then when @code{documentencoding} is set,
@code{IN_ENCODING} is also set if the encoding is supported by Perl.

@item ENCODING_NAME
The encoding advertised in output files.  If not set, the value of
this variable is based on the other ENCODING values, and if they are
all undefined, the variable @code{DEFAULT_ENCODING} is used.

@item OUT_ENCODING
The encoding of the output files.  If not set, the value of
@code{ENCODING_NAME} or @code{IN_ENCODING} is used if one of these
variables is set.

@end vtable

In general, the @code{documentencoding} and @code{IN_ENCODING} are set
to the appropriate values with no need to override.
@code{OUT_ENCODING} is set according to @code{ENCODING_NAME}.  To
force a given encoding for the output, it's best to set
@code{ENCODING_NAME}.  The default output encoding for Info is ASCII,
and for other formats is UTF-8.

The values for the encoding related variables are set in the default
@code{init_out} function reference (@pxref{Output Initialization}).


@node texi2any's Three Passes
@subsection @code{texi2any}'s Three Passes: Macro Expansion, Document Structure, Output

@cindex @code{texi2any's} three passes
@cindex Passes, of @code{texi2any}
@cindex Three passes, of @code{texi2any}

@command{texi2any} operates in three passes to transform the original
input to the final output.  In pass@tie{}0, the @code{@@macro} calls
are expanded; in pass@tie{}1, the document structure is gathered; and
in pass@tie{}2 the result is output.  In most cases this organization
does not matter, as output customization is almost always done in
pass@tie{}2.  Only if you want to do something during an earlier pass
do you need to consider this, as explained below.

After the Texinfo input file has been parsed, some information is
available which can be used to modify some variables and prepare for
the output.  For example, even such basic things as the document
language, the document encoding, values set with @code{@@set} or
@code{@@setfilename}, etc., cannot be known before the Texinfo
parsing.

@anchor{Output Initialization}
@cindex Output initialization
@cindex Initialization of output
The following function reference may be redefined to be called after 
Texinfo processing and before document generation, i.e., for output
initialization:

@deffn {Function Reference} init_out
This function performs the initialization of variables and other
tasks before document output.
@end deffn

By default, the hashes @code{%BUTTONS_NAME} (@pxref{Navigation Panel
Button Specification}) and @code{%BUTTONS_GOTO} (@pxref{About Element
Customization}) are initialized.  The initialization of these
variables depends on the document language.  Similarly, the encoding
variables are set based on the information now available (@pxref{Init
File Encodings}).  When generating HTML, aditionally, the
@code{%NAVIGATION_TEXT} hash is initialized.

To perform the default initializations, which are almost surely
desired, and also add more code, the best way is to save the default
function reference and then call it in your new function, like this:

@example
my $default_init_out = $init_out;
$init_out = \&my_init_out;
sub my_init_out() 
@{
   &$default_init_out();
   $NAVIGATION_TEXT@{'NodeForward'@} = ' > ';
@}
@end example

@anchor{Output Finalization}
@cindex Output finalization
@cindex Finalization of output
At the other end of things, if you want to do some clean-up after the
document was generated (write at the end of the output files, issue
messages, @dots{}), the following function reference may be overridden:

@deffn {Function Reference} finish_out
This function is called after the document generation.
@end deffn

The default is to do nothing.

These function references are mostly redundant with the handlers described 
in the next section (@pxref{Init File Calling at Different Stages}).


@node Init File Calling at Different Stages
@subsection 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 between the different
Texinfo parsing and outputting passes (see previous section).  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 five places for user defined functions, each associated with
an array.  The function references in each array are called one after
another.  The arrays correspond with the different stages:

@vtable @code
@item @@command_handler_setup
Called before anything is done, including collecting the output file
names.  The input file names' directories are available.

@item @@command_handler_init
Called as soon as the input file names are known.  It may be at
different moments: before processing anything, right after
@code{@@setfilename}, or at the end of pass@tie{}0 (after
@code{@@macro} and @code{@@include} expansions).  At that time the
information available is essentially just the input file names.

@item @@command_handler_names
Called right after pass@tie{}1, the main input collection.  At that
time all the special @@-commands have been collected as explained
above, but no output has been produced, and the element (node and
section) names have not been processed.

@item @@command_handler_process
Called after the element names have been processed, but
before the main output initialization.

@item @@command_handler_output
Called right before the main output processing, so that more
information is available, such as the title (@pxref{Init File Global
Information}).

@item @@command_handler_finish
Called after output generation is finished.
@end vtable 

Because these are arrays, you should use @code{push} to add your
functions to them, like this (a real example from the @LaTeX{}2HTML
support):

@example
push (@@command_handler_init,
      \&Texi2HTML::LaTeX2HTML::init);
push (@@command_handler_process,
      \&Texi2HTML::LaTeX2HTML::latex2html);
push (@@command_handler_finish,
      \&Texi2HTML::LaTeX2HTML::finish);
@end example

For a real-life example, see the @LaTeX{}2HTML support.


@node Init File Formatting of Commands
@subsection Init File Formatting of Commands

@cindex Init file formatting of commands
@cindex Formatting of commands, in init file
@cindex Commands, custom formatting

It is possible to bypass completely the normal formatting of
@@-commands with braces and the block commands of ``raw'' input such
as @code{@@html} and @code{@@tex} (@pxref{Raw Formatter Commands}).
In these cases the @@-commands and the text within are passed to a
user-defined function early, right after the document structure
determination of pass@tie{}1 (@pxref{texi2any's Three Passes}).
Another user-defined function is called during the output expansion
phase.

@vindex %command_handler
These user-defined functions are specified as values in the
@code{%command_handler} hash, with the key being the command to
override.  The associated value is itself a hash reference, whose keys
can be @code{'init'} for the function reference called during the
first pass, and @code{'expand'} during the expansion pass.

Here is an example for an @@-command with braces, @code{math}, used
for in the @LaTeX{}toHTML support:

@example
$command_handler@{'math'@} =
  @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
     'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
  @};
@end example

@cindex Raw region, overriding formatting of
Handling a raw region @@-command is the same:

@example
$command_handler@{'tex'@} =
  @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
     'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
@};
@end example

These function references are called as follows, respectively:

@deftypefn {Function Reference} $status @
           $command_handler@{'$command'@}->@{'init'@} $command $text $count
@var{$command} is the @@-command name, @var{$text} is the text
appearing within the @@-command, and @var{$count} counts how many
times this @@-command has appeared.  @var{$status} is a boolean to return,
true if the collection was succesful.  If it is false, the @@-command
and the text are discarded.
@end deftypefn

@deftypefn {Function Reference} $result @
     $command_handler@{'$command'@}->@{'expand'@} $command $count \%state $text
@var{$command} is the @@-command name, @var{$count} counts how many
times this @@-command has appeared, and @var{\%state} is a hash
reference with detailed context information; @var{$text} should be
empty.  @var{$result} is the expanded resulting text.
@end deftypefn


@node Init File General Block Commands
@subsection Init File General Block Commands

@cindex Init file general block commands
@cindex General block commands, in init files
@cindex Block commands, in init files

A @dfn{general block @@-command} is any @@-command which is paired
with an @code{@@end @var{cmdname}}, with the exception of those
@@-commands selecting whether input is processed (such as
@code{@@ignore} and @code{@@ifhtml}) and ``raw'' @@-commands (such as
@code{@@verbatim} and @code{@@html}).

@deftypefn {Function Reference} $line begin_format_texi $command $line \%state
@var{$command} is the format command, @var{$line} is the rest of the
line following the @@-command, and @var{\%state} is a hash reference
with detailed context information.  The function can modify
@code{$line} and return something else.
@end deftypefn

By default, this is used to keep track of multitable nesting, and so
it is linked with multitable formating.

@c oldapi @pxref{Multitable Formatting}


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

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

There are four 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.

@c oldapi (@pxref{Menu formatting})

@item string context
@cindex String expansion context
When rendering strings without formatting elements, for example in
comments (@pxref{Comments}) and titles.  We have two string contexts,
one that produces plain text, and a second that allows for limited
formatting, typically without any element when producing HTML or XML,
so the value can be used in an attribute.

@item math context
@cindex Math expansion context
Math (@pxref{math,, @code{@@math}}).

@end table


@node Internationalization of Strings
@subsection Internationalization of Strings in the Output Document

@cindex I18n
@cindex Internationalization of strings in the output document
@cindex Output documentation, internationalization of

@vindex documentlanguage @r{configuration variable}
@command{texi2any} writes some fixed strings in the generated document
at various places: for cross references, in page footers, on the help
page, alternate text for images, and so on.  The string chosen depends
on the value of the configuration variable @code{documentlanguage} at
the time of the string being output (@pxref{documentlanguage}, for the
Texinfo command interface).

@pindex libintl-perl @r{Gettext implementation}
The Gettext framework is used for those strings (@pxref{Top,,,
gettext, Gettext}).  The @code{libintl-perl} package is used as
the @code{gettext} implementation; more specifically, the pure Perl
implementation is used, so Texinfo can support consistent behavior
across all platforms and installations, which would not otherwise be
possible.  @code{libintl-perl} is included in the Texinfo distribution
and always installed, to be sure that it is available if needed.  It
is also possible to use the system @code{gettext}; currently decided
at build-time).  

@vindex texinfo_document @r{Gettext domain}
The Gettext domain @samp{texinfo_document} is used for the strings,
and the subroutine @code{gdt} is used for translated
strings:

@defun gdt ($string, \%variables_hash, \%state)
@var{$string} is the string to be translated, @var{\%variables_hash}
is a hash reference holding the variable parts of the translated
string, and @var{\%state} is a hash reference with detailed context
information.
@end defun

@cindex Perl format strings for translation
Translated strings are written as Texinfo, and may include
@@-commands.  In translated strings, the varying parts of the string
are not usually denoted by @code{%s} and the like, but by
@samp{@{arg_name@}}.  (This convention is common for @code{gettext} in
Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
Format Strings, gettext, GNU Gettext}.)  For example, in the
following, @samp{@{section@}} will be replaced by the section name:

@example
see @{section@}
@end example

These Perl-style brace format strings are used for two reasons: first,
changing the order of @code{printf} arguments is only available since
Perl@tie{}5.8.0; second, and more importantly, the order of the
argument is unpredictable, since @@-command expansion may lead to
different orders depending on the output format.  The expansion of
a translation string is done like this:

@enumerate
@item First, the string is translated.  The locale 
is @var{@@documentlanguage}@code{.}@var{@@documentencoding}.

@cindex @code{us-ascii} encoding, and translations
If the @var{@@documentlanguage} has the form @var{ll_CC}, @var{ll_CC}
is tried first, and then @var{ll}.  If that does not exist, and the
encoding is not @code{us-ascii}, then @code{us-ascii} is tried.  The
idea is that if there is a @code{us-ascii} encoding, it means that all
the characters in the charset may be expressed as @@-commands.  For
example, there is a @code{fr.us-ascii} locale that can accommodate any
encoding, since all the Latin@tie{}1 characters have associated
@@-commands.  On the other hand, Japanese has only a translation
@code{ja.utf-8}, since there are no @@-commands for Japanese
characters.

@item Next, the args in string are protected.  For example,
@samp{@{ arg_name @}} becomes@*
@samp{@@internal_translation_open_brace@{@} arg_name@*
@@internal_translation_close_brace@{@}}
(this part is skipped if there is nothing to expand).

@item Next, the string is expanded as Texinfo.
@samp{@@internal_translation_open_brace@{@}} expands to @samp{@{} and
@samp{@@internal_translation_close_brace@{@}} expands to @samp{@}},
such that in the end one still gets @samp{@{arg_name@}} within an
expanded string (this part is skipped if there is nothing to expand).

@item Finally, the arguments are substituted; for 
example, @samp{@{arg_name@}} is replace by the corresponding actual
argument.

@end enumerate

@vindex duplicate @r{in @code{%state} hash}
In the following example, @samp{@{date@}}, @samp{@{program_homepage@}}
and @samp{@{program@}} are the arguments of the string.  Since they
are used in @code{@@uref}, their order is not predictable.  The
@samp{@{'duplicate'=>1@}} means that the document state should be used
when expanding the string.  @samp{@{date@}},
@samp{@{program_homepage@}} and @samp{@{program@}} are substituted
after the expansion, which means that they should already be
acceptable output:

@example
gdt('Generated on @@emph@{@{date@}@} using
     @@uref@{@{program_homepage@}, @@emph@{@{program@}@}@}.',
    @{
     'date' => $date,
     'program_homepage' => $Texi2HTML::THISDOC@{'program_homepage'@},
     'program' => $Texi2HTML::THISDOC@{'program_and_version'@} @},
    @{'duplicate'=>1,
   @});
@end example

This approach is admittedly a bit complicated.  Its usefulness is that
it supports having translations available in different encodings for
encodings which can be covered by @@-commands, and also specifying how
the formatting for some commands is done, independently of the output
format---yet still be language dependent.  For example, a
@samp{@@pxref} translation string may be:

@example
see @{node_file_href@} section `@{section@}\' in @@cite@{@{book@}@}
@end example

@noindent
which allows specifying a string independently of the output format,
but with rich formatting that may be translated appropriately in many
languages.

@vindex keep_texi @r{in @code{%state} hash}
Expansion can be prevented by setting the key @code{keep_texi} in the
@code{state} hash.

When an @code{@@documentlanguage} line appears in the document and the
language was not set on the command line, it is convenient for the
translations to redefine some variables based on the new language.
Therefore, Texinfo has a function reference which is called each time
@code{@@documentlanguage} is encountered:

@deffn {Function Reference} $translate_names
Called each time @code{@@documentlanguage} is encountered, if the
language was not set on the command line.  It should be used to
retranslate strings based on the new language.
@end deffn


@node Output Elements
@section Output Elements

@cindex Output elements
@cindex Elements, main unit of output documents

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

@menu
* Defined: Output Elements Defined.
* Labels: Output Element Labels.
* Lines: Output Element Lines.
@end menu


@node Output Elements Defined
@subsection Output Elements Defined

@cindex Output elements, defined

The output elements are:

@table @emph
@item Normal elements
@cindex Normal elements
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.  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} and @code{USE_SECTIONS}
(@pxref{@command{texi2any} Configuration Variables}).

For example, when generating Info, the nodes are the elements; when
generating Docbook, sectioning commands are the main element
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 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.

The top element may end up formatted differently from normal elements
if there is an @code{@@top} section or the @code{@@node Top} is not
associated with a sectioning command.

@item Miscellaneous elements
@cindex Table of contents, output element
@cindex Short table of contents, output element
@cindex Overview, output element
@cindex Footnotes, output element
@cindex About page, output element
The remaining elements are associated with different files if the
document is split, and also if @code{MONOLITHIC} is not set.  There
are four such miscellaneous 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{inline},
the @emph{Table of contents} and @emph{Overview} elements are directly
included within the document.  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 Overview Elements Customization}).

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

@end itemize
@end table

It is common not to have anything but normal elements, 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_SECTIONS} is
set or @code{USE_NODES} is set to 0; conversely, the main component is
nodes if @code{USE_NODES} is set or @code{USE_SECTIONS} is 0.  If both
configuration variables are undefined, heuristics are used, influenced
by the presence of nodes or sectioning elements in the document: if
there are no nodes, sectioning elements are preferred and vice versa.
 
When sections are the main components of elements, ``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 Labels
@subsection Output Element Labels

@cindex Output element labels
@cindex Element labels

A variety of data items, called @dfn{element labels}, are associated
with elements.  They may be used in the formatting functions, and/or
associated with a button (@pxref{Navigation Panel Button Specification}).

Each element label has a name and a reference to the element they
represent, 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).  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, as explained above
(@pxref{Two Paths}).

Here is the list of element labels:

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

@item Top
Top element.  The associated name is @code{$TOP_HEADING} if that variable is 
defined.  This variable is not set by default.

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

@item Index
The first chapter with @code{@@printindex}.  The associated name is
@code{$INDEX_CHAPTER}, if the variable is set.  This variable is not
set by default.

@item This
The current element.

@item Forward 
Next element in reading order.

@item First
First element in reading order.

@item Last
Last element in reading order.

@item Back
Previous element in reading order.

@item FastForward
Next chapter.

@item FastBack
Beginning of this chapter, or previous chapter if the element is a chapter.

@item Next
Next section at the same level.

@item Prev
Previous section at the same level.

@item Up
Up section.

@item SectionNext
Next in section reading order.

@item SectionPrev
Previous in section reading order.

@item SectionUp
Up in section reading order.

@item NodeNext
Next node.

@item NodeForward
Next node in node reading order.

@item NodeBack
Previous node in node reading order.

@item NodePrev
Previous node.

@item NodeUp
Up node.

@end table

The element labels may also be accessed when formatting elements.
Four hashes are available, with their keys being the elements items,
and their values as follows:

@vtable @code
@item %Texi2HTML::NAME
The formatted element name.

@item %Texi2HTML::HREF
The element hypertext reference.

@item %Texi2HTML::NODE
The element node name.

@item %Texi2HTML::NO_TEXI
The element name after removal of texi commands.

@end vtable

For example, @code{$Texi2HTML::NAME@{'Back'@}} is the name of the
previous element in reading order.


@node Output Element Lines
@subsection Output Element Lines

@cindex Output elements lines
@cindex Formatted lines, of output elements

The following array references holds formatted lines relating to
various output elements.

@vtable @code
@item $Texi2HTML::OVERVIEW
Lines of the short table of contents.  @xref{Contents and Overview
Elements Customization}.

@item $Texi2HTML::THIS_SECTION
Lines of the current element.

@item $Texi2HTML::TITLEPAGE
The title page formatted.  @xref{HTML Title Page Customization}.

@item $Texi2HTML::TOC_LINES
Lines of table of contents.  @xref{Contents and Overview Elements
Customization}.

@end vtable


@node Navigation Panel Customization
@section Navigation Panel Customization

@cindex Customization, of navigation panel
@cindex Navigation panel, 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.

Considerable customization can done with straightforward variable
assignments, especially special arrays.  The configuration variables
@code{VERTICAL_HEAD_NAVIGATION}, @code{ICONS}, @code{HEADERS},
@code{HEADER_IN_TABLE}, @code{USE_ACCESSKEY} and @code{USE_REL_REV}
may be used to change the the navigation panel formatting.
@xref{@command{texi2any} Configuration Variables}.

In the unusual case that this isn't enough, it is also possible to
redefine the function doing the navigation panel formatting.

@menu 
* Buttons: Navigation Panel Button Specification.
* Functions: Navigation Panel Formatting Functions.
@end menu


@node Navigation Panel Button Specification
@subsection Navigation Panel Button Specification

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

Several arrays and hashes enable precise control over the navigation
panel buttons and their display.  The following 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.

@vindex WORDS_IN_PAGE
If @code{WORDS_IN_PAGE} is set and the output is split at nodes, these
buttons are only included if the sectioning element text has more than
@code{WORDS_IN_PAGE} words.  The word counting is only approximate and
includes punctuation marks, html elements, numbers.  The default is to
include the buttons for elements larger than 300 words.

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

@table @emph
@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.  @xref{Output Element Labels}, for some
scalars that may be useful here.

@item array reference
Here, the first array element should be a reference to a text string
and the second element an element label.  A link to the element
associated with the element label with the given text is generated.

For example, if the button array element is
@example
[ 'Next', \$Texi2HTML::NODE@{Next@} ] 
@end example

@noindent
Then the button will be a link to the next section with text
@code{$Texi2HTML::NODE@{Next@}}.

@item element label
@vindex %NAVIGATION_TEXT
@vindex init_out
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
label in the @code{%NAVIGATION_TEXT} hash, surrounded by @samp{[} and
@samp{]}. If the element label is @samp{ }, the @samp{[} and @samp{]}
are omitted.  The elements of the @code{%NAVIGATION_TEXT} hash are
defined dynamically, in the @code{init_out} function reference
(@pxref{Output Initialization}).

@vindex %ACTIVE_ICONS
@vindex %BUTTONS_NAME
@vindex %PASSIVE_ICONS
@vindex %NAVIGATION_TEXT
@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 label in the
@code{%ACTIVE_ICONS} hash if the link leads to an element, or in the
@code{%PASSIVE_ICONS} 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 @code{%BUTTONS_NAME} for the button name and
@code{%NAVIGATION_TEXT} for the description.
@end table

@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} 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} hash is used for the @code{rel} attribute.


@node Navigation Panel Formatting Functions
@subsection Navigation Panel Formatting Functions

@cindex Navigation panel formatting functions
@cindex Formatting functions, for navigation panel

In the unusual event that your needs are not met by changing the
navigation buttons (see the previous section), you can completely
control the formatting of navigation panels by redefining function
references.

The overall display of navigation panels is controlled via this
function reference, @code{print_navigation}:

@deftypefn {Function Reference} $navigation_text print_navigation @
           \@@buttons $vertical
@var{\@@buttons} is an array reference holding the specification of
the buttons for that navigation panel.  @var{$vertical} is true if the
navigation panel should be vertical.  Returns the formatted navigation
panel in @var{$navigation_text}.
@end deftypefn

The function reference @code{button_formatting} does the formatting of
one button:

@deftypefn {Function Reference} $formatted_button button_formatting @
           $button $vertical
@var{$button} holds the specification of the button as explained
above.  @var{$vertical} is true if the navigation panel should be
vertical.  Returns the formatted result in @var{$formatted_button}.
@end deftypefn

By default, the function associated with @code{$print_head_navigation}
formats the navigation panel for the page header. 

@deftypefn {Function Reference} $page_head print_head_navigation @
           $filehandle \@@buttons $first_in_page $previous_is_top \%element
@itemize @bullet
@item @var{$filehandle} is the opened filehandle the function should
write to, if defined.  If not defined the function should return the
formatted page header as a string.

@item @var{\@@buttons} is an array reference holding the specification
of the buttons for the navigation panel.

@item @var{$first_in_page} should be set if this is the first navigation
panel in the page.

@item @var{$previous_is_top} is true if the previous element is the
top element.

@item @var{\%element} is a hash reference with information about
the element.
@end itemize
@end deftypefn

Similarly, the function associated with @code{$print_foot_navigation}
formats the navigation panel for the page footer.

@deffn {Function Reference} print_foot_navigation @
  $filehandle \@@buttons $rule $print_navigation_panel \%element $maybe_in_page
@itemize @bullet
@item @var{$filehandle}, @var{\@@buttons}, and @var{\%element} are as above.

@item @var{$rule} is a rule that may be used to separate the navigation panel
from the preceding text.

@item @var{$print_navigation_panel} is a boolean specifying
whether the navigation panel itself should be printed.

@item @var{$maybe_in_page} is set if the present footer is between
regular elements and the top, or between regular elements and special
elements, that is, not at the end of a file.
@end itemize
@end deffn


@node Customizing HTML Page Layout
@section Customizing HTML Page Layout

@command{texi2any} provides for customization of the HTML page
headers, footers, and the section layout in between.  (These are
unrelated to the headings and ``footings'' produced in @TeX{} output;
@pxref{Headings,, Page Headings}.)

@menu
* Headers:  Customizing HTML Page Headers.
* Sections: Customizing HTML Section Layout.
* Footers:  Customizing HTML Page Footers.
@end menu


@node Customizing HTML Page Headers
@subsection Customizing HTML Page Headers

@cindex Customizing HTML page headers
@cindex Headers, customizing for HTML

The following three function references give full control over the
page header formatting done at the top of each HTML output file.  The
@code{$print_page_head} function is called for all pages.  After that,
the @code{$print_chapter_header} function is called if the output is
split at chapters, or the @code{$print_section_header} function if the
split at sections.

@deftypefn {Function Reference} print_page_head $filehandle
@cindex @code{<body>} tag, outputting
@var{$filehandle} is the opened filehandle to which the function
should write.  This function should print the page header, in HTML,
including the @code{<body>} element.
@end deftypefn

@deffn {Function Reference} print_chapter_header $filehandle \%element
@var{$filehandle} is the opened filehandle to which the function
should write.  @var{\%element} is a hash reference with information
about the element.  This function is called if the output is split
at chapters, after @code{$print_page_head}.
@end deffn

@deffn {Function Reference} print_section_header $filehandle \%element
@var{$filehandle} and @var{\%element} are as above.  This function is
called if the output is split at sections, after
@code{$print_page_head}.
@end deffn

@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{Navigation Panel Button
Specification}.


@node Customizing HTML Section Layout
@subsection Customizing HTML Section Layout

@cindex Customizing HTML section layout
@cindex Section layout, customizing for HTML

The following function references are used for the formatting of
sections in HTML output:

@deffn {Function Reference} print_section $filehandle @
       $first_in_page $previous_is_top \%element
@table @var
@item $filehandle
The opened filehandle to which the function should write.

@item $first_in_page
True if this section is the first section in the page.

@item $previous_is_top
True if this section is the section following the top section.

@item \%element
A hash reference with information about the element.
@end table

The function should print the current section contents.
@end deffn

@deffn {Function Reference} end_section $filehandle @
       $last_element_or_before_top \%element
@var{$filehandle} and @var{\%element} are as above.
@var{$last_element_or_before_top} is true if this section precedes the
top element or is the last one in page, or before the special
elements.
@end deffn


@node Customizing HTML Page Footers
@subsection Customizing HTML Page Footers

@cindex Customizing HTML page footers
@cindex Footer, customizing for HTML

The following function references give full control over the page
footer formatting done at the bottom of each HTML output file.  The
@code{$print_chapter_footer} function is called if the output is split
at chapters, or the @code{$print_section_footer} footer is called if
split at sections.  After that, the @code{$print_page_foot} function
is called.

@deffn {Function Reference} print_page_foot $filehandle
@cindex @code{</body>} tag, outputting
@var{$filehandle} is the opened filehandle to which the function
should write.  This function should print the page footer, including
the @code{</body>} element.
@end deffn

@deffn {Function Reference} print_chapter_footer $filehandle \%element
@var{$filehandle} is the opened filehandle to which the function
should write.  @var{\%element} is a reference to a hash with
information about the element.  This function is called if the
output is split at chapters, before @code{$print_page_foot}.
@end deffn

@deffn {Function Reference} print_section_footer $filehandle \%element
@var{$filehandle} and @var{\%element} are as above.
This function is called if the output is split at sections, before
@code{$print_page_foot}.
@end deffn

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


@node Customizing Special Elements
@section Customizing Special Elements

Various function references allow you to customize both the content
and layout of the HTML output of the special elements (@pxref{Output
Elements Defined}).

@menu
* Content: Customizing Content of Special Elements.
* Layout: Customizing Layout of Special Elements.
@end menu


@node Customizing Content of Special Elements
@subsection Customizing Content of Special Elements

@cindex Customizing special elements content
@cindex Special elements content, customizing
@cindex Content of special elements, customizing

The label for the special elements (@pxref{Output Elements Defined}),
except for the top element, is formatted according to the function
reference @code{$misc_element_label}:

@deftypefn {Function Reference} $misc_element_label misc_element_label @
           $identifier $page_name
@var{$identifier} is the identifier associated with the special
element.  @var{$page_name} is the special element name.  The function
should return a label that can be used for references to the special
element.
@end deftypefn

The following sections describe the details for the special elements
other than footnotes, which are formatted when the @code{@@footnote}
command is expanded.

@c oldapi (@pxref{Customizing HTML Footnotes}).

@menu
* Top Element Customization::
* Contents and Overview Elements Customization::
* About Element Customization::
* HTML Title Page Customization::
@end menu


@node Top Element Customization
@subsubsection Top Element Customization

@cindex Customization of top element
@cindex Top element, customizing

The top element formatting is controlled by three functions which also
controls the layout of the top element page or section.  The associated
function references are:

@deffn {Function Reference} print_Top_header $filehandle $begin_page
@var{$filehandle} is the opened filehandle to which the function
should write.  @var{$begin_page} is true if the element is the first
in a page.  This function should begin the top element.  At the time
this function is called, the top element text has not been parsed.
@end deffn

@deffn {Function Reference} print_Top $filehandle $has_top_heading \%element
@var{$filehandle} is the opened filehandle to which the function
should write.  @var{$has_top_heading} is true if there is a
@code{@@heading} command or @code{@@titlefont} command appearing in
the top element text. @var{\%element} is a hash reference with
information about the element.  This function should be used to format
the top element text and navigation panel.
@end deffn

@deffn {Function Reference} print_Top_footer $filehandle $end_page \%element
@var{$filehandle} and @var{\%element} are as above.  @var{$end_page}
is true if the element is the last in a page.  This function should
end the top element.
@end deffn


@node Contents and Overview Elements Customization
@subsubsection Contents and Overview Elements 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 either the beginning (the default) or end of 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_OVERVIEW
Inserted before the short table of contents text.

@item $AFTER_OVERVIEW
Inserted after the short table of contents text.

@item $NO_BULLET_LIST_STYLE
Expected to contain the CSS style used for the list style when there
is no bullet.

@item $NO_BULLET_LIST_CLASS
Used for the class associated with the $NO_BULLET_LIST_STYLE CSS
style.

@item $NO_BULLET_LIST_ATTRIBUTE
Used as attribute text for the list element when there is no bullet.
It is used in the tables of contents if they are formatted as a list.
@end vtable

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

@deffn {Function Reference} toc_body \@@elements 
@var{\@@elements} is an array reference containing information about
all the elements of the document.  Each entry of this array is a hash
reference, useful keys of which are as follows:

@table @code
@item top
True if the element is the top element.

@item index_page
True if the element is an index page added because of index splitting.

@item toc_level
Level of the element in the table of contents: the highest level is 1
for the top element and for chapters, appendices, etc., 2 for
sections, unnumbered sections, etc., and so on.

@item tocid
Label to be used for references linking to this element within the
table of contents.

@item file 
The file containing the element, part of the link if the output is
split.

@item text
Text of the element, with section number,

@item name
Text of the element, without section number.
@end table

@vindex $Texi2HTML::TOC_LINES@r{, in customization}
@vindex $Texi2HTML::OVERVIEW@r{, in customization}
This function doesn't return anything.  Instead, it should fill the
array corresponding to the @code{$Texi2HTML::TOC_LINES} and
@code{$Texi2HTML::OVERVIEW} references with the text for the
respective tables of contents.  @xref{Output Element Lines}.
@end deffn

By default, @code{$toc_body} calls two specialized function
references, one for the contents and the other for the short contents.

@deftypefn {Function Reference} \@@contents_lines contents @
           \@@elements $contents_file
@var{\@@elements} is an array reference as above.
@var{$contents_file} is the name of the file containing the table of
contents.  This function should return the formatted table of contents
lines.
@end deftypefn

@deftypefn {Function Reference} \@@shortcontents_lines shortcontents @
           \@@elements $shortcontents_file
@var{\@@elements} is an array reference as above.
@var{$shortcontents_file} is the name of the file containing the table
of contents.  This function should return the formatted overview
(short table of contents) lines.
@end deftypefn

Another function reference is used to add a heading and a reference,
to be used with @code{CONTENTS_OUTPUT_LOCATION} or merged into the title
material.  Its output is not used when the tables of contents are
separate elements.

@deftypefn {Function Reference} \@@inline_contents_lines inline_contents @
           $filehandle $command \%element \@@elements
Return a reference to an array holding the lines containing the
contents, heading and reference.  @var{$filehandle} is a reference to
the currently opened file if the function is called because a
@code{@@contents} or @code{@@shortcontents} command was encountered,
and @code{undef} otherwise.  @var{$command} is either @samp{contents}
or @samp{shortcontents}.  @var{\%element} is a reference to a hash
holding information about the element where the contents appeared.
Relevant keys are:

@table @code
@item target
The identifier associated with the table of contents, used
to link to the table of contents.

@item id
The identifier associated with the element, used to do labels.
Usually but not necessarily the same as @code{target}.

@item file
The file name containing the table of contents.
@end table

@var{\@@elements} is an array reference as above.
@end deftypefn


@node About Element Customization
@subsubsection 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};
@pxref{Navigation Panel Button Specification}) and an example showing
the button targets.  The formatting of this text may be influenced by
the following:

@table @code
@item $PRE_ABOUT 
@itemx $AFTER_ABOUT
@vindex $PRE_ABOUT
@vindex $AFTER_ABOUT
Each of these variables may be a scalar or a function reference.  If a
scalar, the value is used.  If a function reference, it is called and
the returned text is used.  The text is added before or after the main
About text, respectively.

@item %BUTTONS_GOTO
@vindex %BUTTONS_GOTO
The keys of this hash are element labels (@pxref{Output Element
Labels}), and the values are the text associated with each element
label in the About text.  By default, the elements of the hash are
defined dynamically in the @code{init_out} function reference
(@pxref{Output Initialization}).

@item %BUTTONS_EXAMPLE
@vindex %BUTTONS_EXAMPLE
Like @code{%BUTTONS_GOTO}, except the values are the text from the
About example, typically a section number.

@end table

If the above is not enough and you want to control exactly the
formatting of the about text, the following function reference may be
overridden:

@deftypefn {Function Reference} $about_text about_body
This function returns the about text.
@end deftypefn


@node HTML Title Page Customization
@subsubsection HTML Title Page Customization

@vindex $Texi2HTML::TITLEPAGE
The HTML title page is first formatted using the text appearing in the
@code{@@titlepage} section, and put in the
@code{$Texi2HTML::TITLEPAGE} array reference (@pxref{Output Element
Lines}).  More formatting can be done using the following function
reference:

@deffn {Function Reference} titlepage \@@titlepage_lines @
       $text $comment $simple_text
@var{\@@titlepage_lines} is an array containing the Texinfo lines in
@code{@@titlepage}.  @var{$text} is the text appearing in
@code{@@titlepage}, formatted.  @var{$comment} is the text with
Texinfo markup removed, thus should be simple plain text.
@var{$simple_text} is the text formatted in a string context with
minimal formatting but no elements.  This function should complete
@code{$Texi2HTML::TITLEPAGE}.
@end deffn

By default, this function outputs the title if there is no title page,
and adds the table of contents and short table of contents if they are
to be output and @code{@@setcontentsaftertitlepage} or
@code{@@setshortcontentsaftertitlepage} appear in the document
(@pxref{Contents and Overview Elements Customization}).

@vindex USE_TITLEPAGE_FOR_TITLE
@vindex SHOW_TITLE
The resulting title page output is used in the document if
@code{USE_TITLEPAGE_FOR_TITLE} and @code{SHOW_TITLE} are set.


@node Customizing Layout of Special Elements
@subsection Customizing Layout of Special Elements

@cindex Customizing special elements layout
@cindex Special elements layout, customizing
@cindex Layout of special elements, customizing

The formatting of each of the special elements is controlled by a
function, as listed in the following table:

@ftable @code
@item print_Top
@item print_Top_header
@item print_Top_footer
Formatting of the top element.  It is also used for the formatting of
the top element text (@pxref{Top Element Customization}).

@item print_Toc
Formatting of the table of contents element.

@item print_Overview
Formatting of the short table of contents element.

@item print_About
Formatting of about (help) element.

@item print_Footnotes
Formatting of the footnote elements.
@end ftable

@findex print_misc
@findex print_misc_header
@findex print_misc_footer
In the default case, @code{$print_Top} calls @code{$print_Top_header}
for the header and @code{$print_Top_footer} for the footer of top
element.  All the other functions call @code{$print_misc} which in
turn calls @code{$print_misc_header} for the headers and
@code{$print_misc_footer} for the footers.


@node Customizing Output-Related Names
@section Customizing Output-Related Names

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

@menu
* File: Customizing Output File Names.
* Target: Customizing Output Target Names.
@end menu

@node Customizing Output File Names
@subsection 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
@vindex TOC_FILE
Furthermore, the configuration variables @code{TOP_FILE} and
@code{TOC_FILE} override the output file name for the top and contents
elements.

@vindex NODE_FILES
Two function references enable further customization.  The first,
@code{node_file_name}, is especially useful when @code{NODE_FILES} is
true; it is used to customize the node file name.

@deftypefn {Function Reference} $node_file node_file_name \%node $type
@var{\%node} is a hash reference with the following interesting keys
(there are many others): the string @code{texi}, for the Texinfo node
name, and the boolean @code{with_section}, true if associated with a
section.  @var{$type} is @code{top} if the node is the top element.
The function should return the node file name (@var{$node_file}).
@end deftypefn

The other function reference, @code{element_file_name}, is used to
customize the file names associated with each element, and the name of
the file associated with the special elements (@pxref{Output Elements
Defined}).

@deftypefn {Function Reference} $file element_file_name @
           \%element $type $txi_file_name
@var{\%element} is undefined for the special elements (@pxref{Output
Elements Defined}), Otherwise, it is a hash reference with the
following interesting keys (there are many others):
@table @code
@item texi
The Texinfo element name.

@item number
The number associated with a section.

@item doc_nr
A number incremented whenever a new file should begin, based on how the 
document is split (@pxref{Splitting Output}).

@item text
The element text.

@item name
The element text without section number.
@end table

@var{$type} is empty for normal elements.  For the top element it is
@samp{top}; for the table of contents it is @samp{toc}; for the
overview it is @samp{stoc}; for footnotes it is @samp{foot}; and for
the about element it is @samp{about}.

@vindex FRAMES@r{, customizing output names of}
If frames are used, due to the @code{FRAMES} configuration variable,
the function reference is also called for @samp{frame}, the frame file
name, and @samp{toc_frame}, the table of contents frame file name.

@var{$txi_file_name} is the basename of the Texinfo manual.

The function should return the file name for the element (@var{$file}).
@end deftypefn


@node Customizing Output Target Names
@subsection 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.  Usually, these should
be the same.

@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,$id)} node_target_name @
           \%node $default_target $default_id $type
@var{\%node} is the same as in the @code{node_file_name} function
reference in the previous section.  @var{$default_target} is the
target that has been already set (it is also in
@code{$node->@{'target'@}}), and @var{$default_id} is, similarly, the
id already set.  @var{$type} is @code{top} if the node is the top
node.  The function should return a two-element list of the target and
id names.
@end deftypefn

For elements (@pxref{Output Elements Defined}), the function 
reference is:

@deftypefn {Function Reference} {($target,$id)} element_target_name @
           \%element $default_target $default_id
@var{\%element} is the same as in @code{element_file_name} in the
previous section, and @var{$default_target}, @var{$default_id}, and
the return value, are as above.
@end deftypefn

The file, target, and id of ``placed'' items, namely floats,
footnotes, index entries, anchors, contents, shortcontents and
headings, may also be set, although the default should be suitable.
Nevertheless, the following function reference can be used:

@deftypefn {Function Reference} {($target, $id, $file)} @
           placed_target_file_name \%placed_item \%element @
           $default_target $default_id $default_file $context

@var{\%placed_item} is a hash reference describing the placed item, as
in the above, likewise @var{\%element}.  @var{$default_file},
@var{default_id} and @var{$default_target} are the file, id and target
already set.  @var{$context} describes the context; this is set to
@samp{footnotes} if in footnotes, to @samp{no_associated_element} if
the placed item is outside of any element (e.g., @code{@@titlepage},
@code{@@copying}), and is otherwise empty.
@end deftypefn

@vindex %misc_pages_targets
For special elements, the @code{%misc_pages_targets} hash is used to
set the target and id.  The possibilities for the keys are
@samp{Overview}, @samp{Contents}, @samp{Footnotes} and @samp{About}.


@node Customizing HTML Headings
@section Customizing HTML Headings

@cindex Headings, customizing HTML

A function reference may be defined to do the formatting of the heading
text (usually changing font and underlining):

@deftypefn {Function Reference} $heading_text_formatted heading_text @
           $command $text $level
@var{$command} is the @@-command name associated with the heading.
@var{$text} is the heading @@-command argument, formatted.
@var{$level} is the level of the heading in the document tree.
@end deftypefn

@findex heading_text_preformatted
A similar function reference is available for preformatted context,
@code{heading_text_preformatted}.

A function controls the formatting of element headings,
@code{heading}.  By default its main job is to determine whether the
@code{heading_text} function reference should be called.  Normally,
heading text is not output for a node on its, only for any associated
sectioning element (@pxref{Two Paths}).

@deftypefn {Function Reference} $heading_text heading \%element $command @
           $command_texi_arg $formatted_arg $in_preformatted $one_section @
           $element_heading

@table @var
@item \%element
A hash reference representing the sectioning element.  The
following keys are of interest:

@table @code
@item text
The heading text.

@item text_nonumber
The heading text without section number.

@item node
True if the sectioning element is a node without an associated
structuring command.

@item level
The level of the element in the document tree: @samp{0} for
@code{@@top}, @samp{1} for @code{@@chapter}, and so on.

@item tag_level
The sectioning element name, with @code{@@raisesections} and 
@code{@@lowersections} taken into account.

@item top
True if it is the top element.
@end table

@item $command
The heading @@-command.

@item $command_texi_arg
The argument of the @@-command, unformatted.

@item $formatted_arg
The argument of the @@-command, formatted.

@item $in_preformatted
True if in preformatted environment.

@item $one_section
True if there is only one section.

@item $element_heading
True if the heading is the main component of the element.
@end table
@end deftypefn

It is also possible to customize the heading text with section number
with this function reference (called for headings and nodes):

@deftypefn {Function Reference} $result_texi heading_texi @
           $heading_command $heading $number
@var{$heading_command} is the sectioning @@-command of that heading.
@var{$heading} is the Texinfo input for that heading.  @var{$number}
is the heading number classically-computed with dots between numbers,
and letters for top-level appendix numbering.  This function should
return the Texinfo text corresponding with the numbered heading.
@end deftypefn

The label associated with the heading that can appear before the
heading itself and even before the navigation panel can be customized
with this function reference:

@deftypefn {Function Reference} $element_label element_label @
           $identifier \%element $command $unformatted_line
@var{$identifier} is the identifier associated with the heading.
@var{\%element} is the same as above.  @var{$command} is the
@@-command appearing on the line, and @var{$unformatted_line} is the
line, unformatted.
@end deftypefn

Additionally, for @code{@@node} and sectioning @@-commands, the
formatting of the label, navigation panel and heading is controlled
by:

@deftypefn {Function Reference} $element_heading_text element_heading @
           \%element $command $command_texi_arg $formatted_arg @
           $in_preformatted $one_section $element_heading $first_in_page @
           $is_top $previous_is_top $unformatted_line $element_id $new_element
@var{\%element}, @var{$command}, @var{$command_texi_arg},
@var{$formatted_arg}, @var{$in_preformatted}, @var{$one_section}, and
@var{$element_heading} are as above.  For the rest:

@table @var
@item $first_in_page
True if this is the first heading in a page.

@item $is_top
True if the heading is considered as a top element heading.

@item $previous_is_top
True if the previous element was a top element.

@item $unformatted_line
Holds the whole line, unformatted.

@item $element_id
The id of the heading.

@item $new_element
True if the heading is the first of an element.
@end table
@end deftypefn


@node Customizing Indices
@section Customizing Indices

@cindex Customizing indices
@cindex Indices, customizing
@vindex IDX_SUMMARY
To do something special with index entries outside of the Texinfo
source document (@pxref{Indices}), you should first set the
configuration variable @code{IDX_SUMMARY} true.  After that, various
function references will be called for each non-empty index: one for
initialization, one for each index entry, and one for finalization.

Another way to work with the index (and tables of contents) entries is
to specify the @option{--internal-links} option and use the resulting
table; @pxref{Invoking texi2any}.

@deffn {Function Reference} index_summary_file_begin $index_name @
       $is_printed $manual_name
This function is called once for each non-empty index used in the
document, before any calls to @code{index_summary_file_entry}.

@table @var
@item $index_name
The two-letter name of the index. 

@item $is_printed
True if this index has a corresponding @code{@@printindex} command.

@item $manual_name
The manual basename.
@end table
@end deffn

@deffn {Function Reference} index_summary_file_entry $index_name @
       $entry_text $entry_reference $formatted_entry $texi_entry @
       $entry_element_reference $entry_element_header $is_printed $manual_name 
This function is called for each entry of an index, in sorted order.
The sorting happens regardless of whether the index is actually printed.

@table @var
@item $index_name
The two-letter name of the index.

@item $entry_text
@itemx $formatted_entry
@itemx $texi_entry
The entry in plain text, formatted, and original source, respectively.

@item $entry_reference
The reference used for the index entry, in the form @samp{file#id}.

@item $entry_element_reference
The reference to the beginning of the element containing the index
entry, also in the form @samp{file#id} (@pxref{Output Elements
Defined}).

@item $entry_element_header
The formatted header of the element containing the index entry. 

@item $is_printed
True if this index has a corresponding @code{@@printindex} command.

@item $manual_name
The manual basename.
@end table
@end deffn

@deffn {Function Reference} index_summary_file_end $index_name $is_printed @
       $manual_name
This function is called once for each non-empty index used in the
document, after all calls to @code{index_summary_file_entry}.  The
arguments are the same as for @code{index_summary_file_begin}, above.
@end deffn


@node Customizing CSS
@section Customizing the CSS lines

@cindex Customizing CSS
@cindex CSS customization

@vindex %css_map
@vindex INLINE_CSS
@vindex NO_CSS
The @code{NO_CSS} configuration option turns off CSS support.  Instead
of CSS lines being output at the beginning of the document, they may
be added to HTML attributes, if @code{INLINE_CSS} is set.

The configuration variable holds the CSS specification lines when CSS
is not inline.  It is possible to modify the CSS lines by modifying
the entries or adding to the @code{%css_map} hash.  Each key is a CSS
selector, the corresponding value is a style string.

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

@deffn {Function Reference} css_lines \@@import_lines \@@rule_lines
This function should set the variable @code{CSS_LINES}.
@var{\@@import_lines} is an array reference holding the
@code{@@import} lines of the files specified with
@option{--include-css}.  @var{\@@rule_lines} is an array reference
holding the CSS lines of those. files.
@end deffn


* Customizing HTML Basic Commands:: Commands with no arguments, images, etc.
* Customizing HTML References::     @code{@@xref}, external node pointers, etc.
* Customizing HTML Footnotes::      Footnotes.
* Customizing HTML Block Commands:: Environments.
* Paragraph and preformatted region::
* Lists tables and definitions formatting::
* Menus indices and floats formatting::
* Handling special regions::
* Other and unknown commands::

@node Customizing HTML Basic Commands
@section Customizing HTML Basic Commands

This section describes customizing the HTML output for the basic
Texinfo commands used within the running text.

@menu
* Argless: HTML Customization for Commands Without Arguments.
* @@-Colon: HTML Customization After @@-Colon.
* Simple: HTML Customization for Simple Commands.  Indicators, accents, etc.
* Anchors: HTML Customization for Anchors.
* Images: HTML Customization for Images.
* sp: HTML Customization for @code{sp}.
* Abbrs: HTML Customization for Abbreviations. @code{@@acronym}, @code{@@abbr}.
* Text: HTML Customization for Text Sequences.  @code{-- --- `` ''}, etc.
* Title: HTML Customization for Title Commands.  @code{@@title}, etc.
@end menu


@node HTML Customization for Commands Without Arguments
@subsection HTML 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@{@}}.

Each of these categories of commands have associated hashes for each
expansion context: normal, preformatted, string, and math (@pxref{Init
File Expansion Contexts}).  The keys of each hash are the command
names, the associated value is the text replacing the command.  In
math context, if a command is not a key of these hashes, the defaults
for the command are used.

@vindex %simple_map
@vindex %things_map
@vindex %simple_map_pre
@vindex %pre_map
@vindex %simple_map_texi
@vindex %texi_map
@vindex %simple_map_math
@vindex %math_map
The hashes are:

@multitable {preformatted} {one nonlettered character} {empty braces}
@headitem command type @tab one nonlettered character @tab empty braces
@item normal       @tab @code{%simple_map}      @tab @code{%things_map}
@item preformatted @tab @code{%simple_map_pre}  @tab @code{%pre_map}
@item string       @tab @code{%simple_map_texi} @tab @code{%texi_map}
@item math         @tab @code{%simple_map_math} @tab @code{%math_map}
@end multitable

To change the formatting of a command, change the associated value in
the desired hash.  For example, if you want @code{&shy;} to be output
for @code{@@-} in normal and preformatted context, write this in your
init file:

@example
$simple_map@{'-'@} = '&shy;';
$simple_map_pre@{'-'@} = '&shy;';
@end example

@vindex %sorting_things_map
An additional hash is used preferentially when sorting indices,
overriding @code{%texi_map} entries: @code{%sorting_things_map}.

For better control, function references are available, although they
are not used in string context.  @code{simple_command} is for
formatting of the single-nonletter @@-commands:

@deftypefn {Function Reference} $formatted_command simple_command
           @ $command $in_preformatted $in_math $line_nr \%state
@var{$command} is the @@-command name.  @var{$in_preformatted} is true
if in a preformatted region.  @var{$in_math} is true if in math.
@var{$line_nr} is an opaque structure containing information about the
line number of the @@-command.  @var{\%state} holds information about
the current context.
@end deftypefn

For @@-commands with empty brace arguments, @code{thing_command} may
be redefined:

@deftypefn {Function Reference} $formatted_command thing_command
           @ $command $text $in_preformatted $in_math $line_nr \%state
@var{$text} is the formatted text appearing in the @@-command.  It is
invalid Texinfo to have anything other than the empty string there.
@var{$command}, @var{$in_preformatted}, @var{$in_math},
@var{$line_nr}, and @var{\%state} are as above.
@end deftypefn


@node HTML Customization After @@-Colon
@subsection HTML Customization After @@-Colon

@cindex HTML customization after @code{@@:}
@cindex Punctuation after @code{@@:}, customizing HTML for
@cindex Sentence punctuation, customizing HTML for

@vindex %colon_command_punctuation_characters
The formatting of a punctuation character followed by @code{@@:} is
determined by the hash @code{%colon_command_punctuation_characters}.
If a @code{@@:} command is preceded by a character in this hash, it is
replaced by the associated value.  By default, the associated value is
also the character, so this leaves the punctuation character
unmodified.

The following function reference may be redefined to handle characters
that are in @code{%colon_command_punctuation_characters}:

@deftypefn {Function Reference} $punctuation colon_command $character
@var{$character} is a character appearing in
@code{%colon_command_punctuation_characters} and preceding an
@code{@@:} command.  By default, the associated value in
@code{%colon_command_punctuation_characters} is returned.
@end deftypefn


@node HTML Customization for Simple Commands
@subsection HTML Customization for Simple Commands

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

@vindex %style_map
@vindex %style_map_pre
@vindex %style_map_texi
@vindex %style_map_math
The formatting of the output produced by ``indicator'' and font
commands (e.g., @code{@@code}, @code{@@t}, @code{@@titlefont}), the
accent-related commands with arguments (e.g., @code{@@'},
@code{@@udotaccent}, @code{@@dotless}) and other simple commands with
arguments (e.g., @code{@@w}, @code{@@uref}, @code{@@math},
@code{@@asis}) is controlled by the following hashes by default
(@pxref{Init File Expansion Contexts}):

@table @code
@item %style_map
In normal context.

@item %style_map_pre
In preformatted context.

@item %style_map_texi
In string context.  

@item %style_map_math
Preferentially in math context, falling back to other hashes if not found.
@end table

If defined, a function reference is called at the @@-command opening:

@deffn {Function Reference} begin_style_texi $command \%state \@@stack @
       $real_style_or_accent $remove_texi
@table @var
@item $command
The @@-command name. 

@item \%state
Information about the current context. 

@item \@@stack
An opaque variable.

@item $real_style_or_accent
Set if the command is an accent or a font command.

@item $remove_texi
Set if in a context where output is simple text.
@end table
@end deffn

@vindex %accent_map
The nonlettered accent commands where the following character is taken
as the argument (e.g., @code{@@`a}) should be keys of the
@code{%accent_map} hash, even if no value is associated.

Command with braces may be handled differently; @pxref{Init File
Formatting of Commands}.  For example, this is used for @code{@@math}
if @LaTeX{}2HTML is used.

The key of the hashes are the command names.  The values may be
strings or hash references.  The hash reference interface is the only
one described in this manual, the other is retained primarily for
backward compatibility.  You can also define your own interface.

@menu
* Hash Interface for Simple HTML Customization::
* Custom Interface for Simple HTML Customization::
@end menu


@node Hash Interface for Simple HTML Customization
@subsubsection Hash Interface for Simple HTML Customization

@cindex Hash interface for simple HTML customization
@cindex Interface for simple HTML customization, hash

The keys of the hashes given above are Texinfo command names.  The
values determine how the command argument is formatted.  Each value is
a hash reference.  In this value hash, each key corresponds with a
type of information for formatting, and the value is the corresponding
data.

Here's an example:

@example
$style_map@{'command'@} = @{
  'args' => ['code'],
  'inline_attribute' => 'code',
@};
@end example

Here, the arguments for @code{@@command} are interpreted as specified
by the values associated with the @samp{args} key, namely a code
argument; and the @code{inline_attribute} associated with that command
is @samp{<code>}.

Here is a list of the possible keys in the value hashes:

@table @samp
@item args
@anchor{Reference Hash Args}
The value associated is an array reference.  Each element of the array
defines how the corresponding argument (separated by @samp{,} in the
Texinfo input) for the @@-command should be formatted.  The
possibilities are:

@table @code
@item normal
for normal text,

@item code
for text where @samp{---}, @samp{--}, @samp{''}, and @samp{``} should
be kept as-is, and

@item keep
if the input should be kept entirely as-is, with no interpretation of
any @@-commands.
@end table

The default is @samp{['normal']} for one normally-interpreted argument.

For example, we specify

@example 
$style_map@{'email'@}->@{'args'@} = ['code', 'normal'];
@end example

because @samp{---}, @samp{--}, @samp{''} and @samp{``} should be kept
as-is in the first argument of @code{@@email}
(@pxref{email,, @code{@@email}}).

@item attribute
If the associated value is a word, it is considered to be an XML
element name, and the argument is enclosed between the element opening
and the element closing. For example, if the value is @code{elem}, the
resulting HTML is @code{<elem>@var{arg}</elem>}.

If the text is a word followed by some text, the word is interpreted
as above, and the text is considered to be the attributes text of the
element.  Thus @code{elem class="elem"} leads to @code{<elem
class="elem">@var{arg}</elem>}.  This only works if there is only one
argument.

@item inline_attribute
Like @code{attribute}, except that it is closed at each paragraph end
and reopened at each beginning of paragraph.  This is more often used
than @samp{attribute} since it allows to have well-formed HTML and
XML.

@item inline_begin
The associated value is added in front of the text and each time a
paragraph is restarted while within the command.

@item inline_end
The associated value is added after the text and each time a paragraph
is ended while within the command.

@item begin
The associated value is added in front of the text.

@item end
The associated value is added after the text. 

@item quotes
If the corresponding value is true, the result is enclosed in quotes
associated with configuration variables @code{OPEN_QUOTE_SYMBOL} and
@code{CLOSE_QUOTE_SYMBOL}; the defaults depend on the output format
but fall back to @samp{`} and @samp{'}.

@item function 
The corresponding value should be a function reference, which is
called with the following arguments:

@table @code
@item $command
The @@-command name.

@item \@@args
An array reference containing the arguments of the @@-command.

@item \@@command_stack
An array reference with the names of the @@-commands containing the
@@-command being formatted, latest on top.

@item \%state
A hash reference containing context information.

@item $line_nr
An opaque structure containing line number information for the
@@-command.  It can be used to call @code{main::line_error} or
@code{main::line_warn} with the first argument being the message, and
the second argument @code{$line_nr}.

@item \@@line_numbers
An array reference containing the line numbers (the same opaque
structure as above) of the lines produced by the @@-command.
@end table
@end table


@node Custom Interface for Simple HTML Customization
@subsubsection Custom Interface for Simple HTML Customization

@cindex Custom interface for simple HTML customization
@cindex Interface for simple HTML customization, custom

If the hash interface described in the previous section does not
suffice, it is possible to change how the ``simple'' Texinfo commands
are processed by redefining the following function reference:

@deftypefn {Function Reference} $resulting_text style $style $command $text @
       $args $no_close $no_open $line_nr \%state $command_stack \@@line_numbers
@table @var
@item $command
The @@-command

@item $style
The value associated with the @var{$command} in the @code{%style_map},
@code{%style_map_pre} or @code{%style_map_texi} hashes.

@item $text
The argument text appearing within the @@-command braces.

@item $args
Array reference containing the command arguments, formatted according
to the same conventions as the hash reference style (provided that the
value associated with the @@-command is a hash reference with an
@var{$arg} key; @pxref{Reference Hash Args}).

@item $no_close
@itemx $no_open
If @var{$text} is split into paragraphs, each paragraph is passed
through the function, and @var{$no_close} is true if this is not the
last paragraph, while @var{$no_open} is true if this is not the first
paragraph.

@item $line_nr
@itemx \%state
@itemx $command_stack
@itemx \@@line_numbers
See the previous section.
@end table
@end deftypefn


@node HTML Customization for Anchors
@subsection HTML Customization for Anchors

@cindex HTML customization for anchors
@cindex Anchors, customizing HTML for

The HTML formatting of anchors (@pxref{anchor,, @code{@@anchor}}) is
controlled by functions.  To customize the output, the function
reference @code{$anchor_label} should be redefined.  The function
should return the formatted text.

@deftypefn {Function Reference} $anchor_label anchor_label $identifier $anchor
@var{$identifier} is the anchor identifier, and @var{$anchor} is the
@code{@@anchor} argument.
@end deftypefn

By default, this uses a function reference, @code{$anchor}, which can
do a reference target or link. This is especially relevant for HTML
but can potentially be used in other formats, since it is a rather
common element among output formats.

@deftypefn {Function Reference} $anchor anchor @
           $identifier $href $text $attributes
If @var{$identifier} is not empty, its value should be used to create
a target for links (typically associated with a name or id attribute
in HTML).  The @var{$href} argument specifies a hypertext reference
which should be used to link to a target.  If both @var{$identifier}
and @var{$href} are given, the text produced should be both a target
for @var{$identifier} and a link to @var{$href}.  @var{$text} is the
text to be displayed.  @var{$attributes} are additional attributes for
an @code{<a>} HTML element.
@end deftypefn


@node HTML Customization for Images
@subsection HTML Customization for Images

@cindex HTML customization for images
@cindex Images, customizing HTML for

@vindex @@IMAGE_EXTENSIONS
To customize the images produced by @code{@@image} (@pxref{Images}),
the first possibility is to modify the @code{@@IMAGE_EXTENSIONS}
array, which holds a list of filename extensions for image files.

Second, it is also possible to redefine the function used to determine
the filename of the image:

@deftypefn {Function Reference} $filename image_files @
           $basename $extension $texi_base $texi_extension
@var{$basename} is the first @code{@@image} argument, and
@var{$extension} is the corresponding @code{@@image} argument; both
are formatted.  @var{$texi_base} is the first @code{@@image} argument
and @var{$texi_extension} is the extension, unformatted.  This
function reference should return an array of array references, each
holding both formatted and unformatted image filenames without any path
for which the main program should look.
@end deftypefn

Third, it is possible to control the formatting of @code{@@image} by
redefining this:

@deftypefn {Function Reference} $image image $file_path $basename @
           $preformatted $file_name $alt_text $width $height $raw_alt @
           $extension $working_dir $file_relative_path $in_paragraph @
           \@@file_locations $base_simple_format @
           $extension_simple_format $file_name_simple_format $line_nr
@table @var
@item $file_path
The image file name with the path from the output directory to the
source manual directory prepended.

@item $basename
The file name without extension---the first argument to the
@code{@@image} command.

@item $preformatted
True if the image appears in preformatted text.

@item $file_name
The file name without path but with extension.

@item $alt_text
The alternate text, possibly undefined.

@item $width
@itemx $height
The corresponding @code{@@image} arguments.

@item $raw_alt
The unmodified alternate-text @code{@@image} argument.

@item $extension
The corresponding @code{@@image} argument.

@item $working_dir
Path to the working directory relative to the output directory.

@item $file_relative_path
The file name relative to @var{$working_dir}.

@item $in_paragraph
True if within a paragraph.

@item \@@file_locations
Array reference holding another array reference with 3 elements: the
file name array reference as returned by @code{image_files}; the image
location if it was found, or undef; and the file name formatted using
simple formatting in string context.

@item $base_simple_format
@itemx $extension_simple_format
@itemx $file_name_simple_format
The corresponding arguments formatted using simple formatting in
string context.

@item $line_nr
An opaque structure containing the information about the line number
of the @@-command.
@end table
@end deftypefn


@node HTML Customization for @code{sp}
@subsection HTML Customization for @code{sp}

@cindex HTML customization for @code{sp}
@cindex @code{sp}, customizing HTML for

The formatting of @code{@@sp} (@pxref{sp,,@code{@@sp}}) is controlled by:

@deftypefn {Function Reference} $sp sp $number $preformatted
@var{$number} is the numeric argument of @code{@@sp}.
@var{$preformatted} is true if the @code{@@sp} appears in preformatted
text.
@end deftypefn


@node HTML Customization for Abbreviations
@subsection HTML Customization for Abbreviations

@cindex HTML customization for abbreviations
@cindex @code{abbr}, customizing HTML for
@cindex @code{acronym}, customizing HTML for

The formatting of @code{@@acronym} and @code{@@abbr} (@pxref{acronym,,
@code{@@acronym}} and @ref{abbr,, @code{@@abbr}}) is controlled by:

@deftypefn {Function Reference} $acronym acronym_like @
           $acronym_texi $acronym_text $with_explanation \@@explanation_lines @
           $explanation_text $explanation_simply_formatted

@var{$acronym_texi} is the original acronym argument with @@-commands,
while @var{$acronym_text} is formatted.

The other arguments are related to the explanation (the second arg of
the acronym).  @var{$with_explanation} is true if the second argument
of the acronym command is present.  If an explanation exists, coming
from a previous @code{@@acronym} or as an argument to the present
command, the remaining arguments are defined:

@table @var
@item \@@explanation_lines
Array reference containing simply formatted explanation lines
(@pxref{Init File Expansion Contexts}).

@item $explanation_text
Formatted explanation text.

@item $explanation_simply_formatted
Explanation simply formatted in a string context.
@end table
@end deftypefn


@node HTML Customization for Text Sequences
@subsection HTML Customization for Text Sequences

@cindex HTML customization for text sequences
@cindex Text sequences, customizing HTML for
@cindex Ligatures in text, customizing HTML for

Some character sequences are processed especially in text: @samp{---},
@samp{--}, @samp{``} and @samp{''}. This should only be done only if
in normal text and not within commands for preformatted output
(@code{@@code}, @code{@@env}@dots{}).  A function reference is called
to process the text and take care of these constructs.  It may also be
used to transform the text, for example, convert to upper case if it
is in @code{@@sc}.  The function should also take care of protecting
special characters.

@deftypefn {Function Reference} $processed_text normal_text $text @
     $in_raw_text $in_preformatted $in_code $in_math $in_simple $command_stack 
Process @var{$text} and return @var{$processed_text}.  The other
arguments give some information about the context of the text.

@table @var
@item $in_raw_text
True if the text appears in a place where there is no formatting at
all; e.g., in comments.

@item $in_preformatted
True if within a preformatted environemnt

@item $in_code
True if within a special command such as @code{@@code} or @code{@@env}
where the text sequences should be left as is.

@item $in_math
True if within @code{@@math}.

@item $in_simple
True if in a string context with minimal formatting.

@item $command_stack
Array containing the name of the formatting @@-commands that enclose
the text.
@end table

By default, the @samp{---}, @samp{--}, @samp{``} and @samp{''}
constructs are expanded if needed and the text is upper-cased if in
@code{@@sc}.  Special characters (@samp{&}, @samp{"}, @samp{<} and
@samp{>} in HTML) are protected if needed.
@end deftypefn

@cindex Protecting special output characters
@cindex Output format characters, protecting
@cindex HTML characters, protecting
Some characters are special in a particular output format, such as
@samp{<} in HTML.  Some text is not processed by the above function,
but still needs protection before output.  This is done by the
following:

@deftypefn {Function Reference} $protected_text protect_text $text
Process the general text @var{$text} and return the resulting
protected text @var{$protected_text}.
@end deftypefn

@cindex Empty lines, removing
Empty lines are processed by the following function reference, which
can be useful if empty lines are to be removed.

@cindex Definition commands, empty lines after
@deftypefn {Function Reference} $resulting_text empty_line $empty_line $state
Process @var{$empty_line} and return @var{$resulting_text}.
@var{$state} is a structure holding information about the state of
parsing.  By default, empty lines are left as-is except right after a
definition @@-command.
@end deftypefn


@node HTML Customization for Title Commands
@subsection HTML Customization for Title Commands

@cindex HTML customization for title commands
@cindex Title commands, customizing HTML for

@vindex %line_command_map
Some @@-commands related to titles appear on a line by themselves and
take the rest of the line as their argument: @code{@@titlepage},
@code{@@title}, @code{@@subtitle}, and @code{@@author}
(@pxref{Titlepage & Copyright Page}).  These are listed in
@code{%line_command_map} and the following function reference is used
to format them:

@deftypefn {Function Reference} $resulting_text line_command @
           $command $arg_text $arg_texi \%state

@var{$command} is the @@-command, @var{$arg_text} is the
@@-command's formatted argument, and @var{$arg_texi} is the @@-command
argument without any formatting.  @var{\%state} is a hash reference
containing context information.  The function returns
@var{$resulting_text}.
@end deftypefn

For more customization of title pages, @pxref{HTML Title Page
Customization}.


@node Customizing HTML References
@section Customizing HTML References

@cindex References, HTML customization for 
@cindex Cross references, HTML customization for 

@menu 
* Internal: HTML Customization for Internal References.
* External: HTML Customization for External References.
@end menu


@node HTML Customization for Internal References
@subsection HTML Customization for Internal References

@cindex HTML customization for internal references
@cindex Internal references, HTML customization for 

This function reference is used to format a reference to a node in the
current manual (@pxref{Cross References}).

@deftypefn {Function Reference} $text internal_ref $command $href $short_name @
           $name $is_section \@@args_texi \@@formatted_args \%element

@table @var
@item $command
The reference command, namely @code{ref}, @code{xref}, @code{pxref} or
@code{inforef}).

@item $href
An HTML href to the node.

@item $short_name
@itemx $name
The text for the reference.  @var{$short_name} can be the node name
which is assumed to be no longer than the section name.

@item $is_section
True if the reference is to a sectioning element. 

@item \@@args_texi
@itemx \@@formatted_args
Array references containing the @@-command arguments, not formatted
and formatted, respectively.

@item \%element
Hash reference with information about the target element of the
reference.
@end table

The function should return the full formatted text of the internal 
reference.
@end deftypefn


@node HTML Customization for External References
@subsection HTML Customization for External References

@cindex HTML customization for external references
@cindex External references, HTML customization for 

These references are produced by one of two function references:
@code{external_href} is used for menu items which refer to other
manuals (@pxref{Other Info Files}), while @code{external_ref} is used
for full external cross references (@pxref{Four and Five Arguments}).

@deftypefn {Function Reference} $href external_href $node $node_identifier @
           $xml_node_identifier $file 
This function formats a reference to a node in an external Texinfo manual.

@table @var
@item $node
The node name, with @@-commands.

@item $node_identifer
The node name mapped to an identifier acceptable as a file name.

@item $xml_node_identifier
The node name mapped to an identifier acceptable for XML.

@item $file
The manual file name of the external reference.
@end table

The function should return an HTML href for the external reference.

@xref{HTML Xref}, for how the identifiers are built in order to allow
for cross references to external manuals to succeed.
@end deftypefn

@deftypefn {Function Reference} $text external_ref $command $section $book @
           $file $href $cross_ref_name \@@args_texi \@@formatted_args $node 
This function formats a general cross reference to an external Texinfo manual.

@table @var
@item $command
The reference command (@code{ref}, @code{xref}, @code{pxref} or
@code{inforef}).

@item $section
The section in the external manual; may be empty.

@item $book
The book title; may be empty.

@item $file
The manual file name.

@item $href
An HTML href to the external manual constructed using the above
@code{external_href} function.

@item $cross_ref_name
Optional cross reference name appearing in the reference command.

@item \@@args_texi
@itemx \@@formatted_args
Array references containing the @@-command arguments, not formatted
and formatted, respectively.

@item $node
The node name, formatted.
@end table

The function should return the HTML text for the external manual
reference.  
@end deftypefn


@node Customizing HTML Footnotes
@section Customizing HTML Footnotes

@cindex Customizing HTML footnotes
@cindex Footnotes, customizing HTML

Each footnote is associated with a footnote entry.  Several footnote
entries are grouped in a footnote section.  When a footnote appears,
two things must be formatted: the footnote text, and the place in the
main text where the footnote marker appears.

It is possible to replace the footnote with other text before
formatting the footnote. The following function reference
is used for this if it is defined:

@deftypefn {Function Reference} $added_text footnote_texi $footnote_text @
           \%state \@@command_stack
@table @var
@item $footnote_text
The footnote text.

@item \%state
Hash referencing with information about the context of the footnote
location in the main document.  Specifically, the entries
@code{\%state->@{'outside_document'@}} or
@code{\%state->@{'multiple_pass'@}} can be used.

@item \@@command_stack
Array reference containing the commands enclosing the footnote.
@end table

This function should return new formatted text for the footnote.
@end deftypefn

Two functions, with corresponding function references, control the
formatting of the footnotes:

@deftypefn {Function Reference} {(\@@lines $doc_text)} foot_line_and_ref @
           $number_in_doc $number_in_page $footnote_id $place_id @
           $document_file $footnote_file \@@lines \%state 
@table @var
@item $number_in_doc
The footnote number counted through the whole document, 

@item $number_in_page
The footnote number counted on the current page.

@item $footnote_id
An identifier for the footnote text, which should be used to make the
target for references to the footnote.

@item $place_id
Identifier for the location of the footnote in the main document.

@item $document_file
Name of the file containing the text where the footnote appears in the
main document

@item $footnote_file
Name of the file where the footnote text appears.

@item \@@lines
Array reference containing the footnote text lines, formatted.

@item \%state
Information about the context at the footnote location in the main
document.  As usual, the most useful entry is @code{preformatted},
which is true if the footnote appears in a preformatted context.
@end table

The function should return a list of two elements: an array reference
(@var{\@@lines}) containing the updated footnote text for the footnote
entry, and a string (@var{$doc_text}), for the text to appear at the
location of the footnote in the main document, i.e., linking to the
footnote entry.
@end deftypefn

The following function is only used when footnotes are at the bottom
of a page and the document is split.  For customization in the case
when footnotes are on a separate page or section, @pxref{Customizing
Layout of Special Elements}.  The footnote location is determined by
@code{footnotestyle} (@pxref{Footnote Styles}).

@deffn {Function Reference} foot_section \@@footnotes_lines
This function formats a group of footnotes.  @var{\@@footnotes_lines}
is an array reference holding the lines of all the footnote entries
formatted as explained above.  The function should modify the
reference.
@end deffn


@node Customizing HTML Block Commands
@section Customizing HTML Block Commands

@cindex Customizing HTML block commands
@cindex Block commands, customizing HTML
@cindex Environments, customizing HTML

@menu
* Align: HTML Customization of Alignment Commands.  @code{@@flushleft}, etc.
* Preformatted block command formatting::
* Other block commands formatting::
@end menu

@node HTML Customization of Alignment Commands
@subsection HTML Customization of Alignment Commands

@cindex HTML customization of alignment environments
@cindex Customization of alignment environments
@cindex Alignment environments, HTML customization of
@cindex @code{@@center}, HTML customization of
@cindex @code{@@flushleft}, HTML customization of
@cindex @code{@@flushright}, HTML customization of

@vindex %paragraph_style
When a block with special text alignment of text is used, namely
@code{@@center} (@pxref{titlefont center sp},,
@code{@@titlefont}@comma{} @code{@@center}@comma{} and @code{@@sp}),
@code{@@flushleft} or @code{@@flushright} (@pxref{flushleft &
flushright,, @code{@@flushleft} and @code{@@flushright}}, the main
program takes care of opening and closing paragraphs.  The alignment
commands are the keys in the @code{%paragraph_style} hash.  The value
is used in the function doing the formatting of the paragraphs
(@pxref{Paragraph and preformatted region}).

This function reference allows for customizing the formatting of the
command argument.

@deftypefn {Function Reference} $result paragraph_style_command $command $text
@var{$command} is the command name and @var{$text} is the text
appearing within the command.  This function should return the
formatted text.  The default is to return the text unmodified.
@end deftypefn


@node Preformatted block command formatting
@subsection Preformatted block command (@code{@@example}, @code{@@display}@dots{}) formatting

Here we see how a whole preformatted block command is 
formatted.  For the formatting
of the text, see @ref{Paragraph and preformatted region}.

@vindex %complex_format_map
The formatting of the block commands is ultimately controlled by a
function, however the default for this function uses a hash and 
changing the hash values should be enough in most cases. This
hash is called @code{%complex_format_map}. It has a key for each
of the preformatted block commands (@code{example}, @code{smallexample}, 
@code{lisp}, @code{smalllisp}, @code{display}, @code{smalldisplay}, 
@code{format}, @code{smallformat}).

The associated value is a reference on a hash.  The keys are:

@table @code
@item begin
The @code{begin} should lead to the beginning of the
formatted output.
@item end
The @code{end} should lead to the end of the 
formatted output.
@item class
The HTML class.  If not defined, the command name.
@item pre_style
The preformatted style. If not defined the corresponding @acronym{CSS} style
is used.
@item style
If the associated value is @code{code}, the format is assumed to be in 
code style, where 
with @samp{---}, @samp{--}, @samp{''} and  @samp{``} kept as is.
If the key is absent the format  inherits the code style
and the font from the enclosing context.
@end table 
The enclosed text will be formatted as described in
@ref{Paragraph and preformatted region}, and the name of the complex
format will be available to the function formatting the text.

If you aren't satisfied with this scheme, you can redefine the following
function reference for a better control over the complex format formatting:

@deftypefn {Function Reference} $complex_format_text complex_format $format_name $preformatted_text

@var{$format_name} is the complex format name, @var{$preformatted_text} is the 
text allready formatted as described in @ref{Paragraph and preformatted region}.
This function returns the whole complex format.
@end deftypefn

@node Other block commands formatting
@subsection Formatting of other block commands (@code{@@verbatim}, @code{@@cartouche}, @code{@@quotation}, @code{@@html})

@c FIXME verbatiminclude is distinct
Regions corresponding with raw text, like @code{@@verbatim}, @code{@@html}, 
@code{@@tex} or the content of the file given in @code{@@verbatiminclude} 
argument are formatted according to the following function reference:

@deftypefn {Function Reference} $raw_region raw $command $text
@var{$command} is the command name, @var{$text} is the raw text.
In the default case, if @var{$command} is @code{verbatiminclude} 
the text is the content of the @code{@@verbatiminclude} file argument.
@end deftypefn

If La@TeX{}2HTML is used, @code{@@tex} regions are handled differently,
(@pxref{Init File Formatting of Commands}).

The @code{@@cartouche} command formatting is controlled by the
function reference:

@deftypefn {Function Reference} $cartouche cartouche $text
@var{$text} is the text appearing within the cartouche.
@end deftypefn

The formatting of @code{@@quotation} and @code{@@smallquotation} 
is controlled by two function references.
The first one is usefull in case the @code{@@quotation} has an argument, as
it allows to prepend a string to the quotation text:

@deftypefn {Function Reference} $prepended_string quotation_prepend_text $command $text
@var{$command} is the @@-command.
@var{$text} is the argument of the quotation with @@-commands not 
interpreted. This function
can return a string which will be prepended to the quotation text.
@end deftypefn

The whole quotation is formatted by:

@deftypefn {Function Reference} $quotation quotation $command $quotation_text $argument_text $argument_text_texi \@@quote_authors
@var{$command} is the @@-command.
@var{$quotation_text} is the quotation text, formatted, with the text 
prepended by the function above.  @var{$argument_text} is the argument 
of the @code{@@quotation}, formatted.  @var{$argument_text_texi} is the argument
of the @code{@@quotation}, simply formatted.
@var{\@@quote_authors} is a reference on an array holding information 
about the @code{@@author} command arguments appearing within the 
@code{@@quotation}.  Each of the array element is a reference on a 
hash with the following keys:
@table @code
@item author_texi
Texinfo code of this @code{@@author} line.
@item author_text
Formatted argument of the @code{@@author} line.
@end table
@end deftypefn

@node Paragraph and preformatted region
@section Formatting of paragraph and preformatted regions


@c FIXME not sure that it is stable enough to be documented?
If defined, the following function reference is called at the paragraph
opening:

@deffn {Function Reference} begin_paragraph_texi $paragraph_or_preformatted \@@paragraph_at_commands $context_command \%state \@@stack
@var{$paragraph_or_preformatted} is @samp{paragraph} when opening a paragraph,
or @samp{preformatted} at the beginning of a preformatted region.
@var{\@@paragraph_at_commands} is a reference on an array containing the
listof th ecommands with brace opened outside of the paragraph or 
preformatted.  @var{$context_command} is a reference on a structure describing
in what generalized block @@-command we are.
@var{\%state} holds informations about the current context. 
@var{\@@stack} is an opaque variable.
@end deffn

@menu
* Paragraph and preformatted formatting::
* Avoiding paragraphs::
@end menu

@node Paragraph and preformatted formatting
@subsection Paragraph and preformatted region formatting

The formatting of a paragraph region or a preformatted region, is controlled
by function references:

@deftypefn {Function Reference} $paragraph_text paragraph $text $alignement $index $formatting_command $formatting_command_formatted \$paragraph_number $format $item_number $enumerate_style $number $command_stack_at_end $command_stack_at_begin
This function formats a paragraph.  @var{$text} is the text of the paragraph,
@var{$alignement} is the empty string when no alignement command has
been seen, otherwise it is the current alignement command name (see
the previous section).
@var{$indent} holds @samp{noindent} or @samp{indent} if the corresponding 
@@-command appeared in the paragraph.
@var{$command_stack_at_end} and @var{$command_stack_at_begin} are arrays
containing the opened @@-commands at end and at beginning of the paragraph,
latest on top.

The remaining arguments are usefull when the paragraph appears within a
list or table.  It is usefull whenever the paragraph has to be formatted
differently when appearing in such environments. 
Moreover in that case the format command (@code{@@itemize}@dots{}) 
may have an associated formatting command.
@var{$formatting_command} is this  formatting command
(like @code{@@minus}).
@var{$formatting_command_formatted} is the command formatted in html
in case the formatting command is a leading command (like @code{@@minus})
which should be leading the first paragraph.
@var{\$paragraph_number} is a reference on the number of
paragraphs in that format command.  The corresponding variable should be 
increased when a paragraph is added.  @var{$format} is the format command. 
@xref{Table and list items formatting}.

If the @var{$format} is an enumerate, @var{$item_number} is the number of 
the item in the list, @var{$enumerate_style} is the argument of the enumerate,
@var{$number} is the number or letter corresponding with this item. 
@end deftypefn

@deftypefn {Function Reference} $preformatted_text preformatted $text $style $region_name $formatting_command $formatting_command_formatted \$preformatted_number $format $item_number $enumerate_style $number $command_stack_at_end $command_stack_at_begin
This function formats a preformatted region.  @var{$text} is the text of the
preformatted region, @var{$style} is the css style associated with that
preformatted region (@pxref{Customizing CSS}).  @var{$region_name} is the 
name of the command opening        
the preformatted region (@code{example}@dots{}, see @ref{Preformatted block command formatting}) 
or a identifier for the preformatted context (for example 
@code{menu-comment}, see @ref{Menu formatting}).
The alignment commands are not taken into account, as the spaces are
preserved in preformatted regions, you should flush and center by hand.
@var{$command_stack_at_end} and @var{$command_stack_at_begin} are arrays
containing the opened @@-commands at end and at beginning of the preformatted
region, latest on top.

The remaining arguments are usefull when the preformatted region appears 
within a list or table.  It is usefull whenever the preformatted region 
has to be formatted
differently when appearing in such environments. 
Moreover in that case the format command (@code{@@itemize}@dots{}) 
may have
an associated formatting command.
@var{$formatting_command} is this formatting command
(like @code{@@minus}).
@var{$formatting_command_formatted} is the command formatted in html
in case the formatting command is a leading command (like @code{@@minus})
which should be leading the first preformatted region.
@var{\$preformatted_number} is a reference on the number of
preformatted regions in that format command.  The corresponding variable 
should be increased when a preformatted region is added. @var{$format} is the 
format command.
@xref{Table and list items formatting}.

If the @var{$format} is an enumerate, @var{$item_number} is the number of 
the item in the list, @var{$enumerate_style} is the argument of the enumerate,
@var{$number} is the number or letter corresponding with this item. 
@end deftypefn

A special function reference is called instead if the preformatted
is empty and the function reference is defined:

@deftypefn {Function Reference} $preformatted_text empty_preformatted $text
@var{$text} is the text of th epreformatted which should contain only
spaces.  The function refernece should return the formatted text for 
this empty preformatted region.
@end deftypefn

@node Avoiding paragraphs
@subsection Avoiding paragraphs in @@-commands

@cindex Avoid paragraph opening

@vindex %format_in_paragraph
It is possible to avoid that a format closes the previous paragraph or
preformatted region and reopens one, by putting the format command in a 
hash, @code{%format_in_paragraph} with a true value.  This only 
makes sense for few commands since otherwise the nesting of formats and
paragraphs could become wrong.

@vindex %no_paragraph_commands
If the value of @code{%no_paragraph_commands} associated with a command is
true, no paragraph is started by the command if outside of a paragraph
(after an empty line, for example).  If the value is set to 0, it will start
a paragraph.  If the value is not set, reasonable defaults are
set.

@vindex %stop_paragraph_command
It is also possible to stop a paragraph when an @@-command happens by
putting the @@-command in the @code{%stop_paragraph_command} hash
associated with a true value.

@node Lists tables and definitions formatting
@section Lists, tables and definitions formatting

@menu
* Lists and tables formatting::
* Definition formatting::
@end menu

@node Lists and tables formatting
@subsection Customizing the formatting of lists and tables

The formatting of lists and tables is done at two levels:
@itemize
@item 
At the level of the whole region (table or list),
@item
At the level of the individual items, rows or cells of the list or table.
@end itemize

@menu
* Table and list items formatting::
* Whole table and list formatting::
@end menu


@node Table and list items formatting
@subsubsection Formatting individual table and list items

In texinfo it is possible to give @code{@@itemize} or table command (hereafter
called a @dfn{format command}) a @dfn{formatting command}. 
For example @code{@@minus} is the formatting command here:
@example
@@table @@minus
@end example

@vindex %special_list_commands
The default is to apply the command to the text item, however it is possible
to avoid it.
The hash @code{%special_list_commands} has an entry for each of the 
format command.  Each of these entries is a hash reference.  If a formatting
command is a key of the hash reference, then the formatting command is not
applied to the text item for that format command.  For example, if we have:

@example
$special_list_commands@{'itemize'@} = @{ 'bullet' => '' @};
@end example

and we have the following @code{@@itemize}:
@example
@@itemize @@bullet
@@item an item
@@end itemize
@end example

then @code{@@bullet} will not be applied to @code{an item}.

Every time a @code{@@tab} or an @code{@@item} is encountered, the following 
function reference is called, if defined:
@deftypefn {Function Reference} $result_line tab_item_texi $command \@@command_stack \@@stack \%state $line $line_nr
@var{$command} is the command name.
@var{\@@command_stack} is an array with all the @@-commands opened, latest
on top.
@var{\@@stack} is an opaque variable.
@var{\%state} holds informations about the current context. 
@var{$line} is the line appearing after the command.
@var{$line_nr}
is an opaque structure containing the information about the line number of the 
@@-command. 
The function returns the line that may be further processed.
@end deftypefn


More control of the text before formatting of the line or the item is 
achieved with the following function reference:

@deftypefn {Function Reference} ($result_line, $open_command) format_list_item_texi $format $line $prepended $command $number
The @var{$format} is the list or table @@-command, 
@var{$line} is the item line, @var{$command} is the @dfn{format command},
@var{$prepended} is set to the text folllowing the @dfn{format command}
on the format argument line.
The @var{$number} is the number of the item, as set in @code{@@enumerate}.
The @var{$result_line} replaces the item argument.
@var{$open_command} is an obsolete return code that can be set to 
anything.
@end deftypefn

Then the different @@-commands items are formatted thanks to
function references:

@table @strong
@item lists
The items of lists are formatted using the following function reference:
@deftypefn {Function Reference} $list_item list_item $text $format $command $formatted_command $item_number $enumerate_style $number $prepended_texi $prepended_formatted $only_inter_item_commands $before_items $item_command
This function formats the text between @code{@@item} commands.  @var{$text} 
is the text corresponding with the item.  @var{$format} is the type of format,
@samp{itemize} or @samp{enumerate}.  @var{$command} is the formatting command
given in argument to @code{@@itemize}, @var{$formatted_command} is this command
formatted if it is a leading command, like @code{@@minus}.

If the @var{$format} is an enumerate, @var{$item_number} is the number of 
the item in the list, @var{$enumerate_style} is the argument of the enumerate,
@var{$number} is the number or letter corresponding with this item. 

If the @var{$format} is an itemize, @var{$prepended_texi} is the text that
appeared on the itemize line, maybe after the formatting command
(if any), and @var{$prepended_formatted} is the corresponding text, 
formatted.

@var{$only_inter_item_commands} is true if there are only @@-commands 
that are not considered as the item argument in the item, like
index entries.
@var{$before_items} is set if there is in fact no leading @code{@@item}
for the text, as it may happen for some text following the @var{$format} 
@@-command, as in 

@example
@@table @@asis
Tex before items.

@end example
@var{$item_command} is the item command name.

@end deftypefn

@item two column tables
The two columns tables (@code{@@table}, @code{@@ftable} and @code{@@vtable}), 
items are formatted using two function references,
one for the first line located on the @code{@@item} line corresponding
with the first column, the other for the text appearing on the
following lines, corresponding with the second column text.

@deftypefn {Function Reference} $table_item table_item $item_text $index_label_text $format $command \@@command_stack $item_command $formatted_index_entry
This function is used to format the text on the @code{@@item} line.
@var{$item_text} is the text line.  In case there is an index entry 
associated with the @code{@@item} (as with @code{@@ftable} and 
@code{@@vtable}), @var{$index_label_text} is the text inserted at 
the place where an index entry appears.  @xref{Index entry place formatting}.
@var{$format} is the type of format,
@samp{table}, @samp{ftable} or @samp{vtable}.  @var{$command} is the formatting command
given in argument to the table format command.
@var{\@@command_stack} is an array with all the @@-commands opened, latest
on top.
@var{$item_command} is the item command, @samp{@@item} or @samp{@@itemx}.
@var{$formatted_index_entry} is the index entry formatted.
@end deftypefn

@deftypefn {Function Reference} $table_line table_line $text
This function is used to format the text on the lines following
the @code{@@item} line. @var{$text} is the corresponding text. 
@end deftypefn

@item multitable
@anchor{Multitable Formatting}
The multitable elements formatting is controlled by the functions associated
with two function references.  One for a cell, and the other for a row.

@deftypefn {Function Reference} $multitable_cell cell $text $item_command \@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
This function is used to format the text of a multitable cell, the text 
following a @code{@@item} or a @code{@@tab}.
@var{$text} is the corresponding text. @var{$item_command} is the command 
used to introduce the row, such that it is possible to distinguish 
between @code{@@item} and @code{@@headitem}.
@var{\@@columnfractions} is a reference on an array 
containing the @code{@@columnfraction} arguments, if any, and 
@var{\@@prototype_row} is a reference on an array containing the row prototypes
given on the @code{@@multitable} line, if any.
@var{\@@prototype_lengths} array contains the lengths of the row prototypes
formatted.
@var{$column_number} is the maximal number of columns.
@end deftypefn

@deftypefn {Function Reference} $multitable_row row $text $item_command \@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
This function is used to format a multitable row. @var{$text} is
the row text, with cells allready formatted with the @code{$cell}
function reference. @var{$item_command}, @var{\@@columnfractions}, 
@var{\@@prototype_row}, @var{\@@prototype_lengths}
and @var{$column_number} are the same than in the function reference above.
@end deftypefn

@end table

By default, this function is interlinked with
@code{$begin_format_texi} (@pxref{Init File General Block Commands})
and @code{@@multitable} formatting since a stack of possibly nested
multitables is stored in order to know the cell number.


@node Whole table and list formatting
@subsubsection Formatting of a whole table or list

@vindex %format_map
If the Texinfo command is a key of the @code{%format_map}, the associated
value is used to specify the formatting of the construct, otherwise a function 
is called. 
The value in @code{%format_map} associated with a command is interpreted 
similarly with values associated with more simpler commands:

@itemize
@item
If the text is a word, in HTML or XML, it is considered to be an XML
or HTML element
name, and the whole table or list is enclosed between the element opening
and the element closing.
@item
If the text is a word followed by some text, 
the word and is interpreted as above, and the
text is considered to be the attributes text of the element. 
@item
If the text is empty nothing is added to the text.
@end itemize

In case the @code{%format_map} isn't used, a function reference called
@code{$table_list}
should be redefined, the associated function will be called each time
a command isn't found in @code{%format_map}.

@deftypefn {Function Reference} $whole_table_list table_list $format_command $text $command $formatted_command $item_nr $enumerate_style $prepended_texi $prepended_formatted \@@columnfractions \@@prototype_row \@@prototype_lengths $column_number
@var{$format_command} is the Texinfo command name, @var{$text} is the 
formatted items. @var{$command} is the @dfn{format command} given in argument
to the format command, @var{$formatted_command} is the same, but formatted.
@var{$prepended_texi} is the remaining text on the format command line,
@var{$prepended_formatted} is the same, but formatted.
Only relevant in @code{@@enumerate}, @var{$item_nr} is the item number, and 
@var{$enumerate_style} is the @code{@@enumerate} style.  Only relevant in 
@code{@@multitable}
@var{\@@columnfractions} is a reference on an array 
containing the @code{@@columnfraction} arguments, if any, 
@var{\@@prototype_row} is a reference on an array containing the row prototypes
given on the @code{@@multitable} line, if any,
@var{\@@prototype_lengths} array contains the lengths of the row prototypes
formatted and
@var{$column_number} is the maximal number of columns.
@end deftypefn

If you still want to use @code{%format_map} but differently from 
the default, it is possible to redefine the following function reference:

@deftypefn {Function Reference} $whole_table_list format $command $format $text
@var{$command} is the @@-command, @var{$format} is the entry associated with
@var{$command} in @code{%format_map}.  @var{$text} is the formatted items.
@end deftypefn


@node Definition formatting
@subsection Interpretation and formatting of the definition formatting

The formatting of definition commands is controlled by a main hash,
3 strings and another hash, and and five
functions.  The main hash describes how the text on the definition line is 
interpreted, the functions control the formatting of the definition line
and the definition function text.

@menu
* Definition line interpretation::
* Definition command formatting::
@end menu


@node Definition line interpretation
@subsubsection Customizing the interpretation of a definition line

@vindex %def_map
The keys of the hash @code{%def_map} are definition command names.
There are two types of entries:

@itemize

@item If the command is a shortcut for 
another definition command the value is a text and the definition 
command is replaced by the text.

For example if we have:
@example
$def_map@{'deftruc'@} = '@@defvr @{A truc@}';
@end example

and a line like
@example 
@@deftruc var
@end example

the line will be transformed in
@example
@@defvr @{A truc@} var
@end example

@item
If the command is not a shortcut, it is associated with an array
reference.  The first element is @samp{f}, @samp{v} or @samp{t} corresponding
with the index type (@samp{f} for function, @samp{v} for variable,
@samp{t} for type).

The remaining of the array describes how to interpret the text following
the definition command on the definition command line. 
The entry item specify what corresponds
with the next bracketed item or word.  Currently the possibilities are
@samp{category}, @samp{name}, @samp{type}, @samp{class}, @samp{arg} 
and @samp{argtype}.  @samp{arg} means that the arguments are not mixed 
with type definitions, with @samp{argtype} types are mixed with 
definitions. When there is no @samp{arg} nor @samp{argtype} it is 
the same than @samp{argtype}.

For example if we have
@example
def_map@{'defvr'@} = [ 'v', 'category', 'name' ];
@end example

The first bracketed item following @code{@@defvr} is considered
to be the category and the next one is the name.  The index associated
with the definition line is the variables index.
@end itemize

Some characters are special with regard with definition parsing, they
are delimiters, the can have a role in definition argument determination, 
and also hae a special meaning in arguments parsing. 
This is not very well documented in the Texinfo manual,
so it is subject to change.  Strings allow to determine the delimiters:

@vtable @code
@item $def_argument_separator_delimiters
Characters that separate arguments, currently @code{()[],}.
@item $def_always_delimiters
Character that are always delimiters, if they appear in a type or a 
parameter,
@code{()[]}.
@item $def_in_type_delimiters
Character that are considered as delimiters only if in a type. In
a parameter they are part of the parameter.
@end vtable


@node Definition command formatting
@subsubsection Customization of the definition formatting

Five functions are used when formatting a definition command:

@table @strong
@item category name
@deftypefn {Function Reference} $category definition_category $category $class $style $command
This function precise a category name associating a class 
@var{$class} (if given) with @var{$category}.  The @var{$style} of the
definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t}, 
for type.  The @var{$command} is the definition @@-command.
@end deftypefn

@deftypefn {Function Reference} $entry definition_index_entry $name $class $style $command
This function precise a name associating a class 
@var{$class} (if given) with @var{$name}.  This is used to do an index
entry associated with th edefinition command.  The @var{$style} of the
definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t}, 
for type.  The @var{$command} is the definition @@-command.
@end deftypefn

@item formatting of the definition line
@deftypefn {Function Reference} $line def_line $class_category_class $name $type $arguments $index_label \@@arguments_array \@@arguments_type_array \@@unformatted_arguments_array $command $class_name $category $class $style $original_command
This function formats the definition line.  @var{$class_category} is the 
category
formatted with @code{$definition_category}, @var{$name}, @var{$type} and 
@var{arguments} are the element of the definition line.  @var{$index_label} is
the text inserted at the place where an index entry appears. 
@xref{Index entry place formatting}.
@var{\@@arguments_array} is an array holding the definition arguments, 
formatted. @var{\@@arguments_type_array} holds the type of the definition
arguments, like @samp{name}, @samp{type} and similar arguments, 
@samp{paramtype}.
@samp{delimiter} and  @samp{param}.  @var{\@@unformatted_arguments_array} 
holds the arguments without @@-command substitution. @var{$command} is the
definition command, after substitution. 
@var{$class_name} is the class applied on name, formatted
as specified in @code{definition_index_entry}.  @var{$category} and 
@var{$class} are the corresponding arguments.  @var{$style} corresponds 
with the index style, as explained above.  @var{$original_command} is the 
unmodified definition @@-command.
@end deftypefn

@item definition text
@deftypefn {Function Reference} $definition_text def_item $text $only_inter_item_commands $command
This function formats the definition text, @var{$text}.
@var{$only_inter_item_commands} is true if there are only @@-commands 
that are not considered as the definition argument in the definition
text, like index entries.
@var{$command} is the definition @@-command.
@end deftypefn

@item the whole definition
@deftypefn {Function Reference} $definition def $text $command
This function formats the whole definition.  The definition line and text 
formatted by the above functions are in @var{$text}.
@var{$command} is the definition @@-command.
@end deftypefn

@end table

@node Menus indices and floats formatting
@section Menus, indices and floats formatting

@menu
* Menu formatting::
* Indices formatting::
* Floats and lists of floats formatting::
@end menu

@node Menu formatting
@subsection Menu formatting

There are two possibilities for menu formatting:

@itemize @bullet
@item format the whole menu in a preformatted environment, like 
in @ref{Preformatted block command formatting};
@item format the menu in table with more specialized formatting for each
part of the menu; 
@end itemize

The simple formatting in a preformatted is used if 
the configuration variable @code{SIMPLE_MENU} is true, 
otherwise the format with tables is used (this is the default).

In HTML, if the configuration variable @code{USE_ACCESSKEY} is set, 
the @code{accesskey} attribute is used in anchors.  In that case the 
@code{%BUTTONS_ACCESSKEY} hash is used for the access key.

In @command{texi2any}, a menu is considered to be composed of 2 parts, the
@dfn{menu entries} and the @dfn{menu comments} (@pxref{Writing a Menu}).
Menu entries are further 
divided in an @dfn{entry link} and optionnaly an @dfn{entry description}.
The entry link consists in a node name and an optional menu entry
name (@pxref{Menu Parts}).

@menu
* Menu components formatting::  
* Simple menu formatting::      formatting of a whole menu in a simple 
                                preformatted environement
* Table menu formatting::       formatting of a whole menu in a
                                table environment
@end menu


@node Menu components formatting
@subsubsection The formatting of the different menu components

If in a preformatted context (and @code{SIMPLE_MENU} isn't set), the 
menu link and description are put in the same preformatted environment.
This can be avoided with the configuration variable 
@code{SEPARATE_DESCRIPTION}.

Two function references are associated with the formatting of the 
different parts of a menu:
@deftypefn {Function Reference} $link menu_link $section \%state $href $node $name $ending $has_name \@@command_stack $preformatted $node_normalized_formatted
@var{$section} is the section name corresponding with the link, @var{$href}
is the link hypertextual reference. @var{$href} may be absent.  
@var{\%state} holds informations about the current context. 
@var{$node} is the node name, @var{$name} is the
name of the node.  @var{$ending} is the text ending the link entry, 
in general @samp{::} followed by some spaces.
@var{$has_name} is true if the entry has an explicit name, otherwise
@var{$name} has been constructed using the formatted node name.
@var{\@@command_stack} is an array containing the commands enclosing
the menu link.  It is used in the default case to detect if the 
menu link is right in the @command{@@menu} or not, since if it is not 
right below the menu the formatting is simpler.
@var{$preformatted} is true if in preformatted context.
@xref{Init File Expansion Contexts}. 
@var{$node_normalized_formatted} is the node with spaces normalized
and formatted.
@end deftypefn

This command is not called if @code{SIMPLE_MENU} is set.

@deftypefn {Function Reference} $description menu_description $description_text \%state $element_text
@var{$description_text} is the text of the menu description. 
The formatted link is also here if in preformatted context and 
@code{SEPARATE_DESCRIPTION} is not set.
@var{\%state}
should be used similarly than for the menu link.  @var{$element_text}
is the heading of the element associated with the node.
@var{$command_stack} and @var{$preformatted} are the same than for the
menu link.
@end deftypefn

The @dfn{menu comment} part is formatted like a normal command, 
called @code{menu_comment}.  It is only used if not in preformatted 
environment.
The default is to have it be formatted
like a @ref{Preformatted block command formatting}, with
@example
$complex_format_map@{'menu_comment'@} =
@{
   'begin' => "<tr><th colspan=\"3\" align=\"left\" valign=\"top\">",
   'end' => "</th></tr>", 'class' => 'menu-comment',
@}
@end example


@node Simple menu formatting
@subsubsection  Simple menu formatting in a preformatted environment

If the menu is to be formatted in a single preformatted environment,
an entry for @samp{menu} and @samp{detailmenu} 
should be added to the @code{%complex_format_map}
hash (@pxref{Preformatted block command formatting}).
In the default case, if the user didn't add an entry himself, a very simple 
entry is used, with:

@example
$complex_format_map->@{'menu'@} = @{ 'begin' => '' , 'end' => '',
    'class' => 'menu-preformatted' @};
@end example


@node Table menu formatting
@subsubsection The formatting of the menu in a table

In the default case, the name of the section corresponding with the 
node is used instead of the node name.  If the configuration 
variable @code{NODE_NAME_IN_MENU} is 
true, however, node names are used.  If the configuration variable 
@code{AVOID_MENU_REDUNDANCY}
is true and menu entry equal menu description the description is not printed.
This is the default.  Likewise, if node or section name equal entry name, 
do not print entry name.

@vindex $MENU_SYMBOL
@vindex $UNNUMBERED_SYMBOL_IN_MENU
A symbol, @code{$MENU_SYMBOL} is put at the beginning of menu entries
when the node name is used. The default is @samp{&bull;} for HTML, @samp{*}
for text formats.
If @code{$UNNUMBERED_SYMBOL_IN_MENU} is true it is 
also put at the beginning of unnumbered section names (in HTML).  This is not
done by default.

@vindex $MENU_PRE_STYLE
@vindex $MENU_PRE_COMPLEX_FORMAT
The menu comments are considered to be preformatted text.  The style 
associated with this preformatted text is determined by 
@code{$MENU_PRE_STYLE}. Default is @samp{font-family: serif}.
The entry similar with an entry in @code{%complex_format_map} 
(@pxref{Preformatted block command formatting}) used when the menu 
appears in a preformatted
enviroment is in
@code{$MENU_PRE_COMPLEX_FORMAT}, and, in the default case is:
@example
$MENU_PRE_COMPLEX_FORMAT = @{
              'pre_style' => $MENU_PRE_STYLE, 
              'class' => 'menu-preformatted'
   @};
@end example

The CSS class associated with menu comments is @code{menu-comments}.

The following function reference controls the formatting of a wole menu
or a detailmenu in that case:

@deftypefn {Function Reference} $menu menu_command $command $menu_components_text
@var{$command} is the menu command, currently @samp{menu}, @samp{detailmenu}
or @samp{direntry}.
@var{$menu_components_text} is the formatted menu components text, obtained
as explained above.
@end deftypefn


@node Indices formatting
@subsection Indices formatting

Two different things needs to be handled for indices formatting, the place
where the index term appears, the index entry, and the index list itself.
The indexing commands like @code{@@cindex} determines where index entries
appear, and the index list is printed with a @code{@@printindex} command. 

@menu
* Index entry place formatting::   Index entries in the main document are 
                                   targets for hypertext references
* Index list formatting::          Customizing the formatting of the index list
@end menu


@node Index entry place formatting
@subsubsection Formatting of index entries

Index entry places in the main text may be the target for
references.  Their formatting
is controlled by the function associated with the following function 
reference:

@deftypefn {Function Reference} $target index_entry_label $identifier $preformatted $entry $index_name $index_command $texi_entry $formatted_entry $in_region_not_in_output \%index_entry
@var{$identifier} should be used to create
a target for links (typically associated with a name or id 
attribute in HTML).
@var{$preformatted} is true if the index entry appeared in preformatted text.
@var{$entry} is the index entry with all the @@-commands removed.
@var{$index_name} is the index name, @var{$command} is the index command which
may be a index command like @code{@@cindex}, but also a definition or 
a table.  @var{$texi_entry} is the index entry with @@-commands, and 
@var{$formatted_entry} the entry formatted.
@var{$in_region_not_in_output} is set if the index entry appears in a region
formatting (for example @code{@@titlepage}) and not in the
output document.
@var{\%index_entry} is a reference on a hash holding informations about
the index entry.
@end deftypefn

Regular index entries are (like @code{@@cindex}) are 
formatted using the following function reference:
@deftypefn {Function Reference} $index_entry index_entry_command $command $index_name $label $entry_texi $entry_formatted
@var{$command}, @var{$index_name}, @var{$entry_texi} and @var{$entry_formatted}
are the same as above, and @var{$label} is what could be used as a label,
formatted using the function above. 
@end deftypefn


@node Index list formatting
@subsubsection Customizing the formatting of index lists

There is an elaborate default index formatting, with
index summary by letter linking to index entries grouped by letters too,
with the possibility of index pages split accross files. This system may be 
completly bypassed by redefining the function reference that is called when
@code{@@printindex} is encountered:

@deftypefn {Function Reference} $index_text printindex $index_name \%printindex
@var{$index_name} is the index name appearing on the 
@code{@@printindex} line. 
@var{\%printindex} is a reference on a hash holding informations
on the index.
The index formatted should be returned by this function reference.
@end deftypefn

If the default index formatting is used, there are still possibilities
to customize part of the formatting.
The index entries are sorted alphabetically.  A whole index list is 
considered to be composed of letter entries.  A letter entry is composed
by all the index entries beginning with that letter.  A letter may
be a non alphabetical character, but we call it letter here.

An index summary appears at the beginning and at the end of an index list,
and should be used to jump directly to a letter entry.  Indices lists
may be split across pages, thus the different letters may appear on different
files.  The number of index entries appearing on each page is determined
by a configuration variable @code{SPLIT_INDEX}, if set. The default is not 
to split indices.

The formatting of all these elements is controlled by the following
function references:

@table @emph
@item formatting of a letter in a summary
@deftypefn {Function Reference} {($result_letter, $identifier, $is_symbol)} summary_letter $letter $file $identifier $index_element_id $number $index_element $index_name
This function is used to format a letter appearing in a summary, refering
to a letter entry in the index list.
@var{$letter} is the letter.  @var{$file} is the file name where the letter
entry appears.  More precisely, it is empty when the letter entry is on the 
same page than the summary, it contains the file name when the index page
is split accross page.  @var{$identifier} is an identifier for the target 
letter entry.  @var{$index_element_id} is the identifier associated with the
element holding the letter.  @var{$number} and @var{$index_element} are 
not specified.  @var{$index_name} is the name of the index.
The function returns the resulting letter @var{$result_letter}, an
identifier for the letter @var{$identifier}, to be used in anchors, for example
and @code{$is_symbol} should be true if the letter is not a regular letter
but a symbol.
@end deftypefn

@item formatting of a summary
@deftypefn {Function Reference} $summary index_summary \@@alphabetical_letters \@@nonalphabetical_letters
@var{\@@alphabetical_letters} and @var{\@@nonalphabetical_letters} contain the
formatted summary letters, formatted with the above function.
@end deftypefn

@item formatting of an index entry
@deftypefn {Function Reference} $entry index_entry $entry_href $entry_text $element_href $element_heading $entry_file $element_file $entry_target $entry_element_target $in_region_not_in_output \%index_entry
@var{$entry_href} is a reference to the place where the index entry 
appeared, @var{$entry_text} is the corresponding text.  @var{$element_href}
is a reference to the beginning of the element containing 
the index entry, @var{$element_heading} is the heading of the element.
@var{$entry_file} is the file where the index entry appear, while 
@var{$element_file} is the file of the element.  @var{$entry_target} is the
target of the index entry, @var{$entry_element_target} is the
element target.
@var{$in_region_not_in_output} is set if the index entry appears in a region
formatting (for example @code{@@titlepage}) and not in the
output document.
@var{\%index_entry} is a reference on a hash holding informations about
the index entry.
@end deftypefn

@item formatting of letter entry
@deftypefn {Function Reference} $letter_entry index_letter $letter $identifier $index_entries_text
This function formats a letter entry, consisting in all the index entries 
beginning with this letter.  @var{$letter} is the letter, @var{$identifier} 
should be used to create a target for links (typically links from summaries),
and @var{$index_entries_text} is the text of the index entries formatted as 
described above.
@end deftypefn

@item formatting of whole index
@deftypefn {Function Reference} $index print_index $index_text $index_name
@var{$index_text} is the text of all the index entries grouped by letter
appearing in that page formatted as above.  It is undef if there are
no entries or theindex name isn't known. @var{index_name} is the name of
the index, the argument of @code{@@printindex}.
@end deftypefn
@end table


@node Floats and lists of floats formatting
@subsection Floats and lists of floats

Floats appear in the @code{@@float} environment, optionaly with a style
and a label, and with optionnal @code{@@caption} and @code{@@shortcaption}. 
Their list appear after a @code{@@listoffloats}. 

A hash reference is associated with each float, it is available in some
formatting functions.  The keys are:
@table @code
@item caption_texi
@itemx shortcaption_texi
A reference on an array containing the caption or shortcaption lines,
with texi @@-commands.
@item style_texi
The style with texi @@-commands.
@item style_id
The unique identifier associated with the style.
@item style
The style formatted.
@item nr
The number with the same conventions than makeinfo (use the chapter number a 
dot and then the number of the float of that style in the chapter, or an
absolute number if in unnumbered).
@item chapter_nr
The number of the chapter containing the float.
@item nr_in_chapter
The number of the float in the chapter.
@item absolut_nr
The number of the float in the document.
@item texi
The label with @@-commands.
@item name
The label formatted.
@item id
The unique identifier associated with the label.  Usefull to make an anchor
or a reference.
@item target
The target that can be used to refer to that float.
@item element
A reference on a structure representing the element the float appear in.
@end table

@menu
* Float formatting::                 Formatting of floats
* List of floats formatting::        Formatting the lists of floats 
@end menu

@node Float formatting
@subsubsection Formatting a float

First there is an occasion to construct a texinfo text for the caption, using
the caption texinfo lines and the informations in the float structure.
The returned lines will be formatted in the main program.  A function reference
is used here:

@deftypefn {Function Reference} {(\@@caption_lines_returned, \@@shortcaption_lines_returned)} caption_shortcaption \%float \@@caption_lines \@@shortcaption_lines
@var{\%float} is the structure defined above.  @var{\@@caption_lines} and 
@var{\@@shortcaption_lines} are references on arrays containing the 
texinfo lines for caption and short caption.  @var{\@@caption_lines_returned}
and @var{\@@shortcaption_lines_returned} are references on an array 
containing the texinfo lines for the caption and shortcaption.
@end deftypefn

Then the float is formatted with the following function reference:

@deftypefn {Function Reference} $text float $float_text \%float $caption_text $shortcaption_text
@var{$float_text} is the text appearing within the @code{@@float}, formatted.
@var{\%float} is still the structure defined above.  @var{$caption_text} and
@var{$shortcaption_text} are the caption and short caption build with the
above function and formatted.
@end deftypefn

It is also possible to do something when a caption or a shortcaption appear
with the following function reference:

@deftypefn {Function Reference} $text caption_shortcaption_command $command $formatted_caption \@@texi_lines \%float
@var{$command} is the @@-command, @samp{caption} or @samp{shortcaption}.
@var{$formatted_caption} is the caption text, formatted, while 
@var{\@@texi_lines} is a reference on an array containing the caption lines,
this time without any formatting.
@var{\%float} is still the structure defined above. 

In the default case this function reference returns an empty string.
@end deftypefn


@node List of floats formatting
@subsubsection Formatting lists of floats

A list of floats is introduced by @code{@@listoffloats}.  The argument of
@code{@@listoffloats} is the @dfn{style}.  First the style texinfo can be 
modified with the following function reference:

@deftypefn {Function Reference} $style_texi_returned listoffloats_style $style_texi
@var{$style_texi} is the @code{@@listoffloats} argument with texinfo 
@@-commands kept.  It is possible to make changes to the @var{$style_texi} and
return a modified string, still with @@-commands.  The modified string
is formatted in the main program.
@end deftypefn

After that, for each of the floats with that style, first there is a 
possibility to modify the float style and the float caption before they 
are formatted in the main program, with the following function references:

@deftypefn {Function Reference} $float_style_texi_returned listoffloats_float_style $style_texi \%float
@var{$style_texi} is the style, and @var{\%float} is the structure described 
above.  This function reference returns a style to be formatted in the
main program.
@end deftypefn

@deftypefn {Function Reference} (\@@caption_texi_returned, $caption_or_shortcaption) listoffloats_caption \%float
@var{\%float} is the structure described 
above.  This function reference returns a caption to be formatted in the
main program, @var{\@@caption_texi_returned}, and a string, 
@var{$caption_or_shortcaption} that is either @samp{caption} or 
@samp{shortcaption} that can be used by the main program if this information
is needed. 
@end deftypefn

Each entry is formatted by:

@deftypefn {Function Reference} $listoffloats_entry listoffloats_entry $style_texi \%float $float_style $caption $href
@var{$style_texi} is the style with @@-commands, @var{$float_style} is the
style returned by the above function and formatted. @var{$caption} is the
caption returned by the above function formatted. @var{\%float} is the 
structure corresponding with the float, and @var{$href} is an href pointing to
the float location.
@end deftypefn

Lastly, the whole @code{@@listoffloats} is formatted by:

@deftypefn {Function Reference} $listoffloats listoffloats $style_texi $style \@@listoffloats_entries
@var{$style_texi} is the style with @@-commands, @var{$style} is the
style returned by the above function and formatted. The array reference 
@var{\@@listoffloats_entries} holds the entries formatted by the above
function.
@end deftypefn

@node Handling special regions
@section Handling special regions

@vindex %region_formats_kept
Special regions @code{@@titlepage}, @code{@@documentdescription} and
@code{@@copying} are removed from the document before the last pass in the
default case. They can be kept if the value associated with the @@-command
in the @code{%region_formats_kept} hash is true.

The following function reference is called when starting the
formatting of a special region, if defined:

@deffn {Function Reference} begin_special_region $region_name \%state \@@region_lines
@var{$region_name} is the region name.
@var{\%state} holds informations about the context of the region formatting. 
@var{\@@region_lines} holds the region lines.
@end deffn

The following function reference is called when ending the formatting 
of the special region, if defined:

@deftypefn {Function Reference} $formatting_result end_special_region $region_name \%state $formatted_region
@var{$region_name} is the region name.
@var{\%state} holds informations about the context of the region formatting. 
@var{$formatted_region} is the result of the region formatting.
The function reference returns the result of the region formatting, after
possibly modifying it.
@end deftypefn

The @code{@@insertcopying} @@-command is formatted by 
@deftypefn {Function Reference} $insertcopying insertcopying $text $comment $simple_text
@var{$text} is the text appearing in @code{@@copying}, formatted.
@var{$comment} is the text with texi removed, should be very simple
text. 
@var{$simple_text} is the text formatted in string context
with minimal formatting but no elements.
@end deftypefn

The copying commane that is to be used at the beginning of output
files is formatted by
@deftypefn {Function Reference} $copying_comment_formatted copying_coment \@@copying_lines $text $comment $simple_text
@var{\@@copying_lines} is an array containing the Texinfo lines in @code{@@copying}.
@var{$text} is the text appearing in @code{@@copying}, formatted.
@var{$comment} is the text with texi removed, should be very simple
text.
@var{$simple_text} is the text formatted in string context
with minimal formatting but no elements.
@end deftypefn

@code{@@documentdescription} is handled by the following function
reference, that should set the configuration variable @code{documentdescription}:

@deffn {Function Reference} documentdescription \@@documentdescription_lines $text $comment $simple_text
@var{\@@documentdescription_lines} is an array containing the Texinfo lines in @code{@@documentdescription}.
@var{$text} is the text appearing in @code{@@documentdescription}, formatted.
@var{$comment} is the text with texi removed, should be very simple
text.
@var{$simple_text} is the text formatted in string context
with minimal formatting but no elements.
@end deffn

@xref{HTML Title Page Customization}, for specifics about the title
page handling.


@node Other and unknown commands
@section Customizing other commands, and unknown commands 

@cindex skipped command
@cindex unknown command

Many commands without braces are available in Texinfo, sometimes with
a specific syntax. For example we have @code{@@sp}, @code{@@noindent},
@code{@@documentlanguage}, @code{@@oddheading}, @code{@@headings},
@code{@@shortcontents}, @code{@@shorttitlepage} or @code{@@comment}. 
@command{texi2any} interprets
some of these commands and some functions or variables are used for
their formatting or to access their information.
In the default case, however, most of these constructs are ignored.

It is possible to change how the things following these commands
on the line are handled, what is considered to be an arg for those
commands and it is also possible to keep them instead of discarding
them such that it is possible to handle them specially, with the
same function than the one used for unknown commands.

@vindex %misc_command
Those special commands without braces are the key of a hash:
@code{%misc_command}.  The associated value is a reference on a
hash enabling to set the properties of these commands.  The
keys of this hash reference is the name of a property, the value
is the value of the property. For example here we have @code{line}
for the @code{arg} property for the @code{command} @@-command.

@example
$misc_command@{'command'@} = @{'arg' => 'line', 'skip' => 'space'@};
@end example

The properties and possible values are:

@table @code
@item skip
This property enables to set what is skipped after the command arguments.
Here are the possible values:
@table @code
@item line
The remaining of the line is skipped.
@item space 
Spaces are skipped but not newline.
@item whitespace 
Spaces are skipped
@item linewhitespace
Spaces are skipped if there are only spaces remaining on the line.
@item linespace
Spaces are skipped, but not newline if
there are only spaces remaining on the line
@end table

@item arg
If the associated value is @code{line} the line is considered to be the
argument.  If it is a number it is the number of args (separated by spaces).
@item keep
If true the args and the macro are kept, otherwise they are discarded.
The defaut is to have @code{keep} undef for all the commands.
If @code{keep} is true for @code{@@verbatiminclude} the default
action for this macro is not done.
@end table

These commands are processed by the @code{misc_command_line} function
reference.  This is somehow redundant with @ref{HTML Customization for
Title Commands} xx.

@deftypefn {Function Reference} {($command, $line, $result)} misc_command_line $command $line \@@args \@@stack \%state
@var{$command} is the @@-command name.  @var{$line} is what the main program
would leave on the line.  @var{\@@args} holds the @@-command arguments.
@var{\@@stack} is an opaque variable.
@var{\%state} holds informations about the current context. 
The result is the @@-command that should be considered in the
main program, the line that should be processed further and 
the result of the command formatting.
@end deftypefn


Commands which do not appear in the hashes 
@code{%simple_map}, @code{%simple_map_pre},
@code{%simple_map_texi}, @code{%line_command_map} or @code{%misc_command}, 
or that appear in
@code{%misc_command} but with @code{keep} true are processed by the 
following function reference:

@deftypefn {Function Reference} {($result_line, $result, $result_text, $message)} unknown $command $line $pass
@var{$command} is the @@-command, @var{$line} is the line following
the @var{$command}. @var{$pass} is the pass of texi2html
(@pxref{texi2any's Three Passes}).  @var{$result} is a boolean.  If it
is true then the other return values are taken into account otherwise
the default actions are used. In case @var{$result} is true,
@var{$result_line} is the new line to be processed further,
@var{$result_text} is the resulting formatted text and @var{$message},
if defined is a message outputted to the output with line number added
by @command{texi2any}.
@end deftypefn

Commands with braces not specified above 
nor in @code{%style_map}, @code{%style_map_pre} and
@code{%style_map_texi} are processed 
by the following function reference

@deftypefn {Function Reference} {($result, $result_text, $message)} unknown_style $command $text \%state $no_close $no_open
@var{$command} is the @@-command, @var{$text} is the text appearing within 
the braces (allready formatted).  
@var{\%state} holds informations about the current context. 
If @var{$text} is split in paragraphs each paragraph is passed through
the function, and @var{$no_close} is true if it is not the last paragraph,
while @var{$no_open} is true if it is not the first paragraph.
@var{$result} is a boolean.  If it is true then the other return
values are taken into account otherwise the default actions are
used.  In case @var{$result} is true, @var{$result_text} is the resulting
formatted text
and @var{$message}, if defined is a message outputted to the output
with line number added by @command{texi2any}.
@end deftypefn

@bye