diff options
Diffstat (limited to 'Build/source/utils/texi2html/doc/texi2html.texi')
-rw-r--r-- | Build/source/utils/texi2html/doc/texi2html.texi | 3426 |
1 files changed, 3426 insertions, 0 deletions
diff --git a/Build/source/utils/texi2html/doc/texi2html.texi b/Build/source/utils/texi2html/doc/texi2html.texi new file mode 100644 index 00000000000..b4e2662badb --- /dev/null +++ b/Build/source/utils/texi2html/doc/texi2html.texi @@ -0,0 +1,3426 @@ +\input texinfo @c -*-texinfo-*- +@c This is the ``Texinfo to HTML Converter'' manual which +@c which is part of the ``texi2html'' distribution. +@setfilename texi2html.info + +@c @macro copyleftnotice +@copying +Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 + Free Software Foundation, Inc. + +@multitable @columnfractions .12 .88 +@item Portions of @command{texi2html} +@item @tab Copyright @copyright{} 1999, 2000 Lionel Cons@* +@item @tab Copyright @copyright{} 1999, 2000 Karl Berry@* +@item @tab Copyright @copyright{} 1999, 2000 Olaf Bachmann@* +@item @tab Copyright @copyright{} 2002, 2003 Patrice Dumas@* +@item @tab Copyright @copyright{} 2001, 2002, 2003 Derek Price@* +@item @tab Copyright @copyright{} many others.@* +@item @tab +@item @tab +@item Portions of this manual +@item @tab Copyright @copyright{} 1999, 2000 Karl Heinz Marbaise (manual)@* +@item @tab Copyright @copyright{} 2003 Patrice Dumas (manual)@* +@item @tab Copyright @copyright{} 2003 Derek Price (manual)@* +@end multitable + +Permission is granted to make and distribute verbatim +copies of this manual provided the copyright notice and +this permission notice are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and +print the results, provided the printed document carries +copying permission notice identical to this one except for +the removal of this paragraph (this paragraph not being +relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified +versions of this manual under the conditions for verbatim +copying, provided that the entire resulting derived work is +distributed under the terms of a permission notice +identical to this one. + +Permission is granted to copy and distribute translations +of this manual into another language, under the above +conditions for modified versions, except that this +permission notice may be stated in a translation approved +by the Free Software Foundation. +@end copying +@c @end macro + +@c -------------------------------------------------------- +@c This file is part of the Texi2HTML distribution. +@c +@c Texi2HTML is free software; you can redistribute it +@c and/or modify it under the terms of the GNU General Public +@c License as published by the Free Software Foundation; +@c either version 2 of the License, or (at your option) any +@c later version. +@c +@c Texi2HTML is distributed in the hope that it will be +@c useful, but WITHOUT ANY WARRANTY; without even the implied +@c warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +@c PURPOSE. See the GNU General Public License for more +@c details. +@c +@c You should have received a copy of the GNU General +@c Public License along with this program; if not, write to +@c the Free Software Foundation, Inc., 59 Temple Place, Suite +@c 330, Boston, MA 02111-1307 USA +@c +@c Author: +@c Karl Heinz Marbaise <khmarbaise@gmx.de> +@c Patrice Dumas +@c Derek Price +@c -------------------------------------------------------- + +@c -------------------------------------------------------- +@c Get the version of the script and the last update time +@c of this manual. +@c +@c version.texi is automatically generated through +@c configure/autoconf. +@include version.texi +@c -------------------------------------------------------- + +@c -------------------------------------------------------- +@c Define an index for command line options +@defindex op + +@c Define some macros which affect markup and add to the +@c index simultaneously. +@macro longopt {arg} +@opindex \arg\ +@option{--\arg\} +@end macro + +@macro shortopt {arg} +@opindex \arg\ +@option{-\arg\} +@end macro + +@macro variable {arg} +@vindex \arg\ +@code{\arg\} +@end macro +@c -------------------------------------------------------- + +@settitle Texi2HTML -- Texinfo to HTML v@value{VERSION} +@setchapternewpage odd +@footnotestyle separate +@ifset shorttitlepage-enabled +@shorttitlepage Texi2HTML -- Texinfo to HTML v@value{VERSION} +@end ifset + +@c -------------------------------------------------------- +@c support old style Info Dir entries. +@ifset OLDSTYLE-INFO-DIR +@ifinfo +@format +START-INFO-DIR-ENTRY +* Texi2HTML: (texi2html). Texinfo 2 HTML Converter (texi2html). +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ifset +@c -------------------------------------------------------- +@c Informations for install-info. +@c I think the conversion script should be found +@c where the documentation system lives. +@c What do you think? +@dircategory Texinfo documentation system +@direntry +* Texi2HTML: (texi2html). Texinfo to HTML Converter. +@end direntry +@c -------------------------------------------------------- + +@ifnottex +@ifnothtml +This file, last updated @value{UPDATED}, documents the @command{texi2html} +script which converts @uref{http://www.texinfo.org,Texinfo} into +@uref{http://w3c.org,HTML}. This edition is for @command{texi2html} version +@value{VERSION}. +@end ifnothtml + +@c @copyleftnotice +@insertcopying +@end ifnottex +@c -------------------------------------------------------- +@titlepage +@title Texi2HTML -- Texinfo to HTML v@value{VERSION} +@subtitle Last Update: @value{UPDATED} +@subtitle for Version @value{VERSION} of the @command{texi2html} script. +@author Lionel Cons +@author Karl Berry +@author Olaf Bachmann +@author Patrice Dumas +@author Derek Price +@author and many others. +@author Karl Heinz Marbaise (manual) +@author Patrice Dumas (manual) +@author Derek Price (manual) +@page +@vskip 0pt plus 1filll +@c @copyleftnotice +@insertcopying +@end titlepage + +@comment ======================================================== +@comment The real text starts here. +@comment ======================================================== + +@summarycontents +@contents + +@ifnottex +@c ======================================================== +@node Top +@top Texi2HTML + +@cindex bug report + +This manual, last updated @value{UPDATED}, describes version @value{VERSION} +of the @command{texi2html} Perl script which converts +@c The following construct allows me to get +@c real URL link in HTML and working refs in +@c info. +@c +@c pertusus: support for html cross manual now +@c exists in texi2html, but it implies having Texinfo's +@c HTML manual at the right place, which isn't usually the case. +@c The resulting ref is also less pretty in info. +@ifnotinfo +@uref{http://www.texinfo.org,Texinfo} into @uref{http://w3c.org,HTML}. +@end ifnotinfo +@ifinfo +Texinfo (@pxref{Top,,Texinfo,Texinfo}) into @acronym{HTML}. +@end ifinfo + +Please send bug reports concerning this manual to the Texi2HTML user +discussion list @email{user@@texi2html.cvshome.org}. Please state the exact +version of the manual which contains the bug, as given above. + +@ifinfo +@c @copyleftnotice +@insertcopying +@end ifinfo + +@example +@strong{This manual is currently under construction and of course incomplete. ;-)} +@end example + +@menu +@c * MenuName:NodeName. Description +* Overview:: +* Obtaining texi2html:: + Obtaining a copy of the @command{texi2html} + source code distribution +* Installation:: Installing @command{texi2html} +* Invoking texi2html:: Description of the command line options +* Initialization files:: What kind of variables and subroutines appear + in init files and how they are called +* Changing the page layout:: Fine tuning of the page layout +* Customizing HTML:: Fine tuning of the @acronym{HTML} elements + associated with the texinfo constructs +* Internationalization:: Help translating ! +* Indexop:: Command Line Option Index +* Indexvr:: Variable Index +* Indexcp:: Concept Index + +@end menu +@end ifnottex +@c ======================================================== +@node Overview +@chapter Overview + +@cindex Texinfo +@cindex examples of manuals + +@uref{http://www.texinfo.org,Texinfo} is the official +documentation format of the @uref{http://www.gnu.org,GNU} +project. It uses a single source file to produce both +online information and printed output. + +It is often desirable to have a way to produce +@acronym{HTML} from Texinfo sources, as GNU-Info files are +produced. It is much simpler to run a converter than it is to +rewrite all the documentation in @acronym{HTML}, especially +considering that there is so much Texinfo documentation in +the world. + +Some time ago @command{makeinfo} wasn't able to produce +@acronym{HTML} output format, but people still wanted documentation in +@acronym{HTML}. This was the birthing hour for +@command{texi2html}. The basic purpose of @command{texi2html} +is to convert Texinfo documents into @acronym{HTML}. + +Since then, @acronym{HTML} support in @command{makeinfo} has improved, but +@command{texi2html} is still stronger in many areas, including the degree to +which it allows customization. With @command{texi2html}, some important +aspects of the resulting @acronym{HTML} files may be specified via command +line options, and configuration 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 +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 +file. + +For an example of the kind of pages @command{texi2html} is capable of +producing, have a look at the following sites: +@uref{http://www.singular.uni-kl.de/Manual/html/,the Singular Manual}, +@uref{http://ccvs.cvshome.org/docs/manual,the Cederqvist (CVS Manual)}. + +@menu +* whytexi2html:: Why @command{texi2html} and not @command{makeinfo}?. +@end menu +@c -------------------------------------------------------- + +@node whytexi2html +@section Why @command{texi2html} and not @command{makeinfo}? + +@cindex makeinfo + +You would like to produce @acronym{HTML} files from your existing Texinfo +files? There are two programs you can use to do this. The first is +@command{makeinfo} (@pxref{Generating HTML,,,texinfo}). +The second is @command{texi2html}. + +The design goal of @command{makeinfo}'s @acronym{HTML} output was to produce +readable @acronym{HTML} output. It is now possible to use @acronym{CSS} +for @acronym{HTML} customization. Another possibility is to use intermediate +formats, like docbook or @command{mekeinfo} @acronym{XML} +and @acronym{XSL} stylesheets to customize the resulting document. Still the +output produced by @command{makeinfo} isn't customizable. + +The current development of @command{texi2html} tries to +provide for producing the more interesting and sophisticated @acronym{HTML} +pages that today's Internet users have come to expect. +The goal behind @command{texi2html} is to generate attractive @acronym{HTML} by +default but also to allow users considerable freedom to affect the final +style and design of the output @acronym{HTML} pages. This is achieved via +command line options and flexible configuration files. + +@c The main disadvantage of @command{makeinfo}'s +@c @acronym{HTML} output is that it is only available as one big file. +@c This is of course readable but not very usable. This would be hard to +@c remedy in @command{makeinfo}, as the Texinfo source has to be read in at +@c least twice to implement split nodes. This would require a major +@c rewrite of the @command{makeinfo} source. + +@c think more about this???? +In contrast to the @acronym{HTML} produced by @command{makeinfo --html} (the +@command{makeinfo} program is part of the Texinfo distribution), the +@command{texi2html} program, among other differences, allows for the +customization of the entire page layout, including headers, footers, style +sheets, etc., allows for customization of the low level @acronym{HTML} +formatting, provides for splitting documents at various levels, and provides +for using the @command{latex2html} program to convert @code{@@tex} sections of +the Texinfo source. + +The focus on @acronym{HTML} is still present but with the help of the +customization files it is now possible to use @command{texi2html} to +produce other formats as well. @command{texi2html} may for example be +turned into a texinfo to roff translator with the help of a customization file +provided with the distribution. + +@command{texi2html} should reasonably convert all Texinfo +4.8 constructs. If you find it does not, please send a bug report to the +@email{users@@texi2html.cvshome.org} email list. + +@c ======================================================== +@node Obtaining texi2html +@chapter Obtaining @command{texi2html} +@cindex downloading @command{texi2html} source +@cindex @command{texi2html} source, downloading +@cindex source code for @command{texi2html}, downloading + +The latest version of the source code for @command{texi2html} should be +available from @uref{http://texi2html.cvshome.org,texi2html.cvshome.org}. + +@c ======================================================== +@node Installation +@chapter Installation of @command{texi2html} +@cindex Installation +@cindex configure + +To install @command{texi2html}, you must first obtain a copy of the +source distribution. @xref{Obtaining texi2html}. + +@command{texi2html} also requires @command{perl} version +5.004 or above. The current version has not been tested +extensively on versions of @command{perl} below 5.6, however. + +@command{texi2html} is a standard Automake-based distribution. +If you have a source version, you should run @command{./configure} +to regenerate the executable @file{texi2html} file. @command{./configure} +accepts options to select the installation directory for the @file{texi2html} +file, the default directories @command{texi2html} will use to look for +configuration files, and other details. Run @command{./configure --help} for +more information. + +Running @command{./configure} combines four files into the final +@file{texi2html} program file: +@itemize +@item @file{texi2html.pl} contains the base program, +@item @file{MySimple.pm} handles the command line options, +@item @file{texi2html.init} is the default configuration file, and +@item @file{T2h_i18n.pm} is used for internationalization. +@item @file{translations.pl} contains the translations of the strings used in +documents. +@end itemize + +Running @command{./configure} also builds the @command{make} configuration +files (@file{Makefile}s). To make the documentation run @command{make}. + +@command{make install} performs the installation to the locations specified to +the @command{./configure} script. This usually involves placing the actual +@file{texi2html} file someplace in your path, such as @file{/usr/local/bin} or +@file{/usr/bin}. + +Installing @command{texi2html} in your path should be sufficient +to run it. To use default initialization files, or a configuration file for +La@TeX{}2HTML when using @command{latex2html} to convert @code{@@tex} sections +(@pxref{Expanding TeX regions}), install them in the package data directory +specified to configure. This is @file{/usr/local/share/texi2html/} by default, +but depends on the value of the @longopt{pkgdatadir=@var{dir}} option passed to +the @command{./configure} script. Files used for strings customization and +internationalization are also searched for in the @file{i18n} directory +of this directory. @xref{Using init files} for more. + +@c ======================================================== +@node Invoking texi2html +@chapter Invoking @command{texi2html} + +To produce an @acronym{HTML} manual, run @command{texi2html} with a Texinfo +file as an argument. For example, this manual is created with: + +@example +$ texi2html texi2html.texi +@end example + +The behaviour of @command{texi2html} may be changed with command line +options. These command line options are always associated with corresponding +@command{perl} variables which may appear in init files, and these +variables are presented in this chapter each time a switch is described. + +Boolean command line switches always have a corresponding negated switch, +obtained by prepending @samp{no} or @samp{no-} to the switch name. For example +@c PAT maybe it should be better to have @option{--nomenu} and @option{--menu} +@c as it is not needed and maybe harmfull to have an index entry for these +@c options here +@longopt{nomenu} does the reverse of @longopt{menu}. + +@menu +* Splitting output:: The @acronym{HTML} output may be split at + different levels +* Output files:: +* Expansion:: +* Texinfo related options:: +* Page layout options:: Customizing page layout +* Style options:: Customizing the @acronym{HTML} and text style +* Expanding TeX regions:: +* Using init files:: Specifying initialization files for fine tuning +@end menu + +@c -------------------------------------------------------- +@node Splitting output +@section Specifying where to split the generated document + +The @acronym{HTML} manual resulting from the processing of the Texinfo source +may be split into files at different levels. This is specified with the +option @longopt{split} which takes an argument, namely the level of splitting +(variable: @variable{$SPLIT}). This level may be: + +@table @asis +@item @samp{chapter} +The document is split at @code{@@chapter}, @code{@@appendix}, or @code{@@unnumbered}. +@item @samp{section} +The document is split at the same places as it is using the @samp{chapter} +argument, and also at @code{@@section}, @code{@@appendixsec} or +@code{@@unnumberedsec}. +@item @samp{node} +The document is split at every sectioning command. It is not necessarily +split at each node, if the @code{@@node} structure doesn't correspond with +the sectioning command structure (see below). +@item @samp{none} +The document isn't split. This is the default. +@end table + +There are two kinds of commands which may be used to define sectioning +elements in Texinfo: @code{@@node} and the structuring commands (@code{@@top}, +@code{@@section}, @code{@@appendixsubsec}, and so on). A node just preceding +a structuring command is considered to be part of the same sectioning element +as that command. If the @code{@@node Top} isn't associated with a structuring +command it also defines a sectioning element. + +By default, nodes which aren't associated with a structuring command are not +considered to be sectioning commands. They are always considered to be part +of a sectioning element defined by a structuring command. It is possible to +change this behaviour via the @longopt{use-nodes} option (variable +@variable{$USE_NODES}). In this case, nodes not associated with structuring +commands are also considered to be sectioning commands defining a sectioning +element. + +This default behaviour mimics @command{texi2dvi} behaviour, which ignores +@code{@@node} commands for the purprose of sectioning, while the second +looks like @command{makeinfo} behaviour (@pxref{Two Paths,,, texinfo}). + +As an illustration, the following table shows how a sample Texinfo document is +divided into sectioning elements when @longopt{use-nodes} is used and not: + +@multitable @columnfractions .2 .1 .2 .1 .2 +@item Texinfo code +@tab +@tab +default case +@tab +@tab +with @longopt{use-nodes} +@item +@* +@* +@example +@@node node1 +@@chapter node 1 +node1 text + +@@node node2 +node2 text + +@@node node3 +node3 text +@@chapter node 3 +chapter text +@end example +@tab +@tab +first element: + +@example +@@node node1 +@@chapter node 1 +node1 text + +@@node node2 +node2 text +@end example + +second element: + +@example +@@node node3 +node3 text +@@chapter node 3 +chapter text +@end example + +@tab +@tab +first element: + +@example +@@node node1 +@@chapter node 1 +node1 text +@end example + +second element: + +@example +@@node node2 +node2 text +@end example + +third element: + +@example +@@node node3 +node3 text +@@chapter node 3 +chapter text +@end example + +@end multitable + +@c -------------------------------------------------------- +@node Output files +@section Setting output file and directory names + +The manual name is constructed by stripping the @samp{.texi}, +@samp{.txi}, @samp{.texinfo}, or @samp{.txinfo} extension from the Texinfo file +name. + +By default, @command{texi2html} generates the manual file in the current +directory if the manual isn't split. A @samp{.html} file extension is appended +to the manual name. + +If the manual is split the files are put in a directory named after the +manual name. The file name is constructed using the manual name as basename. +An underscore followed by a number is appended +to the basename for each files corresponding with sectioning elements, with the +exception of the top element. For the top element there nothing appended. +The files containing special elements pages +have an underscore and a 3 letter code corresponding to their content +(@samp{toc} for table of contents, @samp{abt} for about, @samp{ovr} for +overview) appended. Lastly, an @samp{.html} file extension is appended. + +Thus, if the texinfo file @file{afile.texi} is processed and split at chapters +into 3 files, the generated files (in directory @file{afile}) will be: + +@example +afile.html --> @code{@@node Top} or @code{@@top} section +afile_1.html --> Chapter 1 +afile_2.html --> Chapter 2 +afile_toc.html --> Table of Contents +afile_abt.html --> About Page +@end example + +This default behavior may be modified by several command line options. If the +output isn't split, the prefix file name may be overrided by the +@longopt{output} command line option (variable @variable{$OUT}). If the output +is split, and @longopt{output} is set, the files are placed in the directory +specified by the argument to the option. + +The basename may be overridden with @longopt{prefix} (variable +@variable{$PREFIX}). If @longopt{short-ext} is given, @samp{.htm} is appended +instead of @samp{.html} in the final step (variable @variable{$SHORTEXTN}). +The @longopt{top-file} option +overrides the top element file name (variable @variable{$TOP_FILE}). This can +be used to name the top element file @samp{index.html}. Similarly, +@longopt{toc-file} changes the name of the table of contents file (variable +@variable{$TOC_FILE}). + +Reusing the example above, but this time calling @command{texi2html} like so: + +@example +$ texi2html -split chapter -prefix manual -short-ext -top-file index.htm -toc-file contents.htm afile.texi +@end example + +we get, in @file{manual}: + +@example +index.htm --> @code{@@node Top} or @code{@@top} section +manual_1.htm --> Chapter 1 +manual_2.htm --> Chapter 2 +contents.htm --> Table of Contents +manual_abt.htm --> About Page +@end example + +The file names generated by @command{texi2html} differ from those generated +by @command{makeinfo}. @command{makeinfo} uses the node name to construct +the file names while splitting at nodes. It is possible to get the same +behaviour out of @command{texi2html} by specifying the +@longopt{node-files} option (variable @variable{$NODE_FILES}). If the output +isn't split at nodes, @command{texi2html} will still output files named after +the nodes, without real content but redirecting to the right file. +The default is false for this option. +@c Is this true? It wasn't in the last version. -DRP +This trick enables the generated @acronym{HTML} manual to be a +target for the cross-references of other manuals generated by +@command{makeinfo} or @command{texi2html}. + +@c -------------------------------------------------------- +@node Expansion +@section Specifying which regions get expanded + +The default for @command{texi2html} is to expand the @code{@@ifhtml}, +@code{@@html}, and @code{@@menu} regions, all the @code{@@ifnot} regions +except @code{@@ifnothtml}, and no other @code{@@if} regions. + +It is possible to expand other regions by setting @longopt{if<region>}, +where @samp{<region>} is replaced by the literal name of the region (for +example, @samp{--iftex}). Symetrically, if @longopt{no-if<region>} is +specified, the @samp{<region>} region is ignored. The configuration file +array, @variable{@@EXPAND}, holds the names of regions which should be +expanded. The only region name present in @code{@@EXPAND} in the default case +is @samp{html}. + +If @longopt{nomenu} is set, the @code{@@menu} sections are not expanded +(variable @variable{$SHOW_MENU}). The default is to expand @code{@@menu} +sections. +@c How is --no-ifhtml specified? -DRP + +@c -------------------------------------------------------- +@node Texinfo related options +@section Command line options related to Texinfo language features + +Miscalleneous Texinfo related things may be specified via command line options. + +@table @asis +@item @longopt{lang=@var{lang}} +Sets the document language similar to the Texinfo directive, +@code{@@documentlanguage @var{lang}} (variable @variable{$LANG}). +The default is @samp{en}, that is, use the english language strings. +@item @shortopt{D@var{var}} +Sets @var{var}. Equivalent to, @code{@@set @var{var} 1}, in Texinfo. +@item @shortopt{U@var{var}} +Clears @var{var}. Equivalent to, @code{@@clear @var{var}}, in Texinfo. +@item @shortopt{P@var{dir}} +Prepend @var{dir} to the list of directories to search for +@code{@@include} files (the associated array is @variable{@@PREPEND_DIRS}, +empty in the default case). +@item @shortopt{I@var{dir}} +Append @var{dir} to the list of directories to search for +@code{@@include} files (the associated array is @variable{@@INCLUDE_DIRS}, +empty in the default case). +@end table + +The include files are always searched for in the current directory. + +@c -------------------------------------------------------- +@node Page layout options +@section Page layout related command line options + +If the @longopt{frames} option is specified, @acronym{HTML} frames +are used. A file describing the frame layout is generated, and the +document page is associated with a frame where the short table of +content appears (variable @variable{$FRAMES}). The default is not +to use frames. + +It is also possible to suppress the section navigation panel with +@longopt{nosec-nav} (variable @variable{$SECTION_NAVIGATION}, the default +is to output all the navigation panels), and to specify +whether footnotes should appear at the foot of the same page which contains +the reference to the note or on a separate page with +@longopt{separated-footnotes} (variable @variable{$SEPARATED_FOOTNOTES}). +The default is to have separated footnotes. + +@c -------------------------------------------------------- +@node Style options +@section Customizing the @acronym{HTML} and text style + +Miscalleneous style changes may be achieved with command line options. + +@table @asis +@item @longopt{doctype=@var{DTD}} +@itemx @longopt{frameset-doctype=@var{DTD}} +You can specify the document DTD by setting these options. +@longopt{frameset-doctype} applies to the file describing the frames when +frames are used (corresponding variables are @variable{$DOCTYPE} and +@variable{$FRAMESET_DOCTYPE}). + +The default for the document doctype is: +@example +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> +@end example +And for the frameset doctype: +@example +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html401/frameset.dtd"> +@end example + +@item @longopt{iso} +If this option is set, ISO8859 entities are used for some special symbols, +like Copyright @copyright{} (variable @variable{$USE_ISO}). It is the default. + +@item @longopt{css-include=@var{file}} +This command line switch provides for the inclusion of an external +Cascading Style Sheet (@acronym{CSS}) file. More than one file may be +specified, and @samp{-} stands for the standard input (array +@variable{@@CSS_FILES}). + +The option use is the same than for @command{makeinfo} and is described +extensively in @ref{HTML CSS,,,texinfo}. +Briefly, the @acronym{CSS} @code{@@import} lines from the external file +@acronym{CSS} file are pasted before the +@c What does this mean? I don't think I clarified this one much. -DRP +@c Is it better ? -PAT +@command{texi2html} @acronym{CSS} rules, and the external file @acronym{CSS} +rules are pasted after the @command{texi2html} @acronym{CSS} rules. + +@item @longopt{html-xref-prefix=@var{path}} +This option sets the base directory for external @acronym{HTML} texinfo manuals +(variable @variable{$EXTERNAL_DIR}). Defaults to @samp{../}. + +@item @longopt{def-table} +If this option is set, @acronym{HTML} tables are used to format definition +commands, rather than @acronym{HTML} definition tables (variable +@variable{$DEF_TABLE}). Default is false. + +@item @longopt{short-ref} +If this option is set, cross-references are given without section numbers +(variable @variable{$SHORT_REF}). Default is false. + +@item @longopt{number} +If this option is set, sections are numbered (variable +@variable{$NUMBER_SECTIONS}). This is the default. + +@item @longopt{toc-links} +If this option is set, links from headings to @acronym{TOC} entries are +created (variable @variable{$TOC_LINKS}). Default is false. +@end table + +@c -------------------------------------------------------- +@node Expanding TeX regions +@section Expanding @code{@@tex} and @code{@@math} regions using La@TeX{}2HTML + +It is possible to use @uref{http://www.latex2html.org/,La@TeX{}2HTML} +to process @code{@@tex} regions and @code{@@math@{@}} commands. This is an +attractive way to display mathematical constructs in the @acronym{HTML} +manual. The @longopt{l2h} option activates this feature (variable +@var{$L2H}). It is usually desirable to expand @code{@@tex} sections when this +option is specified (@pxref{Expansion}). The default is not to use this +feature. + +The @longopt{l2h-l2h=@var{program}} option enables changing the name/location +of the La@TeX{}2HTML program processing @TeX{} regions (variable +@variable{$L2H_L2H}). The default is @command{latex2html}. + +@longopt{l2h-tmp} sets the directory used for temporary +files, this name shouldn't contain a dot @samp{.} +@c Why not? -DRP +(variable is @variable{$L2H_TMP}). Defaults to the current dir. + +The file specified by @longopt{l2h-file} is +used as La@TeX{}2HTML init file. It is searched at the same places than +init files (@pxref{Using init files}), and the default is @file{l2h.init}. + +@c -------------------------------------------------------- +@node Using init files +@section Use initialization files for fine tuning + +@cindex internationalization +@cindex @file{Config} + +Initialization variables are read first from +@file{/usr/local/share/texi2html/Config} (the exact location being +changeable with the @longopt{pkgdatadir=dir} option of the +@command{configure} script, see @ref{Installation}), +@file{/usr/local/etc/texi2html/Config} (the exact location being +changeable with the @longopt{sysconfdir=dir} option of the +@command{configure} script, see @ref{Installation}), from @file{./Config} +then from @file{$HOME/.texi2html/Config}. Any command-line option +can override the corresponding option set in init file, and the +option @longopt{init-file} specifies an init file to be loaded, with +later settings overriding earlier ones. + +The init files specified with @longopt{init-file} are searched +first in the current directory, then in the @file{$HOME/.texi2html/} +directory, in the @file{/usr/local/etc/texi2html/} directory and lastly +in the @file{/usr/local/share/texi2html/} directory. + +A file is also included based on the language selected, +by @variable{$LANG}, @longopt{lang} or @code{@@documentlanguage}. +If no language was selected @samp{en} is considered to be +the language. All the files with name the language name in +@file{/usr/local/share/texi2html/i18n/}, +@file{/usr/local/etc/texi2html/i18n/}, +@file{$HOME/.texi2html/i18n/} and then @file{./i18n/} are included. + +The default initialization options are defined in the +@file{texi2html.init} file contained in the @command{texi2html} +distribution (which gets included near the beginning of the +@command{texi2html} script that gets installed). + +To customize @command{texi2html} it is best if you copy the +appropriate sections from the @file{texi2html.init} +contents into an appropriate local initialization file, +make the necessary changes there, and then have +@command{texi2html} read this initialization file by one of +the means described above. + +@c ======================================================== +@node Initialization files +@chapter Overview of initialization files content and loading + +The initialization files are @command{perl} files, read as explained +in @ref{Using init files}. You don't need to know much of @command{perl} +to do some simple changes in variable values, however, to be able to +really take advantage of all the features of the initialization file, +a good knowledge of @command{perl} is required. + +In initialization file two kind of variables appear. These are normal +variables (including arrays and hashes) and references on functions. +The later permits the dynamic redefinition of functions used to produce +the @acronym{HTML} manual. You should be able to change the value of some +normal variables without a deep knowledge of @command{perl}, by looking +at the existing examples. The possible mistakes in that case could be +omitted @samp{;}, and bad quoting. + +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 inititalization files are distinct, which ensures +that no name clash should happen. The variables are declared with the +@code{our} specifier, such that it should be possible to use the +@code{use 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. + +@menu +* Redefining functions:: Function redefinition is achieved with + redefinition of references on functions. +* Function prototypes:: Conventions used in that manual for function + reference prototypes display. +@end menu + +@c -------------------------------------------------------- +@node Redefining functions +@section 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 an 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 @variable{$anchor}. Thus if you want to override the +corresponding function +you could write: + +@example +# 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 +@} +@end example + +@c -------------------------------------------------------- +@node Function prototypes +@section 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 +@code{\%hash} for a reference on a hash. + +Thus, the prototype for the function associated with the function +reference @samp{$formatting_function} will be: + +@deftypefn {Function Reference} $text formatting_function $arg1 \@@arg2 +@code{formatting_function} takes as first argument @var{$arg2}, +as second argument a reference on an array @var{\@@arg2} +and returns the formatted text @var{$text}. +@end deftypefn + +To redefined the corresponding function, you should 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 + +@c -------------------------------------------------------- +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@c ======================================================== +@c @include custpage.texi +@node Changing the page layout +@chapter Fine tuning of the page layout + +Some features of the page layout might be specified with command line +options, the corresponding variables are described in +@ref{Page layout options}. +Fine tuning of the page layout may be achieved +with redefinition of other variables and function references in the +initialization files. + +@menu +* The different pages:: The different categories of pages. +* The page layout:: The elements of a page. +* Navigation panel:: How to change the navigation panel. +* Program variables:: The available main program variables and some + usefull functions from the main program. +* Output initialization:: Setting variables before the document + production but after the texinfo parsing. +* Output finalization:: Cleaning after document generation. +* css:: Customizing css lines. +* Customizing header:: +* Customizing section:: +* Customizing footer:: +* Special pages:: Customizing table of contents, top, about page. +* File names:: Customizing the file names. +* External index files:: Putting index entries in external files. +@end menu + +@c -------------------------------------------------------- +@node The different pages +@section The different categories of pages and sectioning elements + +The following sectioning elements can be associated with pages: + +@table @emph +@item Normal elements +These are normal sections or nodes. Their association with pages is +determined by the splitting of the document. @xref{Splitting output}. +@item 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 +@code{@@node Top}. If there is no @code{@@node Top} the first element is the +top element. + +The top element is formatted differently than a normal element if there +is a @code{@@top} section or the @code{@@node Top} isn't associated +with a sectioning command. +@item Misc elements +These elements are associated with pages if the document is split. +There are four misc elements: +@enumerate +@item Table of contents +@item Short table of contents, also called Overview +@item Footnotes page +@item About page +@end enumerate + +The @emph{About page} shouldn't be present for documents consisting +in only one sectioning element. The @emph{Footnote page} should only +be present if the footnotes appear on a separated page +(@pxref{Page layout options}), 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. +@end table + +@c -------------------------------------------------------- +@node The page layout +@section Page layout and navigation panel overview + +A page is broken up in three parts. A page header, the sections +and a page footer. A common element in the page layout is a navigation +panel with icons or text linking to other sections or pages. Another +common element is a rule, separating sections or footer. The navigation +panel and the rules may be part of the sections or part of headers or +footers. You may use the variables @variable{$SMALL_RULE}, +@variable{$DEFAULT_RULE}, @variable{$MIDDLE_RULE} and @variable{$BIG_RULE} +for rules of different sizes. +The defaults are +@example +$SMALL_RULE = '<hr size="1">'; +$DEFAULT_RULE = '<hr>'; +$MIDDLE_RULE = '<hr size="2">'; +$BIG_RULE = '<hr size="6">'; +@end example + +In the header some important meta data may be defined, like the +title or style information, and textual informations may be present +in comments. All this doesn't appear directly in the displayed +@acronym{HTML}, though. + +The page layout is mainly controlled by functions, the precise functions +called depending on the document splitting. The navigation panel, however, +can be customized with variables. + +@subheading Element labels +@anchor{Element labels} + +There are 19 items 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 or an element relative to the current +element. The relative elements are found with respect with the document +structure defined by the section structuring commands (@code{@@chapter}, +@code{@@unnumbered}@dots{}) or by the nodes (in that case the node +directions are specified on node line or in menu organization). +These items are called @dfn{element labels}. They may be associated with +a button (@pxref{Button specifications}), and used in the formatting functions +(@pxref{Program variables}). + +Here is the list: + +@table @emph +@item @samp{@ } +An empty button +@item Top +Top element. The associated name is @variable{$TOP_HEADING} if that variable is +defined. This variable is not set by default. +@item Contents +Table of contents +@item About +About (help) page +@item Overview +Overview, short table of contents +@item First +First element in reading order +@item Last +Last element in reading order +@item Index +The first chapter with @code{@@printindex}. The associated name +is @variable{$INDEX_CHAPTER}, if the variable is set. This variable is not set +by default. +@item This +The current element +@item Back +Preceding element in reading order +@item FastBack +Beginning of this chapter or previous chapter if the element is a chapter +@item Prev +Previous section on the same level +@item NodePrev +Previous node +@item Forward +Next element in reading order +@item FastForward +Next chapter +@item Next +Next section on the same level +@item NodeNext +Next node +@item Following +Next node in node reading order +@item Up +Up section +@item NodeUp +Up node +@end table + +@c -------------------------------------------------------- +@node Navigation panel +@section Customization of the navigation panels buttons + +A lot of customization of the navigation panel may be achieved without +redefining functions, with variables redefinition. +In case it isn't enough, it is also possible to redefine the function +doing the navigation panel formatting. + +@menu +* General purpose variables:: Variables controlling the navigation panel + at a global level +* Button specifications:: +* Panel formatting function:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node General purpose variables +@subsection Controlling the navigation panel panel at a high level + +The global formatting of the navigation panels may be +changed with the following variables: + +@vtable @code +@item $VERTICAL_HEAD_NAVIGATION +A vertical navigation panel will be used for the header navigation +panel if this variable is true. +@item $ICONS +Icons are used instead of +textual buttons if this variable is true. +@item $SECTION_NAVIGATION +If this variable is false there is no section navigation, no navigation +panels for the elements within the pages, only at +the beginning and the end of the page (@pxref{Page layout options}). +@end vtable + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Button specifications +@subsection 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: + +@vtable @code +@item @@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. +@item @@SECTION_FOOTER_BUTTONS +@itemx @@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 @variable{$WORDS_IN_PAGE} is set and the output is split at nodes, these +buttons are only present if there are more than @variable{$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. +@item @@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. +@item @@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. +@end 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: + +@table @emph +@item reference on a function +The function is called with first argument a filehandle reference on the +current file and second argument a boolean true if the navigation +panel should be vertical. +@item reference on a scalar +The scalar value is printed. For some possibly +usefull scalars, @ref{Elements hashes}. +@item 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 +@example +[ 'Next', \$Texi2HTML::NODE@{Next@} ] +@end example + +The button will be a link to the next section with text +@variable{$Texi2HTML::NODE@{Next@}}. +@item 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 @variable{%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}). + +If icons are used, the button is an image with file determined by +the value associated with the element label in the @variable{%ACTIVE_ICONS} +hash if the the link really leads to an element, or in the @variable{%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. +@end table + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Panel formatting function +@subsection 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: + +@deffn {Function Reference} print_navigation $filehandle \@@buttons $vertical +@var{$filehandle} is the opened filehandle the function should write to. +@var{\@@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. +@end deffn + +@c -------------------------------------------------------- +@node Program variables +@section Main program variables and usefull functions + +In the functions +controlling the page layout some global variables set by the main +program are available, with value corresponding with the current +layout element. + +@menu +* Elements hashes:: Accessing information related with the + different elements +* Global informations:: Accessing global informations, like date, + title@dots{} +* Global functions:: main program usefull functions +@end menu + + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Elements hashes +@subsection Accessing elements informations + +Four hashes are available, with key the elements labels (as described +in @ref{Element labels}) and values: + +@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 + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Global informations +@subsection Accessing global informations + +Three kinds of global informations are available, miscalleneous global +strings, flags set by @code{@@set} and special flags and section lines. + +@subsubheading Global strings +The @variable{%Texi2HTML::THISDOC} hash holds some global informations: + +@table @code +@item fulltitle +title set by @code{@@title}. If there is no @code{@@title} other +possibilities are tried (@code{@@settitle}, @code{@@shorttitlepage}@dots{}). +@item title +title set by @code{@@settitle}, or @code{fulltitle}. +@item title_no_texi +title without texi formatting +@item title_texi +title with texi commands +@item author +Authors list set by @code{@@author}. +@item authors +A reference on an array containing each author set by @code{@@author}. +@item copying +Text appearing in @code{@@copying} with all the texinfo commands removed, +put in comments. +@item program +The name and version of @command{texi2html}. +@item program_homepage +Homepage for @command{texi2html}. +@item program_authors +Authors of @command{texi2html}. +@item file_base_name +base name of the texinfo manual file. +@item destination_directory +Destination directory for the resulting files. +@item toc_file +The file name of the table of contents. +@item today +The date. +@end table + +It also holds the arg of the following commands, associated with the command +name: kbdinputstyle, paragraphindent, setchapternewpage, headings, +footnotestyle, + exampleindent, firstparagraphindent, everyheading, everyfooting, + evenheading, evenfooting, oddheading, oddfooting. + + +@subsubheading Flags +Flags defined by @code{@@set} may be accessed through the +@variable{%main::value} hash. The key is the flag name, the value is the +flag value at the end of the document. + +Special flags are set by the main program. They correspond with a texinfo +command, like @code{@@setfilename}, or @code{@@settitle}, +@code{@@author}@dots{} The corresponding flag is the command name with +@samp{_} appended, for example, @code{_titlefont} corresponds with +@code{@@titlefont}. Like other flags they are available in +@variable{%main::value}. + + +@subsubheading Section lines + +The following array references or arrays holds formatted lines: + +@vtable @code +@item $Texi2HTML::THIS_SECTION +Lines of the current element. +@item $Texi2HTML::THIS_HEADER +Lines of the current element appearing before the element label (anchors). +@item $Texi2HTML::OVERVIEW +Lines of short table of contents. @xref{Special pages}. +@item $Texi2HTML::TOC_LINES +Lines of table of contents. @xref{Special pages}. +@end vtable + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Global functions +@subsection Function usefull in page formatting + +The usefull function is a function used to print an array of lines, which +also counts the number of words in the array, if needed. + +@deftypefun $words_number main::print_lines $filehandle \@@lines_array +@var{$filehandle} is the opened filehandle the function should write to. +@var{\@@lines_array} is the array line the function should write to the file. +If this argument is omitted, the function uses @variable{$Texi2HTML::THIS_SECTION}. +@var{$words_number} is the number of words in the array, only defined if +split at nodes and @variable{$WORDS_IN_PAGE} is defined. +@end deftypefun + +@c -------------------------------------------------------- +@node Output initialization +@section 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: + +@deftypefn {Function Reference} $encoding init_out +This function perform the initialization of variables and any other +task before document outputting. It returns the encoding used for the +output files. +@end deftypefn + +In the default case the @variable{$BODYTEXT} (@pxref{Customizing header}) +and the hashes @variable{%NAVIGATION_TEXT} (@pxref{Button specifications}) and +@variable{%BUTTONS_GOTO} (@pxref{About text}) are 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) : + +@example +my $default_init_out = $init_out; +$init_out = \&makeinfo_like_init_out; +sub makeinfo_like_init_out() +@{ + my $encoding = &$default_init_out(); + $NAVIGATION_TEXT@{'Following'@} = ' > '; + return $encoding; +@} +@end example + +@c -------------------------------------------------------- +@node Output finalization +@section 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: + +@deffn {Function Reference} finish_out +This function is called after the document generation. +@end deffn + +The default is to do nothing. + +@c -------------------------------------------------------- +@node css +@section Customizing the @command{texi2html} css lines + +It is possible to modify the @command{texi2html} css lines by modifying +the entries or adding to the @variable{%css_map} hash. Each key is a css +selector, the corresponding value is a style string. + +The whole css text is in the variable @variable{$CSS_LINES}. If this +variable is defined the variable value is used instead of being +constructed using the @variable{%css_map} entries. For example if you don't +want any css entries, set + +@example +$CSS_LINES = ''; +@end example + +It is also possible to change completely the way @variable{$CSS_LINES} are +generated by redefining the following function reference: + + +@deffn {Function Reference} css_lines \@@import_lines \@@rule_lines +This function should be used to construct the @variable{$CSS_LINES}. +@var{\@@import_lines} are the @code{@@import} lines of the +files specified with @longopt{include-css}, +and @var{\@@rule_lines} are the css commands lines of these files. +@xref{Style options}. +@end deffn + +@c -------------------------------------------------------- +@node Customizing header +@section Customizing the page header + +It is possible to add lines to the text within the @code{<head>} +@acronym{HTML} elements, by defining the variable @variable{$EXTRA_HEAD}. +Similarly it is possible to add text just after the @code{<body>} +element with the variable @variable{$AFTER_BODY_OPEN}. +These variables are empty by default. + +The encoding of the texinfo file is defined by @variable{$DOCUMENT_ENCODING} +if no @code{@@documentencoding} appears in the document. +The default is a @samp{en-ascii} encoding. +The encoding of the resulting document is defined by +@variable{$ENCODING}. The default is the @code{$DOCUMENT_ENCODING}. + +The description of the document may be specified in +@variable{$DOCUMENT_DESCRIPTION}. If this variable is undef, the text +associated with @code{@@documentdescription} is used, and if there isn't +such test a default description is constructed using the document title and +the name of the first section of the file. + +The @code{<body>} element attributes may be set by defining the +variable @variable{$BODYTEXT}. If you want to define that variable +dynamically, you should use the @code{init_out} function reference +(@pxref{Output initialization}). + +The default functions call the function associated with +@variable{$print_head_navigation} to format the navigation panel for the +page header. Thus you can control parts of the formatting by +redefining the function reference. + +@deffn {Function Reference} print_head_navigation $filehandle \@@buttons +@var{$filehandle} is the opened filehandle the function should write to. +@var{\@@buttons} is an array reference which should hold the specification of +the buttons for the navigation panel. +@end 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 @variable{$print_page_head} is called for all the pages, and after that, +the function associated with @variable{$print_chapter_header} is called +if the document is split at chapters, or the function associated with +@variable{$print_section_header} is called if the document is split at sections. + +@deffn {Function Reference} print_page_head $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function should print the page head, including the @code{<body>} +element. +@end deffn + +@deffn {Function Reference} print_chapter_header $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function is called if the document is split at chapters, after +@code{print_page_head}. +@end deffn + +@deffn {Function Reference} print_section_header $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function is called if the document is split at sections, after +@code{print_page_head}. +@end deffn + +@c -------------------------------------------------------- +@node Customizing section +@section Customizing the sections + +The functions associated with the following function references are used for +the formatting of sections: + +@deffn {Function Reference} print_section $filehandle $first_in_page $previous_is_top +@var{$filehandle} is the opened filehandle the function should write to. +@var{$first_in_page} is true if this section is the first section in the page. +@var{$previous_is_top} is true if this section is the section following the +Top section. +This function should print the current section. +@end deffn + +@deffn {Function Reference} end_section $filehandle $last_element_or_before_top +@var{$filehandle} is the opened filehandle the function should write to. +@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 + +@c -------------------------------------------------------- +@node Customizing footer +@section Customizing the page footer + +It is possible to add text just before the @code{</body>} +element with the variable @variable{$PRE_BODY_CLOSE}. Nothing is added +by default. + +@ignore +The footer text may be influenced by @variable{$ADDRESS} which should hold +information about who created the document and how. +If you want to define that variable +dynamically, you could redefine the following function reference: + +@deftypefn {Function Reference} $address_text address $user $date +This function should return the address. @var{$user} is the user name +of the user running @command{texi2html}, @var{$date} is the date of the day. +@end deftypefn +@end ignore + +The default functions call the function associated with +@variable{$print_foot_navigation} to format the navigation panel for the +page footer. Thus you can control parts of the formatting by +redefining the function reference. + +@deffn {Function Reference} print_foot_navigation $filehandle \@@buttons +@var{$filehandle} is the opened filehandle the function should write to. +@var{\@@buttons} is an array reference which should hold the specification of +the buttons for the navigation panel. +@end deffn + +If you want even more control, you can have full control the page footer +formatting by redefining three function references. +The function associated with @variable{$print_chapter_footer} is called +if the document is split at chapters, or the function associated with +@variable{$print_section_footer} is called if the document is split at sections. + After that the function associated +with @variable{$print_page_foot} is called. + +@deffn {Function Reference} print_page_foot $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function should print the page foot, including the @code{</body>} +element. +@end deffn + +@deffn {Function Reference} print_chapter_footer $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function is called if the document is split at chapters, before +@code{print_page_foot}. +@end deffn + +@deffn {Function Reference} print_section_footer $filehandle +@var{$filehandle} is the opened filehandle the function should write to. +This function is called if the document is split at sections, before +@code{print_page_foot}. +@end deffn + + +@c -------------------------------------------------------- +@node Special pages +@section Special pages formatting + +For the special elements, two things must be formatted: the content +and the page layout + +@menu +* Special pages content:: +* Special pages layout:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Special pages content +@subsection Customizing the content of the special pages + +@menu +* Top element text:: +* Contents and Overview text:: +* Footnotes text:: +* About text:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Top element text +@subsubsection 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: + +@deffn {Function Reference} print_Top_header $filehandle $begin_page +@var{$filehandle} is the opened filehandle the function should write to. +@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 hasn't been parsed. +@end deffn + +@deffn {Function Reference} print_Top $filehandle $has_top_heading +@var{$filehandle} is the opened filehandle the function should write to. +@var{$has_top_heading} is true if there is a @code{@@heading} command or +@code{@@titlefont} command appearing in the Top element text. +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 +@var{$filehandle} is the opened filehandle the function should write to. +@var{$end_page} is true if the element is the last in a page. +This function should end the Top element. +@end deffn + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Contents and Overview text +@subsubsection Table of contents and Short table of contents +Several variables may be used to control the formatting of table of contents +and short table of contents: + +@vtable @code +@item $DO_CONTENTS +If the variable is true a table of contents is done even if there is no +@code{@@contents} command. +@item $DO_SCONTENTS +If the variable is true a short table of contents is done even if there is no +@code{@@summarycontents} command. +@item $BEFORE_OVERVIEW +The variable value is inserted before the short table of contents text. +@item $AFTER_OVERVIEW +The variable value is inserted after the short table of contents text. +@item $BEFORE_TOC_LINES +The variable value is inserted before the table of contents text. +@item $AFTER_TOC_LINES +The variable value is inserted after the table of contents text. +@item $TOC_LIST_STYLE +This should contain a css style used for the list style if the tables of +content are formatted with a list. +@item $TOC_LIST_ATTRIBUTE +This should contain an attribute text used for the list element if the tables of +content are formatted with a list. +@end 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: + +@deffn {Function Reference} toc_body \@@elements +@var{\@@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: + +@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 content. Highest level +is 1 for the top element and for chapters, appendix and so on, +2 for section, unnumberedsec and so on... +@item tocid +label used for reference linking to the element in table of +contents, +@item file +the file containing the element, usefull to do href to that file +in case the document is split, +@item text +text of the element, with section number, +@item name +text of the element, without section number. +@end table + +This function doesn't return anything but should fill the array corresponding +with the +@variable{$Texi2HTML::TOC_LINES} and +@variable{$Texi2HTML::OVERVIEW} references with the table of contents and short +table of contents. + +@end deffn + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Footnotes text +@subsubsection Formatting of footnotes text + +The footnotes text is allready formatting when @code{@@footnote} commands +are expanded. @xref{Footnotes}. + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node About text +@subsubsection 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: + +@table @code +@item $PRE_ABOUT +@itemx $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. +@item %BUTTONS_GOTO + +The keys of this hash are element labels (@pxref{Element labels}). The value +is the text associated with the element label in the about text. +The element of the hash are defined +dynamically, you should in the @code{init_out} function reference +(@pxref{Output initialization}). + + +@item %BUTTONS_EXAMPLE + +The keys of this hash are element labels (@pxref{Element labels}). The value +is the text associated with the element label in the about example, +typically a section number. + +@end 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: + +@deftypefn {Function Reference} $about_text print_about +This function should return the about text. +@end deftypefn + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Special pages layout +@subsection Customizing the layout of the special 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: + +@ftable @code +@item print_Top +@item print_Top_header +@item 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}). +@item print_Toc +Formatting of table of contents page or section +@item print_Overview +Formatting of short table of contents page or section +@item print_About +Formatting of about (help) page or section +@item print_Footnotes +Formatting of footnotes section or page in case footnotes are on a +separated page or the document isn't split. +@end ftable + +In the default case, @variable{$print_Top} calls @variable{$print_Top_header} for +the header and @variable{$print_Top_footer} for the footer of top element. +All the other function call @variable{$print_misc} which in turn calls +@variable{$print_misc_header} for the headers and @variable{$print_misc_footer} +for the footers. + +@c -------------------------------------------------------- +@node File names +@section Customizing the file names + +It is possible to specify the file names with more control than with the +command line options (@pxref{Output files}). +First the extension may be overrided by the variable @variable{$EXTENSION} +value. +Two function references enable +further customization. One is usefull in case @variable{$NODE_FILES} is true +and it is used to customize the node file name itself and is also used +to produce a file name with a redirection leading to the node file. + +@deftypefn {Function Reference} {($node_file $redirection_node_file)} node_file_name $node +@var{$node} is a hash reference with the following interesting keys (there +are much more keys): +@table @code +@item texi +The texinfo node name. +@item with_section +True if associated with a section. +@end table +The result is the node file name @var{$node_file}, and the file containing +a redirection to the node @var{$redirection_node_file}. +@end deftypefn + +The other is usefull if @code{$NODE_FILES} isn't true. It is used to +customize the file associated with each element. +@deftypefn {Function Reference} $file element_file_name $element $is_top $docu_name +@var{$element} is a hash reference with the following interesting keys (there +are much more keys): +@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{$is_top} is true if the element is considered as the top element. +@var{$docu_name} is the basename of the texinfo manual. +The result is the element file name. +@end deftypefn + +@c -------------------------------------------------------- +@node External index files +@section Generation of external files for index entries + +Within the document, @code{@@printindex} commands are expanded as explained +in @ref{Index list}. In case you want to do something special with index +entries, outside of the document, you should first set the variable +@variable{$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 finalazation. + +@deffn {Function Reference} index_summary_file_begin $index_name $is_printed +@var{$index_name} is the two letters name for the index. +This function +is called for each index +appearing in the document, before +@code{index_summary_file_entry}. +@var{$is_printed} is true if there is a @code{@@printindex} for that index. +@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 +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, +@var{$formatted_entry} 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}. +@var{$entry_element_header} 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 +@samp{file#id}. +@var{$is_printed} is true if there is a @code{@@printindex} for that index. +@end deffn + +@deffn {Function Reference} index_summary_file_end $index_name $is_printed +@var{$index_name} is the two letters name for the index. This function +is called for each index appearing in the document, after +@code{index_summary_file_entry}. +@var{$is_printed} is true if there is a @code{@@printindex} for that index. +@end deffn + +@c ======================================================== +@node Customizing HTML +@chapter Customizing @acronym{HTML} and text style in init files + +Some simple customization may be achieved with the redefinition of the +variables +associated with the command line options. For the description and an +explanation of the meaning of these variables, @ref{Style options}. + +Other variables and hash entries can be modified in initialization file +to achieve more customization. +Lastly, functions references corresponding with functions called from +the main program and initialization files may +be redefined. + +@menu +* Three contexts:: there are three different contexts for command + expansion: normal text, preformatted text and + strings. +* Commands without argument:: +* Style and accent commands:: +* Anchors images and spaces:: Formatting of @code{@@anchor}, @code{@@image}, @code{@@sp}, @code{@@acronym}, @code{@@abbr} +* Text:: Some characters are processed specially +* Strings:: @command{texi2html} write some strings in the output + different for each languages +@c * Skipped commands:: +* References:: +* Alignement commands:: @code{@@center}, @code{@@flushleft}@dots{} +* Paragraph and preformatted region:: +* Complex formats:: @code{@@example}, @code{@@display}@dots{} +* Lists tables:: +* Definitions:: +* Headings:: +* Special regions:: @code{@@verbatim}, @code{@@cartouche}, @code{@@quotation} +* Menus:: +* Indices:: +* Floats and lists of floats:: @code{@@float} and @code{@@listoffloats} +* Footnotes:: +* Other and unknown commands:: You can handle specifically other commands + +@end menu + +@c -------------------------------------------------------- +@node Three contexts +@section Three contexts for expansions: preformatted, normal and string + +There are three contexts of interest, one is the normal context, the other +is a special context, called the @dfn{preformatted} context and the last is +the string context. The preformatted +context occurs when the spacing between words is kept. This is the +case, for example, in @code{@@display} or @code{@@example} regions, and in +menu comments (@pxref{Menus}). The preformatted regions are usually +rendered in @code{<pre>} elements in @acronym{HTML}. +The string context occurs when rendering strings without formatting elements, +in comments or titles for example. + +@c -------------------------------------------------------- +@node Commands without argument +@section Customizing the formatting of commands without argument + +This includes the commands whose name is a nonletter character like @code{@@@@}, +the commands with lettered characters and braces +but whose braces should be empty, like @code{@@TeX@{@}}, or some commands +associated with accentted letters like @code{@@AA@{@}}. If there happens to +be something within the braces, it is put after the command, thus +@example +@@TeX@{something@} +@end example +leads to the same than +@example +@@TeX@{@} something +@end example + +Each of these categories of commands have three associated hashes, one +for normal +context, the other for preformatted context and the last in strings. The +keys of the hashes are the +command names, the associated value is the text replacing the command. + +The hashes are: +@multitable {one nonlettered character} {normal text} {preformatted text} {string} +@item command type @tab normal text @tab preformatted text @tab string +@item one nonlettered character @tab @variable{%simple_map} @tab @variable{%simple_map_pre} @tab @variable{%simple_map_texi} +@item nothing in braces @tab @variable{%things_map} @tab @variable{%pre_map} @tab @variable{%texi_map} +@end multitable + +To change the @acronym{HTML} resulting from these constructs, just change the +value. For example, if you want @code{­} to be outputted for @code{@@-} +in normal and preformatted context, write in your init file: + +@example +$simple_map@{'-'@} = '­'; +$simple_map_pre@{'-'@} = '­'; +@end example + +@c -------------------------------------------------------- +@node Style and accent commands +@section Customizing accent, style and other simple commands + +The formatting of the @acronym{HTML} produced by style and indicatric +commands (@code{@@tt}, @code{@@code}, +@code{@@email}, @code{@@titlefont}), the accentuation related +commands taking argument (@code{@@'}, @code{@@udotaccent}, @code{@@dotless}) +and miscalleneous commands (@code{@@email}, @code{@@verb}, @code{@@w}, +@code{@@uref}, @code{@@math}, @code{@@asis}) is controlled by two hash in the +default case, +@variable{%style_map} for normal context, @variable{%style_map_pre} for +preformatted context and @variable{%style_map_texi} in string context. + +The key of the hashes are the command names. There are two possibilities for +the values corresponding with two interfaces. The values may be strings or +hash references, and you can chose the interface depending on the one you +prefer. The interface with hash reference is a bit more flexible but might also +be regarded as more complex. If you don't like either of these interfaces you +can define your own. + +Some remarks are in order: + +@itemize +@item +The nonlettered accent commands which following character is considered +to be the argument (like in @code{@@`a}) should be keys of the +hash @variable{%accent_map} hash, even if no value is associated. +@item +@code{@@math} is handled differently if La@TeX{}2HTML is used. +@end itemize + +@menu +* Hash reference interface:: +* String interface:: +* Define your own interface:: +@end menu + +@node Hash reference interface +@subsection An interface for commands formatting with a hash reference + +The key of the hashes are the command names. The value determine how the command argument +is formatted. This value is a reference on a hash. In this hash each key +corresponds with a type of information for the formatting, and the value is +the corresponding information. For example, in + +@example +$style_map@{'command'@} = @{ 'args' => ['code'], 'attribute' => 'code'@}; +@end example + +the arguments for @code{@@command} are interpreted as specified by +the values associated with the @samp{args} key while the attribute associated +with that command is @samp{code}. + +The following keys in the hashes associated with each command have the +following meaning: + +@table @samp +@item args +@anchor{Reference hash args} +The value associated is a reference on an array. Each element of the array +defines how the arguments (separated by @samp{,} in the texinfo code) for +the @@-command should be +formatted. The possibilities are +@table @code +@item normal +for normal text, +@item code +for text with @samp{---}, @samp{--}, @samp{''} and @samp{``} kept as is, +@item keep +if the texinfo should be kept as is, without interpretation of the @@-commands. +@end table + +For example, we have +@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}. + +The default is @samp{['normal']}. + +@item attribute + +If the associated value is a word, it is considered to be an @acronym{HTML} +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 @acronym{HTML} is @code{<elem>@var{arg}</elem>}. + +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. +Thus @code{elem class="elem"} leads to +@code{<elem class="elem">@var{arg}</elem>}. + +This works only if there is only one argument. + +@item begin + +The associated value is added in front of the text. + +@item begin + +The associated value is added after the text. + +@item quotes + +If the corresponding value is true, the result is +enclosed in quotes @variable{$OPEN_QUOTE_SYMBOL} and +@variable{$CLOSE_QUOTE_SYMBOL}, with defaults +@samp{`} and @samp{'}. + +@item function + +The corresponding value should be a function reference. The corresponding +function is called with the following arguments: + +@table @code +@item $command +The @@-command name +@item $args +A reference on an array containing the arguments of the @@-command. +@item $style_stack +A reference on an array containing the name of the @@-commands containing +the @@-command being formatted. +@item $state +A reference on a hash containing a lot of informations about the context +of the @@-command. +@item $line_nr +An opaque structure containing the information about the line number of the +@@-command. It can be used to call @code{main::echo_error} or +@code{main::echo_warning} with first argument a message, and second argument +@code{$line_nr}. +@end table +@end table + +@node String interface +@subsection An interface for commands formatting with a string + +The keys of the hashes are the command names. The value determine +how the command argument +is formatted. If the value begins with @samp{"}, the result is +enclosed in quotes @variable{$OPEN_QUOTE_SYMBOL} and +@variable{$CLOSE_QUOTE_SYMBOL}, with defaults +@samp{`} and @samp{'}. + +The command argument is allready formatted as @acronym{HTML}. +The remaining of the value text +(or the value text if there were no @samp{"}) is interpreted as follow: + +@itemize @bullet +@item +If the text is empty the argument of the command is left as is. +@item +If the text is a @samp{&} followed by a name, +like @samp{&function}, the name is considered to be a function name, +and this function is called to format the argument of the command. The +first argument of the function is the command name, the second is +the command argument. For example, if the value associated with the +(fictituous) command @code{@@foo} is @code{&my_func} +and we have: + +@example +sub my_func +@{ + my @@args = split /,\s*/ $_[1]; + return "$_[0]: $args[0]" if ($args[1] = 1); + return "$args[0]"; +@} +@end example + +The result of +@example +@@foo@{truc, 1@} +@@foo@{truc, bidule@} +@end example +will be +@example +foo: truc +truc +@end example +@item +If the text is a word, it is considered to be an @acronym{HTML} 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 @acronym{HTML} is @code{<elem>@var{arg}</elem>}. +Similarly @code{"quoted} leads to +@code{`<quoted>@var{arg}</quoted>'}. +@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. +Thus @code{elem class="elem"} leads to +@code{<elem class="elem">@var{arg}</elem>}. +@end itemize + +@node Define your own interface +@subsection Defining the style and indicatric commands interface + +If you don't like this scheme, it is possible to change how those 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 $style_stack +@var{$command} is the @@-command, @var{$style} is the value associated with +the @var{$command} in the @code{%style_map}, @code{%style_map_pre} +or @code{%style_map_texi} hashes. +The @var{$text} is the text appearing within the @@-command braces. +@var{args} is a reference on an array contening the command arguments +formatted according to the same conventions than with the reference hash style +(provided the value associated with the @@-command is a hash reference with a +@var{$arg} key as described in @ref{Reference hash args}). +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{$line_nr} +is an opaque structure containing the information about the line number of the +@@-command. It can be used to call @code{main::echo_error} or +@code{main::echo_warning} with first argument a message, and second argument +@code{$line_nr}. +@var{$state} +is a reference on a hash containing a lot of informations about the context +of the @@-command. +@var{$style_stack} +is a reference on an array containing the name of the @@-commands containing +the @@-command being formatted. + +@end deftypefn + +@c -------------------------------------------------------- +@node Anchors images and spaces +@section Formatting of special simple commands + +The formatting of special simple commands is controlled by functions. To +customize the output, the corresponding function references should be +redefined. All these functions return a formatted text. + +The formatting of anchors is controlled by @variable{$anchor}, but the function +associated with the function reference does more, it is usefull +to produce a reference target or link. +@deftypefn {Function Reference} $anchor anchor $identifier $href $text $attributes +If @var{$identifier} is not empty, this value should be used to create +a target for links (typically associated with a name or id +attribute in @acronym{HTML}). +The @var{$href} argument specifies a hpertextual reference which should be +used to link to a target. +In case 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. +It should be reasonable to assume that the attributes are for a @code{<a>} +@acronym{HTML} element. +@end deftypefn + +The formatting of @code{@@image} is controlled by: +@deftypefn {Function Reference} $image image $file_path $basename $preformatted $file_name +@var{$file_path} is the image file name with the path, @var{$basename} is the +alternate text or the file name without extension if no alternate text is +given. @var{$preformatted} is true if the image +appears in preformatted text. @var{$file_name} is the file name without path +but with extension. +@end deftypefn + +The formatting of @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 + +The formatting of @code{@@acronym} and @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 acronym argument with texinfo @@-commands, +@var{$acronym_text} is formatted. + +The other arguments are related with +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 previous @code{@@acronym} or as an arg of this +command, the other args are defined: @var{\@@explanation_lines} is a +reference on an array containing the unformatted explanation lines, +@var{$explanation_text} is the explanation text formatted, +@var{$explanation_simply_formatted} is the explanation with a light formatting, +unabling in @acronym{HTML} (or @acronym{XML}) the explanation to be in an +attribute. +@end deftypefn + +@c -------------------------------------------------------- +@node Text +@section Processing special characters in text + +Some characters are processed especially in text: @samp{---}, @samp{--}, +@samp{``} and @samp{''}. This is done only if in normal text and not in +some commands (@code{@@code}, @code{@@env}@dots{}). A function reference +is called to process those characters in text + +@deftypefn {Function Reference} $processed_text normal_text $text +The function processes @samp{---}, @samp{--}, @samp{``} and @samp{''} +in @var{$text} and returns @var{$processed_text}. The default is to +change @samp{---} to @samp{--}, @samp{--} to @samp{-}, and @samp{``} and +@samp{''} to @samp{"}. +@end deftypefn + +Some characters are special in @acronym{HTML} (@samp{&}, @samp{"}, +@samp{<} and @samp{>}) and should be protected. +This is done by the function associated with the function reference + +@deftypefn {Function Reference} $protected_text protect_text $text +The function processes the unprotected text @var{$text} and returns +the resulting protected text @var{$protected_text}. +@end deftypefn + +Empty lines are processed by the following function reference, which could +be usefull if empty lines are to be removed for example + +@deftypefn {Function Reference} $resulting_text empty_line $empty_line +This function processes an @var{$empty_line} and returns the resulting +text @var{$resulting_text}. Empty lines are left as is by default. +@end deftypefn + +@c -------------------------------------------------------- +@node Strings +@section Customizing strings written by @command{texi2html} + +@cindex i18n + +@command{texi2html} writes some strings in the generated document at +various places, at the page footers, on the help page, for special +section headings, buttons alt text and so on. These strings are +customizable. The string chosen depends on the language of the +document (set by @longopt{lang}, @variable{$LANG} or +@code{@@documentlanguage}). This is the basis for internationalization +as it allows for strings translations. + +The strings are found in a hash reference, @variable{$LANGUAGES}. +Each key is a language code. The associated value is also a hash +reference. The key is an english string and the associated value +is the string replacing the english string, if present. For example, +we have + +@example +$LANGUAGES->@{'fr'@} = @{ + ' Up ' => 'Plus haut', +@}; +@end example + +It means that whenever the string @samp{@ Up@ } is to be written +and the language is @samp{fr}, @samp{Plus haut} is written. It is possible +to customize the english strings by redefining the @samp{en} language hash. + +When a string contains a @samp{%} followed by @samp{@{} @var{name} @samp{@}} +it means that the string will be expanded by @command{texi2html}. For +example, if we have + +@example +$LANGUAGES->@{'fr'@} = @{ + 'See %@{node_file_href@}' => 'Voir %@{node_file_href@}', +@}; +@end example + +@samp{%@{node_file_href@}} will be expanded to an href for a node in a +file by @command{texi2html} in the string. A @samp{%%} will be expanded +as @samp{%}. + +For more on internationalization, see @ref{Internationalization}. + +@c -------------------------------------------------------- +@node References +@section References +@cindex reference + +@menu +* Reference to external manual:: +* Internal reference:: +@end menu + +@node Reference to external manual +@subsection Reference to external manual +@cindex external manual + +The references are produced with two function references, one for the +hypertextual reference construction, the other for the full reference to +external manual. + +@deftypefn {Function Reference} $href external_href $node $node_identifier $xml_node_identifier $manual_file_name +@var{$node} is the node name, with @@-commands. @var{$node_identifer} is the +node name mapped to an identifier acceptable as a file name. +@var{$xml_node_identifier} is the +node name mapped to an identifier acceptable as an @acronym{XML} identifier. +Those identifiers are built as explained in @ref{HTML Xref,,,texinfo}, +thus allowing for cross references to external manuals. @var{$file} is the +manual or file name of the external reference. This function should return an +href leading to the external manual. + +The default for this function is to make a reference compatible with +@command{makeinfo} (@pxref{HTML Xref,,,texinfo}). +@end deftypefn + +@deftypefn {Function Reference} $text external_ref $command $section $book $node_and_file $href $cross_ref_name +This function formats a reference to an external texinfo manual. +The @var{$command} is the ref command (@code{ref}, @code{xref} or +@code{pxref}, in text, at sentence beginning or in parenthesis). +The optionnal @var{$section} argument is the section in the book and + @var{book} is the book title. +@var{$node_and_file} is the node and file name formatted according to the +convention used in info: @samp{(file)node}. @var{$href} it an hypertextual +reference to the distant manual constructed using the above function. +@var{$cross_ref_name} is an optionnal cross +reference name appearing in the reference command. This function returns +the text corresponding with the external html manual reference. +This function returns the full formatted text of the external reference. +@end deftypefn + +@node Internal reference +@subsection Reference to an internal node + +A function reference is available for internal references. + +@deftypefn {Function Reference} $text internal_ref $command $href $short_name $name $is_section +This function formats a reference to a node in the current manual. +The @var{$command} is the ref command (@code{ref}, @code{xref} or +@code{pxref}, in text, at sentence beginning or in parenthesis). +@var{$href} it an hypertextual reference linking to the corresponding +node or section. @var{$short_name} and @var{$name} hold the text for the +reference but @var{$short_name} can be the node name which is assumed to +be shorter than the section name. +@var{$is_section} is a boolean true if the reference is a reference to a +section. This function returns the full formatted text of the internal +reference. +@end deftypefn + + +@c -------------------------------------------------------- +@node Alignement commands +@section Commands used for centering and flushing of text + +@cindex centering +@cindex flushing text +@cindex text alignement + +When a command controlling the alignement of text is used (@code{@@center}, +@code{@@flushleft} and @code{@@flushright}), the main program takes +care of opening and closing paragraphs. The alignement commands are the +key of the @variable{%paragraph_style} hash. +The value is used in the function doing the formatting of the paragraphs. +@xref{Paragraph and preformatted region}. + +A function references allows for a customization of the formatting of the text +appearing in the command block. + +@deftypefn {Function Reference} $result paragraph_style_command $command $text +@var{$command} is the command name, @var{$text} is the text appearing within +the command. This function returns a formatted text. +The default is to return the text unmodified. +@end deftypefn + +@c -------------------------------------------------------- +@node Paragraph and preformatted region +@section Formatting or not a paragraph or a preformatted region + + +@menu +* Paragraph and preformatted formatting:: +* Avoiding paragraphs:: +@end menu + +@node Paragraph and preformatted formatting +@subsection Paragraph and preformatted region formatting + +@cindex paragraph +@cindex preformatted region + +The formatting of a paragraph region or a preformatted region, is controlled +by function references: + +@deftypefn {Function Reference} $paragraph_text paragraph $text $alignement $formatting_command $formatting_command_formatted \$paragraph_number $format $item_number $enumerate_style $number +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. +@xref{Alignement commands}. + +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}. + +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 +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 (@xref{css}). @var{$region_name} is the +name of the command opening +the preformatted region (@code{example}@dots{}, see @ref{Complex formats}) +or a identifier for the preformatted context (for example +@code{menu-comment}, see @ref{Menus}). +The alignment commands are not taken into account, as the spaces are +preserved in preformatted regions, you should flush and center by hand. + +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}. + +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 + +@node Avoiding paragraphs +@subsection Avoiding paragraphs in formats + +@cindex Avoid paragraph opening + +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, @variable{%format_in_paragraph} with a true value. + +@c -------------------------------------------------------- +@node Complex formats +@section Formatting of complex formats (@code{@@example}, @code{@@display}@dots{}) + +@cindex complex format + +Here we see how a whole complex format is formatted. For the formatting +of the text, see @ref{Paragraph and preformatted region}. + +The formatting of the complex formats is ultimately controlled by a +function, however the default for this function uses a hash reference and +changing the hash reference values should be enough in most cases. This +hash reference is called @variable{$complex_format_map}. It has a key for each +of the complex format commands (@code{example}, @code{smallexample}, +@code{lisp}, @code{smalllisp}, @code{display}, @code{smalldisplay}, +@code{format}, @code{smallformat}). + +The associated value is also a reference on a hash. The keys are @code{begin} +and @code{end}. An eval of @code{begin} should lead to the beginning of the +formatted @acronym{HTML}, an eval of @code{end} should lead to the end of the +formatted @acronym{HTML}. 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 + +@c -------------------------------------------------------- +@node Lists tables +@section 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:: +* Whole table list:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Table and list items +@subsection 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 + +The default is to apply the command to the text item, however it is possible +to avoid it. +The hash @variable{%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}. + +@table @emph +@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 +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. +@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 $formatted_command +This function is used to format the text on the @code{@@item} line. +@var{$text_item} 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}. +@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{$formatted_command} is +this command formatted if it is a leading command, like @code{@@minus}. +@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 +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 +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. +@end deftypefn + +@deftypefn {Function Reference} $multitable_row row $text $item_command +This function is used to format a multitable row. @var{$text} is +the row text, with cells allready formatted with the @variable{$cell} +function reference. @var{$item_command} is the command used to introduce +the row, such that it is possible to distinguish between @code{@@item} and +@code{@@headitem}. +@end deftypefn +@end table + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Whole table list +@subsection Formatting of a whole table or list + +If the Texinfo command is a key of the @variable{%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, it is considered to be an @acronym{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 $command $text +@var{$command} is the Texinfo command name, @var{$text} is the formatted +items. +@end deftypefn + +If you still want to use @variable{%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 + +@c -------------------------------------------------------- +@node Definitions +@section Definition commands formatting + +The formatting of definition commands is controlled by a hash and four +functions. The 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:: +* Definition formatting:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Definition line +@subsection Customizing the interpretation of a definition line + +The keys of the hash @variable{%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 isn't 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} and @samp{arg}. + +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 + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Definition formatting +@subsection Customization of the definition formatting + +Four functions are used when formatting a definition command: + +@table @asis +@item category name +@deftypefn {Function Reference} $category definition_category $category_or_name $class $style +This function precise a category or an index entry name associating a class +@var{$class} (if given) with @var{$category_or_name}. The @var{$style} of the +definition may be @samp{f}, for function, @samp{v}, for variable or @samp{t}, +for type. +@end deftypefn +@item formatting of the definition line +@deftypefn {Function Reference} $line def_line $category $name $type $arguments $index_label +This function formats the definition line. @var{$category} is the category +formatted with @variable{$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}. +@end deftypefn + +@item definition text +@deftypefn {Function Reference} $definition_text def_item $text +This function formats the definition text, @var{$text}. +@end deftypefn + +@item the whole definition +@deftypefn {Function Reference} $definition def $text +This function formats the whole definition. The definition line and text +formatted by the above functions are in @var{$text}. +@end deftypefn + +@end table + +@c -------------------------------------------------------- +@node Headings +@section Customizing headings formatting + +A function controls the formatting of sectioning element headings, +with the corresponding function reference: +@deftypefn {Function Reference} $heading_text heading \%element_reference +The @var{\%element_reference} is a reference on a hash corresponding +with the sectioning element. The following keys are of interest: +@table @code +@item text +The heading text +@item name +The heading text without section number +@item node +true if the sectioning element is a node without associated structuring command +@item level +The level of the element in the document tree. @samp{0} is 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 +@end table +@end deftypefn + +@c -------------------------------------------------------- +@node Special regions +@section Formatting of special regions (@code{@@verbatim}, @code{@@cartouche}, @code{@@quotation}) + +Regions corresponding with raw text, like @code{@@verbatim}, @code{@@html} +or @code{@@tex} 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. +@end deftypefn + +If La@TeX{}2HTML is used, @code{@@tex} regions are handled differently, +from within the main program. + +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} 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 $style $text +@var{$style} is the first argument of the @code{@@quotation} if there are +two arguments. @var{$text} is the second argument or the first if there is +one argument. There are still @@-commands in these strings. 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 $quotation_text $argument_text $argument_style_texi $argument_style_id +@var{$quotation_text} is the quotation text, formatted, with the text +prepended by the function above. @var{$argument_text} is the second argument +of the @code{@@quotation} or the first if there is one argument, formatted. +The other arguments are defiend if there are two arguments for the +@code{@@quotation}, @var{$argument_style_texi} is this argument, with +@@-commands, and @var{$argument_style_id} is this argument transformed in +an identifier which can be used as an @acronym{XML} identifier. +@end deftypefn + + +@c -------------------------------------------------------- +@node Menus +@section Menu formatting + +To understand how the formatting of menus is controlled, the different +parts of a menu are first described, then how to control the formatting +of each of these parts. + +@menu +* Menu parts:: A menu consists in menu entry and menu + comments +* Menu formatting:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Menu parts +@subsection The structure of a menu + +In @command{texi2html}, a menu is considered to be composed of 2 parts, the +@dfn{menu entries} and the @dfn{menu comments}. 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 optionnal menu entry +name. + +A menu entry begins with @samp{*} at the beginning of the line. It begins +with the entry link, followed by the description. The description spans until +the next menu entry, or some text begining at the first character of a line +or an empty line, not contained within a command block which begun in the +description. An empty line or a line with text at the first character +starts a menu comment, which spans until the next menu entry. + +Here is an illustration of these rules: + +@example +@@menu +* node name: entry name. description begins + description continues +* another menu entry:: + description begins + description continues + + A menu comment, after an empty line + +* node:: description begins +A menu comment. The line starts at the first character + +* last entry:: description begins @emph{text +of the description, even if the line begins at the first character, +because we are in @@emph}. +@@end menu +@end example + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Menu formatting +@subsection The formatting of the different menu components + +In the default case, the name of the section corresponding with the +node is used instead of the node name. If @variable{$NODE_NAME_IN_MENU} is +true, however, node names are used. If @variable{$AVOID_MENU_REDUNDANCY} +is true and menu entry equal menu description the description isn't printed. +This is the default. Likewise, if node or section name equal entry name, +do not print entry name. + +A symbol, @variable{$MENU_SYMBOL} is put at the beginning of menu entries +when the node name is used. The default is @samp{•}. +If @variable{$UNNUMBERED_SYMBOL_IN_MENU} is true it is +also put at the beginning of unnumbered section names. This is not +done by default. + +The menu comments are considered to be preformatted text. The style +associated with this preformatted text is determined by +@variable{$MENU_PRE_STYLE}. Default is @samp{font-family: serif}. +The css class associated with menu comments is @code{menu-comments}. + +Three 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 +@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. The only key which could be +of interest is @code{preformatted}, true if the context is a preformatted +context. @xref{Three contexts}. +@var{$node} is the node name, @var{$name} is the +name of the node, and @var{$ending} is the text ending the link entry. +@end deftypefn + +@deftypefn {Function Reference} $description menu_description $description_text \%state +@var{$description_text} is the text of the menu description. @var{\%state} +should be used similarly than for the menu link. +@end deftypefn + +@deftypefn {Function Reference} $menu_comment menu_comment $text +@var{$text} is the text of the menu comment. It is in a preformatted +environment. +@end deftypefn + +The following function reference controls the formatting of a wole menu: + +@deftypefn {Function Reference} $menu menu $menu_components_text +@var{$menu_components_text} is the formatted menu components text, obtained +as explained above. +@end deftypefn + +The last function reference corresponds with a special case. It +is used when a menu entry appears within another block command, to +avoid the possibilities of invalid @acronym{HTML} production. +In that case the menu description and menu comments are not formatted +specially, but treated like normal text. +@deftypefn {Function Reference} $link simple_menu_link $link_text $href $node $name $ending +@var{$link_text} is the text corresponding with the link name, @var{$href} +is the link hypertextual reference. +@var{$node} is the node name, @var{$name} is the +name of the node, and @var{$ending} is the text ending the link entry. +@end deftypefn + +@c -------------------------------------------------------- +@node Indices +@section 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:: Index entries in the main document are + targets for hypertext references +* Index list:: Customizing the formatting of the index list +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Index entry place +@subsection Formatting of index entries + +Index entry places in the main text may be the target for hypertext +references. Their formatting +is controlled by the function associated with the following function +reference: + +@deftypefn {Function Reference} $target index_entry_label $identifier $preformatted +@var{$identifier} should be used to create +a target for links (typically associated with a name or id +attribute in @acronym{HTML}). +@var{$preformatted} is true if the index entry appeared in preformatted text. +@end deftypefn + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Index list +@subsection Customizing the formatting of index lists + +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 variable @variable{$SPLIT_INDEX} if set. The default is to split +indices after 100 entries. + +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} $letter summary_letter $letter $file $identifier +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. +@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 $section_href $section_heading +@var{$entry_href} is a reference to the place where the index entry +appeared, @var{$entry_text} is the corresponding text. @var{$section_href} +is a reference to the beginning of the sectioning element containing +the index entry, @var{$section_heading} is the heading of the element. +@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. @var{index_name} is the name of +the index, the argument of @code{@@printindex}. +@end deftypefn +@end table + +@c -------------------------------------------------------- +@node Floats and lists of floats +@section 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, +unformatted. +@item style_texi +The style with texi @@-commands. +@item style_id +The unique identifier associated with the style. +@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 id +The unique identifier associated with the label. Usefull to make an anchor +or a reference. +@item element +A reference on a structure representing the element the float appear in. +@end table + +@menu +* Floats:: Formatting of floats +* Lists of floats:: Formatting the lists of floats +@end menu + +@node Floats +@subsection 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 + +@node Lists of floats +@subsection 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 listoffloats_caption \%float +@var{\%float} is the structure described +above. This function reference returns a caption to be formatted in the +main program. +@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 + +@c -------------------------------------------------------- +@node Footnotes +@section Customizing the footnotes formatting + +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: in the main text the place where the footnote appear +and the footnote text. + +Two functions, with corresponding function references control the formatting +of the footnotes: + +@deftypefn {Function Reference} {(\@@lines $text_for_document)} foot_line_and_ref $number_in_doc $number_in_page $footnote_id $place_id $document_file $footnote_file \@@lines \%state +@var{$number_in_doc} is the footnote number in the whole document, +@var{$number_in_page} is the footnote number in the current page. +@var{$footnote_id} is an identifier for the footnote in the footnote text +which should be used to make target for references to that footnote, +while @var{$place_id} is an identifier for the location of the footnote +in the main document. Similarly, @var{$document_file} is the file name +of the file containing the text where the footnote appears in the main +document, while @var{$footnote_file} is the file name of the file where +the footnote text appears. + +@var{\@@lines} is a reference on an array containing the footnote text +lines, allready formatted. +And @var{\%state} holds informations about the context at the footnote +place in the main document. As usual the most usefull entry is +@code{preformatted} which is true if the footnote appears in a preformatted +context. + +This function returns a reference on an array, @var{\@@lines} containing +the updated footnote text for the footnote entry, and @var{$text_for_document}, +the text appearing at the footnote place in the main document, 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 of the footnotes page in case they are on a separated +page or section, @ref{Special pages layout}. For +the determination of the footnote locations, @ref{Page layout options}. + +@deffn {Function Reference} foot_section \@@footnotes_lines +This function formats a group of footnotes. @var{\@@footnotes_lines} is a +reference on an array holding the lines of all the footnote entries +formatted as explained above. This function modifies the reference. +@end deffn + +@c -------------------------------------------------------- + +@node Other and unknown commands +@section Customizing other commands, and unknown commands + +@c -------------------------------------------------------- +@c @node Skipped commands +@c @section Customizing ignored commands and text + +@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{texi2html} 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. + +Those special commands without braces are the key of a hash: +@variable{%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 texi +If true the arguments are considered to real texinfo, therefore + @code{@@value} and @code{@@macro} are expanded. +@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 isn't done. +@end table + + +Commands which don't appear in the hashes +@c @variable{%things_map} @variable{%pre_map} +@variable{%simple_map}, @variable{%simple_map_pre}, +@variable{%simple_map_texi} and @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 +@var{$command} is the @@-command, @var{$line} is the line following the +@var{$command}. @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{texi2html}. +@end deftypefn + +Commands with braces not specified above +nor in @variable{%style_map}, @variable{%style_map_pre} and +@variable{%style_map_texi} are processed +by the following function reference + +@deftypefn {Function Reference} {($result, $result_text, $message)} unknown_style $command $text +@var{$command} is the @@-command, @var{$text} is the text appearing within +the braces (allready formatted). @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{texi2html}. +@end deftypefn + + +@c -------------------------------------------------------- +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@c ======================================================== +@c ======================================================== + +@node Internationalization +@appendix Internationalization + +The strings written in the document are selected based on the +document language. This can be used to customize the strings, +as described in @ref{Strings}. This also enables translation of the +strings. + +@menu +* Translating strings:: +* Adding new strings:: +@end menu + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Translating strings +@appendixsec Translating strings + +@cindex Translation +@cindex i18n +@vindex $LANGUAGES +@vindex $T2H_OBSOLETE_STRINGS + +If the language is allready supported, then there will be a file +in the @file{i18n} directory with name the two-letter +ISO-639 language code. In that case you can enhance the translations by +editing this file. There is a @code{$LANGUAGES->@{'@var{language}'@}} +hash in that file. The keys are the english strings, in @code{''}, the +values (in @code{''} after @code{=>}) are the translations. +When a string contains a @samp{%} followed by @samp{@{} @var{name} @samp{@}} +it means that the string will be expanded by @command{texi2html}. For +an example, see @ref{Strings}. + +After that you should run the command @command{./manage_i18n.pl all} in +the top directory, it should merge your file with the existing files in +@file{translations.pl}, which is incorporated to the @file{texi2html} script +by @command{./configure}. + +If the language isn't currently supported, copy the @file{en} file in +@file{i18n} to a file with name the two-letter ISO-639 +language code of your language + and then add your translations to the strings. You could also add your +two-letter language code in the @file{manage_i18n.pl} file in the +@code{@@known_languages} array. + +After that you should similarly run the command +@command{./manage_i18n.pl all} in +the top directory. + +Obsoleted strings are not removed from the files, they are still present +in the @code{$T2H_OBSOLETE_STRINGS->@{'@var{language}'@}} hash in case +the string is reused later. + +If you made change to strings specified in installed files +(@pxref{Installation}) +you will have to reinstall them otherwise the installated files will +take precedence (@pxref{Using init files}). + +@c -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +@node Adding new strings +@appendixsec Adding new strings written to document + +@cindex internationalized strings +@cindex @command{manage_i18n.pl} + +If you need to write strings, for example the new string @var{a string} +to the resulting document, call @code{&$I('a string')}. Use simple quotes. +If you want to substitute a value in the string put +@code{%@{@var{string_value}@}}, in the string, and give a second argument +to @code{&$I}, a hash reference with key @var{string_value} and value +the what you want to substitute. +Here is an example: + +@example +return &$I('%@{name@} of %@{class@}', @{ 'name' => $name, 'class' => $class @}); +@end example + +In that case @code{%@{name@}} is substituted by @code{$name} in the translated +string. + +After that you should run the command @command{./manage_i18n.pl all} in the top +directory, it should add your new strings to all the files in the @file{i18n} +directory. + +@c -------------------------------------------------------- +@c commandline option index. +@node Indexop +@appendix Command Line Option Index +@printindex op +@c -------------------------------------------------------- +@node Indexvr +@appendix Variable Index +@printindex vr +@c -------------------------------------------------------- +@node Indexcp +@appendix Concept Index +@printindex cp +@bye |