[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texinfo.txi doc/version.texi
|
From: |
Patrice Dumas |
|
Subject: |
texinfo ChangeLog doc/texinfo.txi doc/version.texi |
|
Date: |
Fri, 23 Jul 2010 06:36:59 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Patrice Dumas <pertusus> 10/07/23 06:36:59
Modified files:
. : ChangeLog
doc : texinfo.txi version.texi
Log message:
* doc/texinfo.txi (texi2any output customization): add the
general informations about initialization files and the document
layout.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1066&r2=1.1067
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.261&r2=1.262
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/version.texi?cvsroot=texinfo&r1=1.83&r2=1.84
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1066
retrieving revision 1.1067
diff -u -b -r1.1066 -r1.1067
--- ChangeLog 22 Jul 2010 00:39:49 -0000 1.1066
+++ ChangeLog 23 Jul 2010 06:36:58 -0000 1.1067
@@ -1,3 +1,9 @@
+2010-07-23 Patrice Dumas <address@hidden>
+
+ * doc/texinfo.txi (texi2any output customization): add the
+ general informations about initialization files and the document
+ layout.
+
2010-07-21 Karl Berry <address@hidden>
* doc/texinfo.txi (Invoking texi2any) <--conf-dir>: reformat.
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.261
retrieving revision 1.262
diff -u -b -r1.261 -r1.262
--- doc/texinfo.txi 22 Jul 2010 00:39:49 -0000 1.261
+++ doc/texinfo.txi 23 Jul 2010 06:36:58 -0000 1.262
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.261 2010/07/22 00:39:49 karl Exp $
address@hidden $Id: texinfo.txi,v 1.262 2010/07/23 06:36:58 pertusus Exp $
@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -163,6 +163,7 @@
* Generic converter texi2any/makeinfo:: The all purpose converter.
* Creating and Installing Info Files:: Details on Info output.
* Generating HTML:: Details on HTML output.
+* texi2any output customization:: Fine tuning with initialization files.
* Command List:: All the Texinfo @@-commands.
* Tips:: Hints on how to write a Texinfo document.
@@ -650,6 +651,21 @@
* Configuration: HTML Xref Configuration. htmlxref.cnf.
* Preserving links: HTML Xref Link Preservation. MANUAL-noderename.cnf.
+texi2any output customization
+
+* Loading initialization files:: Initialization files search paths.
+* Initialization files basics:: General informations on initialization
+ files.
+* Elements:: The main division of output document.
+* Function prototypes:: Conventions used in that manual for
+ function reference prototypes display.
+* Initializing and finalizing:: Preparing and finalizing the output.
+* Special elements:: Customizing special elements text and
+ layout.
+* File and target names::
+* External index files::
+* Customizing CSS::
+
@@-Command List
* Command Syntax:: General syntax for varieties of @@-commands.
@@ -15910,11 +15926,11 @@
Beside those default formats, with @command{texi2any} some important
aspects of the result may be specified via command line options,
-and configuration files provide an even finer degree of control
+and initialization files provide an even finer degree of control
over the final output, allowing most every aspect of the final output not
-specified in the Texinfo input file to be specified. Configuration files are
+specified in the Texinfo input file to be specified. Initialization files are
written in @command{perl}, like the main program, and anything which may be
-specified on the command line may also be specified within a configuration
+specified on the command line may also be specified within a initialization
file.
@menu
@@ -16009,32 +16025,8 @@
@opindex address@hidden
Append @var{path} to the directory search list for finding
customization files that may be loaded with @option{--init-file} (see
-below). By default the following directories are searched, in this
-order (where @var{prog} is the name of the program invoked on the
-command line):
-
address@hidden
address@hidden The current directory @file{.};
-
address@hidden @file{$HOME/address@hidden, where @env{$HOME} is the user home
directory;
-
address@hidden @address@hidden/@var{prog}}, where @var{sysconfdir} is
-the system directory for host-specific configuration, determined at
-build time (@code{/usr/local/etc} by default);
-
address@hidden @address@hidden/@var{prog}} where @var{datadir} is the
-system directory for data files, determined at build time
-(@code{/usr/local/share} by default);
-
address@hidden the directory @file{.texinfo/init} in the current directory;
-
address@hidden @file{$HOME/.texinfo/init} where @env{$HOME} is the user home
directory;
-
address@hidden @address@hidden/texinfo/init} with @var{sysconfdir} as above;
-
address@hidden @address@hidden/texinfo/init} with @var{datadir} as above.
-
address@hidden enumerate
+below).
address@hidden initialization files}.
@var{path} can be a single directory, or a list of several directories
separated by the usual path separator character (@samp{:} on GNU and
@@ -16172,9 +16164,10 @@
@opindex address@hidden
Load @var{file} code to modify the behaviour and output of the generated
manual. @option{--conf-dir} may be used to add a directory to the list
-of directories where customization files are searched for. It is customary
-to use the @code{.init} extension with customization files, but it is
+of directories where initialization files are searched for. It is customary
+to use the @code{.init} extension with initialization files, but it is
not enforced by anything, and the @var{file} file name is taken literally.
address@hidden initialization files}.
@item address@hidden
@opindex address@hidden
@@ -16342,6 +16335,7 @@
Many aspects of the behaviour and output may be modified by modifying
configuration variables. This allows to go beyond what can be set in
the document by @@-commands and with command line switches.
address@hidden Configuration Variables}.
@item address@hidden
@itemx --no-split
@@ -16349,6 +16343,7 @@
@opindex --no-split
@cindex Splitting of output files
@cindex Output file splitting
address@hidden output}
When generating Info, @option{--no-split} suppress the splitting stage
of @code{makeinfo}. By default, large
@@ -16470,9 +16465,8 @@
@itemize @bullet
@item associated with @@-commands in the document,
for example @code{@@documentlanguage},
address@hidden associated with
-configuration variables that
-may also be set on the command-line, for example @code{SPLIT} which is
address@hidden associated with command-line options, for example the
configuration
+variable @code{SPLIT} is
associated with the @option{--split} command-line switch,
@item other
configuration variables, for example @code{NO_CSS} which may be set to 0
@@ -16533,7 +16527,7 @@
@code{INLINE_CONTENTS} is not set. Default is @file{<document name>_toc.html}.
@item SHOW_MENU
If set, the Texinfo menus are shown. It is set in all the formats, for
-exmaple it is true for HTML (except if @option{--no-headers} is used),
+example it is set for HTML (except if @option{--no-headers} is used),
Info and XML, but not for Docbook.
@item USE_NODES
Use nodes preferentially to decide where elements are separated.
@@ -16692,7 +16686,7 @@
For HTML.
generate @code{<link>} elements in HTML @code{<head>}.
@item OVERVIEW_LINK_TO_TOC
-If set the cross-refeerences in Overview link to the corresponding
+If set the cross-references in Overview link to the corresponding
Table of Contents entry.
@item AVOID_MENU_REDUNDANCY
if set and menu entry equals menu description, then do not print
@@ -16703,11 +16697,11 @@
If set, use node names in index entries, otherwise prefer section names.
@item USE_SETFILENAME
If set, use @code{@@setfilename} to set document name, otherwise base the
-document name only on th einput file name. @xref{setfilename}.
+document name only on the input file name. @xref{setfilename}.
@item USE_SETFILENAME_EXTENSION
Default for Info, not for other output.
If set use what @code{@@setfilename} gives for the output file name,
-including th eextension. You should not need to set this variable.
+including the extension. You should not need to set this variable.
@item COMPLEX_FORMAT_IN_TABLE
For HTML.
If set, use table for indentation of complex formats.
@@ -16728,7 +16722,7 @@
If set, use the node associated with a section for section target in
cross-references.
@item NEW_CROSSREF_STYLE
-If unset use an old cross-reference schenm. This is a backward compatibility
+If unset use an old cross-reference schema. This is a backward compatibility
setting, you should certainly never unset this variable.
@item PROGRAM_NAME_IN_FOOTER
For HTML.
@@ -18309,9 +18303,6 @@
software generating the cross-reference in the present manual can
control.
-Ultimately, we hope to allow for an external configuration file to
-control which manuals are available from where, and how.
-
@node HTML Xref Configuration
@subsection HTML Cross-reference Configuration: @file{htmlxref.cnf}
@@ -18469,6 +18460,1457 @@
indicated with a @samp{@@c} at the beginning of a line, optionally
preceded by whitespace.
address@hidden texi2any output customization
address@hidden Controlling the @command{texi2any} output
+
+
+
address@hidden
+* Loading initialization files:: Initialization files search paths.
+* Initialization files basics:: General informations on initialization
+ files.
+* Elements:: The main division of output document.
+* Function prototypes:: Conventions used in that manual for
+ function reference prototypes display.
+* Initializing and finalizing:: Preparing and finalizing the output.
+* Navigation panel customization::
+* Page layout customization::
+* Special elements:: Customizing special elements text and
+ layout.
+* File and target names::
+* External index files::
+* Customizing CSS::
address@hidden menu
+
address@hidden Loading initialization files
address@hidden Loading initialization files and search paths
+
+It is possible to load initialization files to modify almost every
+aspect of output formatting. The program loads initialization 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}):
+
address@hidden @file
address@hidden ./
+(the current directory)
+
address@hidden ~/address@hidden/
+(where @code{~} is the current user's home directory)
+
address@hidden @var{sysconfdir}/@var{prog}/
+(where @var{sysconfdir} is the system configuration directory
+specified at compile-time, e.g., @file{/usr/local/etc})
+
address@hidden @var{datadir}/@var{prog}/
+(likewise specified at compile time, e.g., @file{/usr/local/share})
address@hidden table
+
+All the files found are used, in that order.
+
+The most common way to load initialization files is to use the
address@hidden option to specify the file to be loaded. The
+initialization files are looked for
+in for in the same directories than @file{Config} files, and also
+in additional directories (the same that are used
+for @ref{HTML Xref Configuration} in the @file{init/} subdirectory).
+By default the following directories are searched, in this
+order (where @var{prog} is the name of the program invoked on the
+command line) the first file found is used:
+
address@hidden
address@hidden The current directory @file{.};
+
address@hidden @file{$HOME/address@hidden, where @env{$HOME} is the user home
directory;
+
address@hidden @address@hidden/@var{prog}}, where @var{sysconfdir} is
+the system directory for host-specific configuration, determined at
+build time (@code{/usr/local/etc} by default);
+
address@hidden @address@hidden/@var{prog}} where @var{datadir} is the
+system directory for data files, determined at build time
+(@code{/usr/local/share} by default);
+
address@hidden the directory @file{.texinfo/init} in the current directory;
+
address@hidden @file{$HOME/.texinfo/init} where @env{$HOME} is the user home
directory;
+
address@hidden @address@hidden/texinfo/init} with @var{sysconfdir} as above;
+
address@hidden @address@hidden/texinfo/init} with @var{datadir} as above.
+
address@hidden enumerate
+
+Additional directories may be appended with @option{--conf-dir}.
+
+
address@hidden Initialization files basics
address@hidden General informations on initialization files
+
+Initialization files are @command{perl} files, read as explained
+in @ref{Loading initialization files}.
+A good source of inspiration could be the initialization files provided
+in the Texinfo distribution. They all have @samp{.init} extension.
+The @file{texi2html.init} file is used to set all the defaults, and,
+although quite large is an interesting source of examples.
+Simpler initialization files are installed in the default case, they may
+also be interesting starting points.
+
+In initialization file three kind of variables appear.
address@hidden @asis
address@hidden configuration variables
+Those variables, described in @ref{makeinfo Configuration Variables}
+are set and accessed through specific functions in initialization files.
address@hidden scalar, arrays and hashes
+Normal perl variable. The order of loading of initialization
+files and of command-line options processing may be important when
+they are modified,
+later changes modifying former changes.
address@hidden references on functions
+This allows a dynamical redefinition of functions used to produce
+the output.
address@hidden table
+
+Initialization file are loaded from the main program by
+the mean of a @code{require}, while in the @code{Texi2HTML::Config}
+namespace. This means that the namespace of the main program and
+the namespace of initialization files are distinct, which ensures
+that no name clash should happen. The scalars,
+arrays and hashes are declared with
address@hidden vars}, such that it should be possible to use the
address@hidden strict} pragma in the initialization file code.
+
+To avoid messing with the variables in the @code{main} namespace
+all the global variables which could be of use in the init files
+are in the @code{Texi2HTML} namespace. Notice that the functions
+of the main program are still in the @code{main} namespace.
+
+Since the program can proceed more than one file on the
+command line, you should make sure that you initialize the variables
+that are used during a manual formatting. It is possible to call
+functions at different stages for that
+use (@pxref{Calling functions at different stages}).
+
address@hidden
+* Setting and getting configuration variable value::
+* Global informations:: Accessing global informations, like date,
+ address@hidden
+* Getting flag values::
+* Encodings:: Setting the encodings.
+* Redefining functions:: Function redefinition is achieved with
+ redefinition of references on functions.
+* Calling functions at different stages::
address@hidden menu
+
+
address@hidden Setting and getting configuration variable value
address@hidden Setting and getting configuration variable value
+
+To set the value of a configuration variable from an initialization file,
+you should use the function:
address@hidden set_from_init_file ($variable_name, $variable_value)
address@hidden is a string containing the name of the variable
+you want to set, and @var{$variable_value} is the value you want to set.
address@hidden may be @samp{undef}. For example
address@hidden
+set_from_init_file('documentlanguage', 'fr');
address@hidden example
+should override the @code{@@documentlanguage} from the document.
+It will be overriden by @option{--document-language} on the
+command-line.
+
+Another example,
address@hidden
+set_from_init_file('SPLIT', 'chapter');
address@hidden example
+should override the default splitting of the document. It will be
+overriden by the @option{--split} option on the command-line.
+
+And, as a last example,
address@hidden
+set_from_init_file('NO_CSS', 1);
address@hidden example
+wil override the default value for @code{NO_CSS}. It will be overriden by
address@hidden NO_CSS=1} on the command-line.
address@hidden defun
+
+To get the value of a variable, the function is @code{get_conf},
+in the @code{Texi2HTML::Config} namespace:
address@hidden get_conf ($variable_name)
address@hidden is the name of the variable you want to know the
+value.
address@hidden defun
+
+For example:
+
address@hidden
+if (get_conf('footnotestyle') eq 'separate') @{ .... @}
address@hidden example
+
+The list of configuration variables associated with @@-commands is
+in @ref{Configuration variables for @@-commands}, the list and mapping
+of configuration variables associated with command line options is at
address@hidden variables and options}.
+
address@hidden Global informations
address@hidden Accessing global informations
+
+The @code{%Texi2HTML::THISDOC} hash holds some global informations:
+
address@hidden
+FIXME
+'split_level' 'variable_levels' 'variables' 'toc_file' stoc_file
+%index_letters_array
+%index_entries_array
+%index_entries_region_array
+%index_entries
+%indices_numbers
+%indices
+input_file_name
+input_file_number
+input_directory
+css_import_lines
+css_rule_lines
+do_about
+titlefont_texi
+'file_base_name' 'FH' 'state' 'format_from_command_line' 'input_directory'
'destination_directory' 'file_base_name' %filename 'dircategory_texi'
'dircategory' 'settitle_texi' 'shorttitlepage_texi' 'title_texi'
settitle_line_nr shorttitlepage_line_nr title_line_nr @authors_texi
@authors_line_nr @subtitles_texi @subtitles_line_nr %merged_index @defindex
@defcodeindex
+command_stack top_texi fulltitle_texi simpletitle_texi
+program
+program_and_version
+program_homepage
+copying_comment
+inline_contents
+line_nr
+input_file_name
+%htmlxref
+%hyphenation
+
+author subtitle -> _texi
+
+'shorttitlepage', 'settitle', 'author',
+ 'titlefont', 'subtitle', 'title', 'fulltitle', 'simpletitle'
+-> $thing, $thing _no_texi, $thing _simple_format
address@hidden ignore
+
address@hidden @code
address@hidden fulltitle
+title set by @code{@@settitle}. If there is no @code{@@settitle} other
+possibilities are tried (@code{@@title}, @code{@@address@hidden).
address@hidden fulltitle_no_texi
+fulltitle without texi formatting
address@hidden fulltitle_texi
+fulltitle with texi commands
address@hidden title
+title set by @code{@@title}.
address@hidden title_no_texi
+title without texi formatting
address@hidden title_texi
+title with texi commands
address@hidden author
+Authors list set by @code{@@author}.
address@hidden authors
+A reference on an array containing each author set by @code{@@author}.
address@hidden copying_comment
+Text appearing in @code{@@copying} with all the texinfo commands removed,
+put in comments.
address@hidden program
+The name of the command generating the output.
address@hidden program_and_version
+The name and version of the command generating the output.
address@hidden program_homepage
+Homepage of the command generating the output..
address@hidden file_base_name
+base name of the texinfo manual file.
address@hidden filename
+This is a reference on 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
address@hidden @code
address@hidden doc
+the document file if not split, if split should be the top element file.
address@hidden top
+Top element file name.
address@hidden toc
+Table of contents element file name.
address@hidden stoc
+Overview (also called short table of contents) element file name.
address@hidden about
+About element file name.
address@hidden foot
+Footnotes element file name.
address@hidden frame
+Main frame file.
address@hidden toc_frame
+Table of contents frame file name.
address@hidden table
address@hidden input_file_name
+Name of the texinfo manual file given on the command line.
address@hidden destination_directory
+Destination directory for the resulting files.
address@hidden extension
+Extension for the output files.
address@hidden toc_file
+The file name of the table of contents, should always be valid, even
+when table of contents are output directly in the document.
address@hidden inline_contents
+A reference on a hash containing two key, one for each type of table
+of contents:
address@hidden @code
address@hidden contents
+The associated value is a
+reference on an array containg the line resulting from formatting
+the table of contents, including a heading and a reference.
address@hidden shortcontents
+The associated value is a
+reference on an array containg the line resulting from formatting
+the short table of contents, including a heading and a reference.
address@hidden table
address@hidden css_import_lines
+reference on an array containing the @code{@@import} lines of
address@hidden files. @xref{HTML CSS}.
address@hidden css_lines
+reference on an array containing the normal lines of
address@hidden files. @xref{HTML CSS}.
address@hidden table
+
+
address@hidden Getting flag values
address@hidden Getting the values of flags set by @code{@@set}
+
+Flags defined by @code{@@set} may be accessed through the
address@hidden::value} hash. The key is the flag name, the value is the
+flag value.
+
+
address@hidden Encodings
address@hidden Setting the encodings
+
+There are four relevant encodings variables, they are autodetected
+if not set:
address@hidden @code
address@hidden documentencoding
+This configuration variable may be set, if not defined, the encoding
+appearing in @code{@@documentencoding} will be used.
address@hidden IN_ENCODING
+The texinfo files encoding, may also be set.
+Otherwise, when @code{documentencoding}
+is set, @code{IN_ENCODING} is also set
+if the encoding is supported by perl.
address@hidden OUT_ENCODING
+The out files encoding. If not set, the value of
address@hidden
+or
address@hidden
+is used if one of these variables is set.
address@hidden ENCODING_NAME
+The encoding advertized in out files.
+If unset the value of this variable is based on the
+other ENCODING values, and if they are all undefined, the variable
address@hidden is used.
address@hidden table
+
+The values for the encoding related variables are set in the default
address@hidden function reference (@pxref{Output initialization}).
+
+In general the @code{documentencoding} and @code{IN_ENCODING} are
+set to the right values. @code{OUT_ENCODING} is also rightly set
+according to @code{ENCODING_NAME}.
+To force a given encoding for the output, the
address@hidden value may be set. The current default output encoding
+is UTF-8.
+
+
address@hidden Redefining functions
address@hidden Redefining functions in initialization files
+
+To redefine a function you must replace the corresponding funtion
+reference with a reference on your function.
+Thus you should write your function, give it a name you
+are certain it is unique in the @code{Texi2HTML::Config} namespace,
+and override the value of the function reference with your own
+function reference. When another function from the main program
+(or from another functions of a initialization file) calls the reference,
+your function will be used.
+
+For example the function
+reference corresponding with the function called when doing an
+anchor is called @code{$anchor}. Thus if you want to override the
+corresponding function
+you could write:
+
address@hidden
+# override the function reference
+$anchor = \&my_own_function;
+
+# the function reference now refers to
+sub my_own_function @{
+# process arguments and return an html anchor
address@hidden
address@hidden example
+
+
address@hidden Calling functions at different stages
address@hidden Calling functions at different stages
+
+Arbitrary user defined functions may be called between the
+different Texinfo parsing and outputting passes. 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
+some cleaning after the expansion pass.
+
+There are five places for user defined functions, associated with arrays.
+The function references in these arrays are called one after another.
+The arrays correspond with the different stages:
address@hidden @code
address@hidden @@command_handler_setup
+The function references in that array are called before anything is done,
+including collecting the output file names. The input file names directory
+are available.
address@hidden @@command_handler_init
+The function references in that array are called as soon as the file names are
+known. It may be at different moments, before processing anything, right after
+@@sefilename, or at the end of the first pass (after @@macro and @@include
+expansions).
+At that time the information available is essentially the file names.
address@hidden @@command_handler_names
+The function references in that array are called right after the collecting
+pass. At that time all the special @@-commands
+have been collected as explained above but no output has been produced,
+the element (node and section) names hasn't been processed and expanded.
address@hidden @@command_handler_process
+The function references in that array are called after the element names
+have been processed, but before the main output initialization.
address@hidden @@command_handler_output
+The function references in that array are called rigth before the
+main output processing, so that more informations are available,
+like the title.
address@hidden @@command_handler_finish
+he function references in that array are called after the end of the
+output generation.
address@hidden vtable
+
+Here is an example of these arrays use:
+
address@hidden
+push @@command_handler_init, \&Texi2HTML::LaTeX2HTML::init;
+push @@command_handler_process, \&Texi2HTML::LaTeX2HTML::latex2html;
+push @@command_handler_finish, \&Texi2HTML::LaTeX2HTML::finish;
address@hidden example
+
+
address@hidden Elements
address@hidden Elements and associated informations
+
address@hidden
+* The different elements::
+* Elements informations::
+* Elements lines::
address@hidden menu
+
address@hidden The different elements
address@hidden The different elements
+
+The main division of output document is the @dfn{element}. Their
+association with output files is determined by the split options.
address@hidden output}.
+The elements are:
+
address@hidden The association of nodes with pages is
address@hidden determined by the splitting of the document. @xref{Splitting
output}.
address@hidden @emph
address@hidden Normal elements
+These are normal sections and nodes. In general nodes are associated
+with the following sectioning command and a sectioning command is associated
+with the previous node and 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 value of
address@hidden and @code{USE_SECTIONS}. For example, if output
+is Info, the nodes are the elements, if output is Docbook, sectioning commands
+are the main element component, and if output is HTML both cases may happen.
address@hidden Paths}.
address@hidden Top element
+The top element is the higher element in the document structure.
+If there is a @code{@@top} section it is the element associated with
+that section. Otherwise it is the element associated with the
address@hidden@@node Top}. If there is no @code{@@node Top} the first element
+is the top element.
+
+The top element may be formatted differently from normal elements if there
+is a @code{@@top} section or the @code{@@node Top} is not associated
+with a sectioning command.
address@hidden Misc elements
+These elements are associated with different files if the document is split.
+And also if @code{MONOLITHIC} is not set.
+There are four misc elements:
address@hidden
address@hidden Table of contents
address@hidden Short table of contents, also called Overview
address@hidden Footnotes page
address@hidden About page
address@hidden enumerate
+
+The @emph{About page} shouldn't be present for documents consisting
+in only one sectioning element, or for documents unsplit and without
+navigation information. When generating HTML,
+the @emph{Footnote page} should only
+be present if the footnotes appear on a separated page,
+(@pxref{Footnote Styles}) however a footnote element is present if
+the document isn't split. The @emph{Table of contents} should only
+be formatted if @code{@@contents} is present in the document.
+Similarly the @emph{Overview} should only appear if @code{@@shortcontents}
+or @code{@@summarycontents} is present. Corresponding configuration variables,
address@hidden and @code{shortcontents} may be set to trigger the
+output of a @emph{Table of contents} or @emph{Overview}.
+The Table of contents and
+the Overview may also be directly included within the document, not
+as separate pages, in case @code{INLINECONTENTS} is set
+(@pxref{Contents and Overview text}).
+
+
+It is common not to have anything by normal elements, especially in
+case of non split output. In case of HTML output, special element may
+be present.
address@hidden table
+
+The main component of elements are sections if @code{USE_SECTIONS} is set,
+or @code{USE_NODES} is set to 0, and, conversely, are nodes if
address@hidden is set or @code{USE_SECTIONS} is 0. If those configuration
+variables are undefined, heuristics are used, influenced by the presence of
+nodes or sectionning elements in the document, if there are no nodes,
+sectioning elements are preferred and the reverse is true if there are no
+sectioning commands.
+
+When sectioning commands are the main components of elements,
+nodes not directly associated with a sectioning command are
+associated with the following sectioning command,
+and sectioning commands without nodes constitute an element.
+Conversely, when nodes are the main component of elements,
+sectioning commands not associated with nodes are associated with the
+previous node, and lone nodes are elements.
+
+
address@hidden Elements informations
address@hidden Elements informations
+
+
+The following items are associated with elements. Each of these
+is associated with 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 an element relative to the current
+element (for example the next element). The relative elements are
+found with respect with the document
+structure defined by the section structuring commands (@code{@@chapter},
address@hidden@@address@hidden) or by the nodes (in that case the node
+directions are specified on node line or in menu organization), as explained
+above (@pxref{Two Paths}).
+These items are called @dfn{element labels}. They may be associated with
+a button (@pxref{Button specifications}), and used in the formatting functions
+(@pxref{Elements informations}).
+
+Here is the list:
+
address@hidden @emph
address@hidden @samp{@ }
+An empty button
address@hidden Top
+Top element. The associated name is @code{TOP_HEADING} if that variable is
+defined. This variable is not set by default.
address@hidden Contents
+Table of contents
address@hidden About
+About (help) page
address@hidden Overview
+Overview, short table of contents
address@hidden First
+First element in reading order
address@hidden Last
+Last element in reading order
address@hidden 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.
address@hidden This
+The current element
address@hidden Back
+Preceding element in reading order
address@hidden FastBack
+Beginning of this chapter or previous chapter if the element is a chapter
address@hidden Prev
+Previous section on the same level
address@hidden NodePrev
+Previous node
address@hidden Forward
+Next element in reading order
address@hidden FastForward
+Next chapter
address@hidden Next
+Next section on the same level
address@hidden NodeNext
+Next node
address@hidden Following
+Next node in node reading order
address@hidden Up
+Up section
address@hidden NodeUp
+Up node
address@hidden FileNext
+Forward element first in the next page (or file)
address@hidden FilePrev
+Backward element first in the previous page (or file)
address@hidden table
+
+
+The element labels may also be accessed when formatting elements.
+Four hashes are available, with key the elements items, and values:
+
address@hidden @code
address@hidden %Texi2HTML::NAME
+The formatted element name
address@hidden %Texi2HTML::HREF
+The element hypertext reference
address@hidden %Texi2HTML::NODE
+The element node name
address@hidden %Texi2HTML::NO_TEXI
+The element name after removal of texi commands
address@hidden vtable
+
+For example @code{$Texi2HTML::address@hidden'Back'@}} is the name of the
+previous element in reading order.
+
+
address@hidden Elements lines
address@hidden Elements lines
+
+The following array references or arrays holds formatted lines:
+
address@hidden @code
address@hidden $Texi2HTML::THIS_SECTION
+Lines of the current element.
address@hidden $Texi2HTML::OVERVIEW
+Lines of short table of contents. @xref{Contents and Overview text}.
address@hidden $Texi2HTML::TOC_LINES
+Lines of table of contents. @xref{Contents and Overview text}.
address@hidden $Texi2HTML::TITLEPAGE
+The title page formatted. @xref{Title page}.
address@hidden vtable
+
+
address@hidden Function prototypes
address@hidden Conventions used for function prototypes
+
+As the 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} for a reference on an array and similarly
address@hidden for a reference on a hash.
+
+Thus, the prototype for the function associated with the function
+reference @samp{$formatting_function} will be:
+
address@hidden {Function Reference} $text formatting_function $arg1 \@@arg2
address@hidden takes as first argument @var{$arg2},
+as second argument a reference on an array @var{\@@arg2}
+and returns the formatted text @var{$text}.
address@hidden deftypefn
+
+To redefined the corresponding function, you should write:
+
address@hidden
+$formatting_function = \&my_formatting_function;
+
+sub my_formatting_function($ $)
address@hidden
+ my $arg1 = shift;
+ my $arg2 = shift;
+ # prepare $formatted_text
+ .....
+ return $formatted_text;
address@hidden
address@hidden example
+
address@hidden Initializing and finalizing
address@hidden Preparing and finalizing the output
+
address@hidden initialization}
address@hidden Preparing the output
+
+After the texinfo file has been parsed, some information is available
+which can be used to modify some variables and prepare the outputting.
+For example the document language, the document encoding,
+values set with @code{@@set} or @code{@@setfilename} and other similar
+@@-commands are not known before the texinfo parsing.
+
+The following function reference may be redefined to be called after
+texinfo processing and before document generation:
+
address@hidden {Function Reference} init_out
+This function perform the initialization of variables and any other
+task before document outputting.
address@hidden deffn
+
+In the default case, the hashes
address@hidden (@pxref{Button specifications}),
address@hidden (@pxref{About text}) are initialized.
+Indeed the initialization of these variables is dependent upon
+the document language selection. Similarly the encoding variables are set
+based on the information now available (@pxref{Encodings}).
+When generating HTML, aditionally, the @code{%NAVIGATION_TEXT}
+hash is initialized.
+
+To perform the default initializations and also add more code, you could
+do as in the following example (save the default function reference and call
+it in your own function):
+
address@hidden
+my $default_init_out = $init_out;
+$init_out = \&makeinfo_like_init_out;
+sub makeinfo_like_init_out()
address@hidden
+ &$default_init_out();
+ address@hidden'Following'@} = ' > ';
address@hidden
address@hidden example
+
address@hidden finalization}
address@hidden Finalizing the output
+
+If you want to do some cleaning after the document was generated (close
+files, write at the end of files and so on), the following function
+reference may be redefined:
+
address@hidden {Function Reference} finish_out
+This function is called after the document generation.
address@hidden deffn
+
+The default is to do nothing.
+
+These function references are mostly redundant with the handlers described
+in @ref{Calling functions at different stages}.
+
address@hidden Navigation panel customization
address@hidden Customization of the navigation panels buttons
+
+A lot of customization of the navigation panel may be achieved
+with variables redefinition, especially special arrays.
+The configuration variables @code{VERTICAL_HEAD_NAVIGATION}, @code{ICONS},
address@hidden, @code{HEADER_IN_TABLE}, @code{USE_ACCESSKEY} and
address@hidden
+may be used to change the the navigation panel formatting.
address@hidden Configuration Variables}.
+In case it isn't enough, it is also possible to redefine the function
+doing the navigation panel formatting.
+
address@hidden
+* Button specifications::
+* Panel formatting function::
address@hidden menu
+
+
address@hidden Button specifications
address@hidden Specifying the buttons formatting
+
+Several arrays and hashes enable a precise control on the buttons and
+their display.
+The following arrays determine the buttons present in navigation panels:
+
address@hidden @code
address@hidden @@SECTION_BUTTONS
+This array is used for the navigation panel buttons present at the begining
+of sectioning elements. If split at node or section they are also used
+at the page footer, and in the case of section navigation at the page header.
address@hidden @@SECTION_FOOTER_BUTTONS
address@hidden @@NODE_FOOTER_BUTTONS
+This array is used for the navigation panel buttons present at the footer
+of pages when split at node or at section.
+
+If @code{WORDS_IN_PAGE} is set and the output is split at nodes, these
+buttons are only present if there are more than @code{WORDS_IN_PAGE}
+words in the sectioning element text. This counting is very rough and include
+punctuation marks, html elements, numbers. The default is to include the
+buttons after 300 words.
address@hidden @@CHAPTER_BUTTONS
+This array is used for the buttons appearing at the page footer if split at
+chapter, and at the page header if split at chapter and there is no section
+navigation.
address@hidden @@MISC_BUTTONS
+These buttons appear at the beginning of special and sections
+and at the end of these section pages if the output is split.
address@hidden @@LINKS_BUTTONS
+These are used for @code{<link>} elements if they are output in the
+headers.
address@hidden vtable
+
+The array specify the buttons displayed in navigation panels,
+and how the button is displayed.
+Each element is associated with
+a button of the navigation panel from left to right.
+The signification of the array element value is the following:
+
address@hidden @emph
address@hidden reference on a function
+The function is called with argument a boolean true if the navigation
+panel should be vertical. Should return the formatted button text.
address@hidden reference on a scalar
+The scalar value is printed. For some possibly
+usefull scalars, @ref{Elements informations}.
address@hidden reference on an array
+In this case the first array element should be a reference on text and the
+second element an element label. In that case a link to the
+element associated with the element label with the scalar value
+text is generated.
+
+For example if the buttons array element is
address@hidden
+[ 'Next', \$Texi2HTML::address@hidden@} ]
address@hidden example
+
address@hidden %NAVIGATION_TEXT
+The button will be a link to the next section with text
address@hidden::address@hidden@}}.
address@hidden element label
+If icons are not used, the button is a link to the corresponding
+element which 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{ }, there is
+no @samp{[} and @samp{]}.
+The element of the @code{%NAVIGATION_TEXT} hash are defined
+dynamically, in the @code{init_out} function reference
+(@pxref{Output initialization}).
+
address@hidden %ACTIVE_ICONS
address@hidden %BUTTONS_NAME
address@hidden %PASSIVE_ICONS
address@hidden %NAVIGATION_TEXT
+If icons are used, the button is an image with file determined by
+the value associated with the element label in the @code{%ACTIVE_ICONS}
+hash if the the link really leads to an element, or in the
@code{%PASSIVE_ICONS}
+hash if there is no element to link to. Of course if there is a link to the
+element the icon links to that element. The button name and
+the button description are used in HTML attributes to have a textual
+description of the icon. The corresponding strings are in
address@hidden for the button name and @code{%NAVIGATION_TEXT}
+for the description.
address@hidden table
+
address@hidden %BUTTONS_ACCESSKEY
+If the configuration variable @code{USE_ACCESSKEY} is set,
+the @code{accesskey} attribute is used in navigation. In that case
+the @code{%BUTTONS_ACCESSKEY} hash is used for the access key.
+
address@hidden %BUTTONS_REL
+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.
+
+
address@hidden Panel formatting function
address@hidden Changing the navigation panel formatting
+
+If you are not satisfied with this scheme, it is possible to
+control exactly the formatting of navigation panels by redefining a function
+reference. The function controlling the display of navigation panel is
+associated with the following function reference:
+
address@hidden {Function Reference} $navigation_text print_navigation
\@@buttons $vertical
address@hidden@@buttons} is an array reference which should hold 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}.
address@hidden deftypefn
+
+
address@hidden Page layout customization
address@hidden Page and file layout customization
+
address@hidden
+* Customizing file header::
+* Customizing the section layout::
+* Customizing file footers::
address@hidden menu
+
address@hidden Customizing file header
address@hidden Customizing file header
+
+The default functions call the function associated with
address@hidden to format the navigation panel for the
+page header. Thus you can control parts of the formatting by
+redefining the function reference.
+
address@hidden {Function Reference} print_head_navigation $filehandle \@@buttons
address@hidden is the opened filehandle the function should write to.
address@hidden@@buttons} is an array reference which should hold the
specification of
+the buttons for the navigation panel.
address@hidden deffn
+
+If you want even more control, you can have full control over the page header
+formatting by redefining three function references. The function associated
+with @code{$print_page_head} is called for all the pages, and after that,
+the function associated with @code{$print_chapter_header} is called
+if the document is split at chapters, or the function associated with
address@hidden is called if the document is split at sections.
+
address@hidden {Function Reference} print_page_head $filehandle
address@hidden is the opened filehandle the function should write to.
+This function should print the page head, including the @code{<body>}
+element.
address@hidden deffn
+
address@hidden {Function Reference} print_chapter_header $filehandle
address@hidden is the opened filehandle the function should write to.
+This function is called if the document is split at chapters, after
address@hidden
address@hidden deffn
+
address@hidden {Function Reference} print_section_header $filehandle
address@hidden is the opened filehandle the function should write to.
+This function is called if the document is split at sections, after
address@hidden
address@hidden deffn
+
address@hidden $EXTRA_HEAD
address@hidden $AFTER_BODY_OPEN
+In HTML,
+it is possible to add lines to the text within the @code{<head>}
address@hidden elements, by defining the variable @code{$EXTRA_HEAD}.
+Similarly it is possible to add text just after the @code{<body>}
+element with the variable @code{$AFTER_BODY_OPEN}.
+These variables are empty by default.
+A date is output in header
+if @code{DATE_IN_HEADER} is set.
+Also, the description from @code{@@documentdescription} (or set as
+a configuration variable) is used in the
+header (@pxref{documentdescription}).
+
+The @code{<body>} element attributes may be set by defining the
+configuration variable @code{BODYTEXT}.
+In the default case, the encoding name @code{ENCODING_NAME} is used.
+If the variable is not defined,
+it is automatically determined
address@hidden
+
address@hidden @@LINKS_BUTTONS
address@hidden %BUTTONS_REL
address@hidden<link>} element are used in the header if @code{USE_LINKS}
+is set. @code{@@LINKS_BUTTONS} determines which links are used.
address@hidden determines the link type associated with the
address@hidden attribute.
+
address@hidden Customizing the section layout
address@hidden Customizing the section layout
+
+The functions associated with the following function references are used for
+the formatting of sections:
+
address@hidden {Function Reference} print_section $filehandle $first_in_page
$previous_is_top
address@hidden is the opened filehandle the function should write to.
address@hidden is true if this section is the first section in the page.
address@hidden is true if this section is the section following the
+Top section.
+This function should print the current section contents.
address@hidden deffn
+
address@hidden {Function Reference} end_section $filehandle
$last_element_or_before_top
address@hidden is the opened filehandle the function should write to.
address@hidden is true if this section precedes the top
+element or is the last one in page, or before the special elements.
address@hidden deffn
+
address@hidden Customizing file footers
address@hidden Customizing the file footers
+
+
+The default functions call the function associated with
address@hidden to format the navigation panel for the
+page footer. Thus you can control parts of the formatting by
+redefining the function reference.
+
address@hidden {Function Reference} print_foot_navigation $filehandle \@@buttons
address@hidden is the opened filehandle the function should write to.
address@hidden@@buttons} is an array reference which should hold the
specification of
+the buttons for the navigation panel.
address@hidden deffn
+
+If you want even more control, you can have more control over the page footer
+formatting by redefining three function references.
+The function associated with @code{$print_chapter_footer} is called
+if the document is split at chapters, or the function associated with
address@hidden is called if the document is split at sections.
+After that the function associated with @code{$print_page_foot} is called.
+
address@hidden {Function Reference} print_page_foot $filehandle
address@hidden is the opened filehandle the function should write to.
+This function should print the page foot, including the @code{</body>}
+element.
address@hidden deffn
+
address@hidden {Function Reference} print_chapter_footer $filehandle
address@hidden is the opened filehandle the function should write to.
+This function is called if the document is split at chapters, before
address@hidden
address@hidden deffn
+
address@hidden {Function Reference} print_section_footer $filehandle
address@hidden is the opened filehandle the function should write to.
+This function is called if the document is split at sections, before
address@hidden
address@hidden deffn
+
address@hidden $PRE_BODY_CLOSE
+In HTML, it is possible to add text just before the @code{</body>}
+element with the variable @code{$PRE_BODY_CLOSE}. Nothing is added
+by default. If @code{PROGRAM_NAME_IN_FOOTER} is set, the date and the
+program name that generated the output manual is output in the footer.
+
address@hidden Special elements
address@hidden Customizing the special elements pages and files
+
address@hidden
+* Special elements content::
+* Special elements layout::
address@hidden menu
+
address@hidden Special elements content
address@hidden Customizing the content of the special elements pages
+
+The label for the special elements, except for the Top element
+is formatted according to the function reference @code{$misc_element_label}:
+
address@hidden {Function Reference} $misc_element_label misc_element_label
$identifier $page_name
address@hidden is the identifier associated with the special element.
address@hidden is the special element name. It should return a label that
+can be used for references to the special element.
address@hidden deftypefn
+
address@hidden
+* Top element text::
+* Contents and Overview text::
+* Footnotes text::
+* About text::
+* Title page::
address@hidden menu
+
address@hidden Top element text
address@hidden Top element text formatting
+
+The top element formatting is controlled by three function which also
+controls the layout of the top element page or section. The associated
+function references are:
+
address@hidden {Function Reference} print_Top_header $filehandle $begin_page
address@hidden is the opened filehandle the function should write to.
address@hidden 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.
address@hidden deffn
+
address@hidden {Function Reference} print_Top $filehandle $has_top_heading
address@hidden is the opened filehandle the function should write to.
address@hidden is true if there is a @code{@@heading} command or
address@hidden@@titlefont} command appearing in the Top element text.
+This function should be used to format the Top element text and navigation
+panel.
address@hidden deffn
+
address@hidden {Function Reference} print_Top_footer $filehandle $end_page
address@hidden is the opened filehandle the function should write to.
address@hidden is true if the element is the last in a page.
+This function should end the Top element.
address@hidden deffn
+
address@hidden Contents and Overview text
address@hidden Table of contents and Short table of contents
+
+Two possibilities exist for the formatting of table of contents (and
+short table of contents). In the default case, the table of contents
+are in separate elements, at the end of the document if the document
+is unsplit or in separate files. This makes sense when
+menus are used for navigation. Another mode may be selected by
+setting @code{INLINE_CONTENTS}. In that case the table of contents
+are not output as separate elements but are instead output where the
+corresponding @@-command, for example @code{@@contents},
+is set. This behaviour is more consistent with @command{texi2dvi}.
+If @code{@@setcontentsaftertitlepage} appears in the document,
+and even if @code{INLINE_CONTENTS} is set, the table of contents are
+merged in the title (which isn't output in the default case, see
address@hidden page}).
+
+Several variables may be used to control the formatting of table of contents
+and short table of contents:
+
address@hidden @code
address@hidden $BEFORE_OVERVIEW
+The variable value is inserted before the short table of contents text.
address@hidden $AFTER_OVERVIEW
+The variable value is inserted after the short table of contents text.
address@hidden $BEFORE_TOC_LINES
+The variable value is inserted before the table of contents text.
address@hidden $AFTER_TOC_LINES
+The variable value is inserted after the table of contents text.
address@hidden $NO_BULLET_LIST_STYLE
+For HTML.
+This should contain a CSS style used for the list style when there
+is no bullet.
address@hidden $NO_BULLET_LIST_CLASS
+This should contain the class assocciated with the $NO_BULLET_LIST_STYLE
+css style.
address@hidden $NO_BULLET_LIST_ATTRIBUTE
+This should contain an attribute text used for the list element when there
+is no bullet. For example it is used in the tables of if they are
+formatted with a list.
address@hidden vtable
+
+More control on the table of contents and short table of contents formatting
+may be achieved by redefining a function with the following associated
+function reference:
+
address@hidden {Function Reference} toc_body \@@elements
address@hidden@@elements} is an array reference contining informations about
+all the elements of the document. Each of the entry of this array is an hash
+reference which entries correspond with different informations
+about the element. Interesting keys have the following meaning:
+
address@hidden @code
address@hidden top
+true if the element is the top element,
address@hidden index_page
+true if the element is an index page added because of index splitting,
address@hidden toc_level
+level of the element in the table of content. Highest level
+is 1 for the top element and for chapters, appendix and so on,
+2 for section, unnumberedsec and so on...
address@hidden tocid
+label used for reference linking to the element in table of
+contents,
address@hidden file
+the file containing the element, usefull to do href to that file
+in case the document is split,
address@hidden text
+text of the element, with section number,
address@hidden name
+text of the element, without section number.
address@hidden table
+
+This function doesn't return anything but should fill the array corresponding
+with the @code{$Texi2HTML::TOC_LINES} and @code{$Texi2HTML::OVERVIEW}
+references with the table of contents and short table of contents.
address@hidden lines}.
+
address@hidden deffn
+
+Another function reference is used to add a heading and a reference, to
+be used with @code{INLINE_CONTENTS} or merged in the title. Its output
+is not used when the table of contents are separate elements.
+
address@hidden {Function Reference} \@@inline_contents_lines inline_contents
$filehandle $command $element
+This function reference returns a reference on an array holding
+the lines containing the contents, heading and reference.
address@hidden is a reference on the currently opened file if
+the function is called because a @code{@@contents} or
address@hidden@@shortcontents} command was encountered, it is undef otherwise.
address@hidden is either @samp{contents} or @samp{shortcontents}.
address@hidden is a hash reference containing informations about the
+table of contents context. Relevant keys are:
address@hidden @code
address@hidden target
+The identifier associated with the table of contents, used for example
+to do references to the table of contents using href in @acronym{HTML}.
address@hidden id
+The identifier associated with the element, used to do labels. In
+general the same than the @code{target}, but not necessarily.
address@hidden file
+The file name containing the table of contents.
address@hidden table
+
address@hidden deftypefn
+
address@hidden Footnotes text
address@hidden Formatting of footnotes text
+
+The footnotes text is already formatting when @code{@@footnote} commands
+are expanded.
address@hidden FIXME readd when it is added
address@hidden @xref{Footnotes customization}.
+
address@hidden About text
address@hidden Formatting of about text
+
+The default about element contains an explaination of the buttons used
+in the document (@code{@@SECTION_BUTTONS}, @ref{Button specifications}) and
+an example locating the buttons targets in an example.
+The formatting of this text may be influenced by the following
+hashes and variables:
+
address@hidden @code
address@hidden $PRE_ABOUT
address@hidden $AFTER_ABOUT
+This variable may be a scalar or a function reference.
+If it is a scalar, the value is used.
+If this is a function reference it is expanded and the returned text is
+used. The text is added before or after the main about text.
address@hidden %BUTTONS_GOTO
+
+The keys of this hash are element labels (@pxref{Elements informations}).
+The value is the text associated with the element label in the about text.
+In the default case, the element of the hash are defined dynamically in
+that the @code{init_out} function reference (@pxref{Output initialization}).
+
+
address@hidden %BUTTONS_EXAMPLE
+
+The keys of this hash are element labels (@pxref{Elements informations}).
+The value is the text associated with the element label in the about
+example, typically a section number.
+
address@hidden table
+
+If this is not enough and you want to control exactly the formatting of
+the about text, you can redefine the function associated with the following
+function reference:
+
address@hidden {Function Reference} $about_text print_about
+This function should return the about text.
address@hidden deftypefn
+
address@hidden Title page
address@hidden Formatting of title page
+
address@hidden $Texi2HTML::TITLEPAGE
+The title page is first formatted using the text appearing in
+the @code{@@titlepage} section, and put in @code{$Texi2HTML::TITLEPAGE}
+(@pxref{Elements lines}). More formatting can be done using the following
+function reference:
+
address@hidden {Function Reference} titlepage
+This function should complete @code{$Texi2HTML::TITLEPAGE}.
address@hidden deffn
+
+In the default case, in this function the title is output if
+there is no titlepage, the table of contents and short
+table of contents are also added if they are to be output and
address@hidden@@setcontentsaftertitlepage}
+or @code{@@setshortcontentsaftertitlepage} appear in the document
+(@pxref{Contents and Overview text}).
+
+The resulting title page output is used in the document if
address@hidden and @code{SHOW_TITLE} are set.
+
address@hidden Special elements layout
address@hidden Customizing the layout of the special element pages
+
+The formatting of each of the special pages, or section in case
+the document is not split, is controlled by a function.
+The associated function reference is called accordingly:
+
address@hidden @code
address@hidden print_Top
address@hidden print_Top_header
address@hidden print_Top_footer
+Formatting of top element page or section. It is also used for the formatting
+of the top element text (@pxref{Top element text}).
address@hidden print_Toc
+Formatting of table of contents page or section.
address@hidden print_Overview
+Formatting of short table of contents page or section.
address@hidden print_About
+Formatting of about (help) page or section.
address@hidden print_Footnotes
+Formatting of footnotes section or page in case footnotes are on a
+separated page or the document is not split.
address@hidden ftable
+
+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 function call @code{$print_misc} which in turn calls
address@hidden for the headers and @code{$print_misc_footer}
+for the footers.
+
address@hidden File and target names
address@hidden Customizing the file and target names
+
address@hidden File names
+
+It is possible to specify the file names with more control than with the
+command line options (@option{--output}). The configuration variables
address@hidden, @code{TOP_FILE} and @code{TOC_FILE} may be used.
+The extension may also be overriden by the configuration variable
address@hidden
+value. The variable should be @code{undef} if no extension is
+to be added.
+
+Two function references enable
+further customization. One is especially usefull in case
address@hidden is true
+and it is used to customize the node file name.
+
address@hidden {Function Reference} $node_file node_file_name \%node
address@hidden is a hash reference with the following interesting keys (there
+are much more keys):
address@hidden @code
address@hidden texi
+The texinfo node name.
address@hidden with_section
+True if associated with a section.
address@hidden table
+The result is the node file name @var{$node_file}.
address@hidden deftypefn
+
+The other is used to
+customize the file names associated with each element, and the
+name of the file associated with the special elements.
address@hidden different elements}.
+
address@hidden {Function Reference} $file element_file_name \%element $type
$docu_name
address@hidden is undefined for the special elements (about, overview,
+table of contents, footnotes).
+Otherwise it is a hash reference with the following interesting keys (there
+are much more keys):
address@hidden @code
address@hidden texi
+The texinfo element name.
address@hidden number
+The number associated with a section.
address@hidden doc_nr
+A number incremented whenever a new file should begin, based on how the
+document is split (@pxref{Splitting output}).
address@hidden text
+The element text.
address@hidden name
+The element text without section number.
address@hidden table
address@hidden 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 the
+footnotes it is @samp{foot} and for about is @samp{about}. If
+frames are used with @code{FRAMES}, the function reference
+is also called for @samp{frame}, the frame file name, and
address@hidden the table of content frame file name.
address@hidden is the basename of the texinfo manual.
+The result is the element or special element file name.
address@hidden deftypefn
+
address@hidden target names
+
+Similarly target and id may be set. The @dfn{id} is placed where the
+item is located, the @dfn{target} is used to construct references to
+that item. In general they should be equal, but not always, for example
+in the default case, the target for a section is the node id.
+The following function reference, is
+for target items (nodes, anchors, floats):
+
address@hidden {Function Reference} {($target,$id)} node_target_name \%node,
$default_target, $default_id
address@hidden is the same as in the @code{node_file_name} function reference
+above.
address@hidden is the target already set (it is also
+in @code{$node->@{'target'@}}), and @var{$default_id} is similarly
+the id already set.
address@hidden deftypefn
+
+For element (@pxref{The different elements}), the function
+reference is:
+
address@hidden {Function Reference} {($target,$id)} element_target_name
\%element, $default_target, $default_id
+the @var{\%element} is the same than in @code{element_file_name}, and
address@hidden and @var{$default_id} are the target and id already set.
address@hidden deftypefn
+
+Placed items
+(floats, footnotes, index entries, anchors, contents,
+shortcontents and headings)
+file and target may also be set. In the default case, they should
+be rightly set, so be careful when changing them. The following
+function reference can be used:
+
address@hidden {Function Reference} {($target, $id, $file)}
placed_target_file_name \%placed_item, \%element, $default_target, $default_id,
$default_file, $context
address@hidden is a hash reference describing the placed item,
+in the same vein than above.
+the @var{\%element} is the same than in @code{element_file_name},
+corresponding with the element containing the placed item.
address@hidden, @var{default_id} and
address@hidden are the file, id and target already set.
address@hidden describes the context, it is empty in the normal cases,
+and can also be set to @samp{footnotes} if in footnotes, or to
address@hidden if the placed item is out of any element
+(typically in @code{@@titlepage}, @code{@@copying}).
address@hidden deftypefn
+
address@hidden %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}.
+
+
address@hidden External index files
address@hidden Generation of external files for index entries
+
address@hidden FIXME Here? of after Index list?
address@hidden Within the document, @code{@@printindex} commands are expanded
as explained
address@hidden in @ref{Index list}.
+In case you want to do something special with index
+entries, outside of the document, you should first set the configuration
+variable @code{IDX_SUMMARY} true. After that some function reference
+will be called for each non empty index. For each index there are 3
+function references, one called for initialization, one called for each
+index entry and the last one called for finalization.
+
address@hidden {Function Reference} index_summary_file_begin $index_name
$is_printed $manual_name
address@hidden is the two letters name for the index. This function
+is called for each index appearing in the document, before
address@hidden
address@hidden is true if there is a @code{@@printindex} for that index.
address@hidden is the manual basename.
address@hidden deffn
+
address@hidden {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. @var{index_name} is the
+name of the index. @var{$entry_text} is the entry in plain text,
address@hidden is the index entry formatted, @var{$texi_entry} is the
+entry with texinfo commands. @var{$entry_reference} is the reference placed
+at the index entry place, in the form @samp{file#id}.
address@hidden is the formatted header of the element containing
+the index entry. @var{entry_element_header} is the reference to the
+beginning of the element containing the index entry, in the form
address@hidden
address@hidden is true if there is a @code{@@printindex} for that index.
address@hidden is the manual basename.
address@hidden deffn
+
address@hidden {Function Reference} index_summary_file_end $index_name
$is_printed $manual_name
address@hidden is the two letters name for the index. This function
+is called for each index appearing in the document, after
address@hidden
address@hidden is true if there is a @code{@@printindex} for that index.
address@hidden is the manual basename.
address@hidden deffn
+
address@hidden Customizing CSS
address@hidden Customizing the CSS lines
+
address@hidden @acronym{CSS}
+
+The @code{NO_CSS} configuration option turns CSS support off.
+Instead of CSS lines output at the document beginning, they may be added
+to each of the HTML attributes, if @code{INLINE_CSS} is set.
+The configuration variable variable holds the CSS
+specification lines in case CSS is not inline.
address@hidden %css_map
+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 the way @code{CSS_LINES}
+are generated by redefining the following function reference:
+
address@hidden {Function Reference} css_lines \@@import_lines \@@rule_lines
+This function should be used to set the variable
address@hidden
address@hidden@@import_lines} are the @code{@@import} lines of the
+files specified with @option{--include-css},
+and @var{\@@rule_lines} are the css commands lines of these files.
address@hidden deffn
+
@node Command List
@appendix @@-Command List
@@ -20341,7 +21783,7 @@
(@url{http://www.gnu.org/software/rcs}) version control systems, which
expand it into a string such as:
@example
-$Id: texinfo.txi,v 1.261 2010/07/22 00:39:49 karl Exp $
+$Id: texinfo.txi,v 1.262 2010/07/23 06:36:58 pertusus Exp $
@end example
(This is useful in all sources that use version control, not just manuals.)
You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -20420,7 +21862,7 @@
@verbatim
\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.261 2010/07/22 00:39:49 karl Exp $
address@hidden $Id: texinfo.txi,v 1.262 2010/07/23 06:36:58 pertusus Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
Index: doc/version.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/version.texi,v
retrieving revision 1.83
retrieving revision 1.84
diff -u -b -r1.83 -r1.84
--- doc/version.texi 19 Jul 2010 23:48:18 -0000 1.83
+++ doc/version.texi 23 Jul 2010 06:36:58 -0000 1.84
@@ -1,4 +1,4 @@
address@hidden UPDATED 20 July 2010
address@hidden UPDATED 23 July 2010
@set UPDATED-MONTH July 2010
@set EDITION 4.13
@set VERSION 4.13