From 06ea056d85ec0645fb1b94f537bed4b29688389a Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 3 Jan 2006 00:00:56 +0000 Subject: trunk/Master/texmf/doc/texi2html git-svn-id: svn://tug.org/texlive/trunk@43 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf/doc/texi2html/texi2html.html | 6072 +++++++++++++++++++++++++++++ 1 file changed, 6072 insertions(+) create mode 100644 Master/texmf/doc/texi2html/texi2html.html (limited to 'Master/texmf/doc') diff --git a/Master/texmf/doc/texi2html/texi2html.html b/Master/texmf/doc/texi2html/texi2html.html new file mode 100644 index 00000000000..d55c003b90f --- /dev/null +++ b/Master/texmf/doc/texi2html/texi2html.html @@ -0,0 +1,6072 @@ + + + + + + +Texi2HTML - Texinfo to HTML v1.76: Texi2HTML + + + + + + + + + + + + + + + + + + + +
[Top][Contents][Index][ ? ]
+

Texi2HTML

+

Copyright © 1999, 2000, 2001, 2002, 2003 + Free Software Foundation, Inc. +

+ + + + + + + + + + + + + + +

Portions of texi2html +

Copyright © 1999, 2000 Lionel Cons
+

Copyright © 1999, 2000 Karl Berry
+

Copyright © 1999, 2000 Olaf Bachmann
+

Copyright © 2002, 2003 Patrice Dumas
+

Copyright © 2001, 2002, 2003 Derek Price
+

Copyright © many others.
+

+
+

Portions of this manual +

Copyright © 1999, 2000 Karl Heinz Marbaise (manual)
+

Copyright © 2003 Patrice Dumas (manual)
+

Copyright © 2003 Derek Price (manual)
+

+ +

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

+

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

+ + + + + + + +

This manual, last updated 1 February 2005, describes version 1.76 +of the texi2html Perl script which converts +Texinfo into HTML. +

+

Please send bug reports concerning this manual to the Texi2HTML user +discussion list user@texi2html.cvshome.org. Please state the exact +version of the manual which contains the bug, as given above. +

+ +
 
This manual is currently under construction and of course incomplete.  ;-)
+
+ + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1. Overview

+ + +

Texinfo is the official +documentation format of the 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 +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 HTML, especially +considering that there is so much Texinfo documentation in +the world. +

+

Some time ago makeinfo wasn't able to produce +HTML output format, but people still wanted documentation in +HTML. This was the birthing hour for +texi2html. The basic purpose of texi2html +is to convert Texinfo documents into HTML. +

+

Since then, HTML support in makeinfo has improved, but +texi2html is still stronger in many areas, including the degree to +which it allows customization. With texi2html, some important +aspects of the resulting 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 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 texi2html is capable of +producing, have a look at the following sites: +the Singular Manual, +the Cederqvist (CVS Manual). +

+ + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

1.1 Why texi2html and not makeinfo?

+ + +

You would like to produce HTML files from your existing Texinfo +files? There are two programs you can use to do this. The first is +makeinfo (see (texinfo)Generating HTML). +The second is texi2html. +

+

The design goal of makeinfo's HTML output was to produce +readable HTML output. It is now possible to use CSS +for HTML customization. Another possibility is to use intermediate +formats, like docbook or mekeinfo XML +and XSL stylesheets to customize the resulting document. Still the +output produced by makeinfo isn't customizable. +

+

The current development of texi2html tries to +provide for producing the more interesting and sophisticated HTML +pages that today's Internet users have come to expect. +The goal behind texi2html is to generate attractive HTML by +default but also to allow users considerable freedom to affect the final +style and design of the output HTML pages. This is achieved via +command line options and flexible configuration files. +

+ +

In contrast to the HTML produced by makeinfo --html (the +makeinfo program is part of the Texinfo distribution), the +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 HTML +formatting, provides for splitting documents at various levels, and provides +for using the latex2html program to convert @tex sections of +the Texinfo source. +

+

The focus on HTML is still present but with the help of the +customization files it is now possible to use texi2html to +produce other formats as well. texi2html may for example be +turned into a texinfo to roff translator with the help of a customization file +provided with the distribution. +

+

texi2html should reasonably convert all Texinfo +4.8 constructs. If you find it does not, please send a bug report to the +users@texi2html.cvshome.org email list. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

2. Obtaining texi2html

+ +

The latest version of the source code for texi2html should be +available from texi2html.cvshome.org. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

3. Installation of texi2html

+ +

To install texi2html, you must first obtain a copy of the +source distribution. See section Obtaining texi2html. +

+

texi2html also requires perl version +5.004 or above. The current version has not been tested +extensively on versions of perl below 5.6, however. +

+

texi2html is a standard Automake-based distribution. +If you have a source version, you should run ./configure +to regenerate the executable `texi2html' file. ./configure +accepts options to select the installation directory for the `texi2html' +file, the default directories texi2html will use to look for +configuration files, and other details. Run ./configure --help for +more information. +

+

Running ./configure combines four files into the final +`texi2html' program file: +

+ +

Running ./configure also builds the make configuration +files (`Makefile's). To make the documentation run make. +

+

make install performs the installation to the locations specified to +the ./configure script. This usually involves placing the actual +`texi2html' file someplace in your path, such as `/usr/local/bin' or +`/usr/bin'. +

+

Installing texi2html in your path should be sufficient +to run it. To use default initialization files, or a configuration file for +LaTeX2HTML when using latex2html to convert @tex sections +(see section Expanding @tex and @math regions using LaTeX2HTML), install them in the package data directory +specified to configure. This is `/usr/local/share/texi2html/' by default, +but depends on the value of the +`--pkgdatadir=dir' option passed to +the ./configure script. Files used for strings customization and +internationalization are also searched for in the `i18n' directory +of this directory. See section Use initialization files for fine tuning for more. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4. Invoking texi2html

+ +

To produce an HTML manual, run texi2html with a Texinfo +file as an argument. For example, this manual is created with: +

+
 
$ texi2html texi2html.texi
+
+

The behaviour of texi2html may be changed with command line +options. These command line options are always associated with corresponding +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 `no' or `no-' to the switch name. For example + +`--nomenu' does the reverse of +`--menu'. +

+ + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.1 Specifying where to split the generated document

+ +

The HTML manual resulting from the processing of the Texinfo source +may be split into files at different levels. This is specified with the +option +`--split' which takes an argument, namely the level of splitting +(variable: +$SPLIT). This level may be: +

+
+
`chapter'
+

The document is split at @chapter, @appendix, or @unnumbered. +

+
`section'
+

The document is split at the same places as it is using the `chapter' +argument, and also at @section, @appendixsec or +@unnumberedsec. +

+
`node'
+

The document is split at every sectioning command. It is not necessarily +split at each node, if the @node structure doesn't correspond with +the sectioning command structure (see below). +

+
`none'
+

The document isn't split. This is the default. +

+
+ +

There are two kinds of commands which may be used to define sectioning +elements in Texinfo: @node and the structuring commands (@top, +@section, @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 @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 +`--use-nodes' option (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 texi2dvi behaviour, which ignores +@node commands for the purprose of sectioning, while the second +looks like makeinfo behaviour (see (texinfo)Two Paths). +

+

As an illustration, the following table shows how a sample Texinfo document is +divided into sectioning elements when +`--use-nodes' is used and not: +

+ + + +

Texinfo code +

+ +

default case +

+ +

with +`--use-nodes' +

+
+
+
 
@node node1
+@chapter node 1
+node1 text
+
+@node node2
+node2 text
+
+@node node3
+node3 text
+@chapter node 3
+chapter text
+
+ +

first element: +

+
 
@node node1
+@chapter node 1
+node1 text
+
+@node node2
+node2 text
+
+

second element: +

+
 
@node node3
+node3 text
+@chapter node 3
+chapter text
+
+
+ +

first element: +

+
 
@node node1
+@chapter node 1
+node1 text
+
+

second element: +

+
 
@node node2
+node2 text
+
+

third element: +

+
 
@node node3
+node3 text
+@chapter node 3
+chapter text
+
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.2 Setting output file and directory names

+ +

The manual name is constructed by stripping the `.texi', +`.txi', `.texinfo', or `.txinfo' extension from the Texinfo file +name. +

+

By default, texi2html generates the manual file in the current +directory if the manual isn't split. A `.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 +(`toc' for table of contents, `abt' for about, `ovr' for +overview) appended. Lastly, an `.html' file extension is appended. +

+

Thus, if the texinfo file `afile.texi' is processed and split at chapters +into 3 files, the generated files (in directory `afile') will be: +

+
 
afile.html         --> @node Top or @top section
+afile_1.html       --> Chapter 1
+afile_2.html       --> Chapter 2
+afile_toc.html     --> Table of Contents
+afile_abt.html     --> About Page
+
+

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 + +`--output' command line option (variable +$OUT). If the output +is split, and +`--output' is set, the files are placed in the directory +specified by the argument to the option. +

+

The basename may be overridden with +`--prefix' (variable + +$PREFIX). If +`--short-ext' is given, `.htm' is appended +instead of `.html' in the final step (variable +$SHORTEXTN). +The +`--top-file' option +overrides the top element file name (variable +$TOP_FILE). This can +be used to name the top element file `index.html'. Similarly, + +`--toc-file' changes the name of the table of contents file (variable + +$TOC_FILE). +

+

Reusing the example above, but this time calling texi2html like so: +

+
 
$ texi2html -split chapter -prefix manual -short-ext -top-file index.htm -toc-file contents.htm afile.texi
+
+

we get, in `manual': +

+
 
index.htm          --> @node Top or @top section
+manual_1.htm       --> Chapter 1
+manual_2.htm       --> Chapter 2
+contents.htm       --> Table of Contents
+manual_abt.htm     --> About Page
+
+

The file names generated by texi2html differ from those generated +by makeinfo. makeinfo uses the node name to construct +the file names while splitting at nodes. It is possible to get the same +behaviour out of texi2html by specifying the + +`--node-files' option (variable +$NODE_FILES). If the output +isn't split at nodes, 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. +This trick enables the generated HTML manual to be a +target for the cross-references of other manuals generated by +makeinfo or texi2html. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.3 Specifying which regions get expanded

+ +

The default for texi2html is to expand the @ifhtml, +@html, and @menu regions, all the @ifnot regions +except @ifnothtml, and no other @if regions. +

+

It is possible to expand other regions by setting +`--if<region>', +where `<region>' is replaced by the literal name of the region (for +example, `--iftex'). Symetrically, if +`--no-if<region>' is +specified, the `<region>' region is ignored. The configuration file +array, +@EXPAND, holds the names of regions which should be +expanded. The only region name present in @EXPAND in the default case +is `html'. +

+

If +`--nomenu' is set, the @menu sections are not expanded +(variable +$SHOW_MENU). The default is to expand @menu +sections. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.4 Command line options related to Texinfo language features

+ +

Miscalleneous Texinfo related things may be specified via command line options. +

+
+
+

`--lang=lang' +

+

Sets the document language similar to the Texinfo directive, +@documentlanguage lang (variable +$LANG). +The default is `en', that is, use the english language strings. +

+
+

`-Dvar' +

+

Sets var. Equivalent to, @set var 1, in Texinfo. +

+
+

`-Uvar' +

+

Clears var. Equivalent to, @clear var, in Texinfo. +

+
+

`-Pdir' +

+

Prepend dir to the list of directories to search for +@include files (the associated array is +@PREPEND_DIRS, +empty in the default case). +

+
+

`-Idir' +

+

Append dir to the list of directories to search for +@include files (the associated array is +@INCLUDE_DIRS, +empty in the default case). +

+
+ +

The include files are always searched for in the current directory. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.5 Page layout related command line options

+ +

If the +`--frames' option is specified, 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 +$FRAMES). The default is not +to use frames. +

+

It is also possible to suppress the section navigation panel with + +`--nosec-nav' (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 + +`--separated-footnotes' (variable +$SEPARATED_FOOTNOTES). +The default is to have separated footnotes. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.6 Customizing the HTML and text style

+ +

Miscalleneous style changes may be achieved with command line options. +

+
+
+

`--doctype=DTD' +

+
+

`--frameset-doctype=DTD' +

+

You can specify the document DTD by setting these options. + +`--frameset-doctype' applies to the file describing the frames when +frames are used (corresponding variables are +$DOCTYPE and + +$FRAMESET_DOCTYPE). +

+

The default for the document doctype is: +

 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
+

And for the frameset doctype: +

 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html401/frameset.dtd">
+
+
+
+

`--iso' +

+

If this option is set, ISO8859 entities are used for some special symbols, +like Copyright © (variable +$USE_ISO). It is the default. +

+
+
+

`--css-include=file' +

+

This command line switch provides for the inclusion of an external +Cascading Style Sheet (CSS) file. More than one file may be +specified, and `-' stands for the standard input (array + +@CSS_FILES). +

+

The option use is the same than for makeinfo and is described +extensively in (texinfo)HTML CSS. +Briefly, the CSS @import lines from the external file +CSS file are pasted before the +texi2html CSS rules, and the external file CSS +rules are pasted after the texi2html CSS rules. +

+
+
+

`--html-xref-prefix=path' +

+

This option sets the base directory for external HTML texinfo manuals +(variable +$EXTERNAL_DIR). Defaults to `../'. +

+
+
+

`--def-table' +

+

If this option is set, HTML tables are used to format definition +commands, rather than HTML definition tables (variable + +$DEF_TABLE). Default is false. +

+
+
+

`--short-ref' +

+

If this option is set, cross-references are given without section numbers +(variable +$SHORT_REF). Default is false. +

+
+
+

`--number' +

+

If this option is set, sections are numbered (variable + +$NUMBER_SECTIONS). This is the default. +

+
+
+

`--toc-links' +

+

If this option is set, links from headings to TOC entries are +created (variable +$TOC_LINKS). Default is false. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.7 Expanding @tex and @math regions using LaTeX2HTML

+ +

It is possible to use LaTeX2HTML +to process @tex regions and @math{} commands. This is an +attractive way to display mathematical constructs in the HTML +manual. The +`--l2h' option activates this feature (variable +$L2H). It is usually desirable to expand @tex sections when this +option is specified (see section Specifying which regions get expanded). The default is not to use this +feature. +

+

The +`--l2h-l2h=program' option enables changing the name/location +of the LaTeX2HTML program processing TeX regions (variable + +$L2H_L2H). The default is latex2html. +

+ +

`--l2h-tmp' sets the directory used for temporary +files, this name shouldn't contain a dot `.' +(variable is +$L2H_TMP). Defaults to the current dir. +

+

The file specified by +`--l2h-file' is +used as LaTeX2HTML init file. It is searched at the same places than +init files (see section Use initialization files for fine tuning), and the default is `l2h.init'. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

4.8 Use initialization files for fine tuning

+ + +

Initialization variables are read first from +`/usr/local/share/texi2html/Config' (the exact location being +changeable with the +`--pkgdatadir=dir' option of the +configure script, see Installation of texi2html), +`/usr/local/etc/texi2html/Config' (the exact location being +changeable with the +`--sysconfdir=dir' option of the +configure script, see Installation of texi2html), from `./Config' +then from `$HOME/.texi2html/Config'. Any command-line option +can override the corresponding option set in init file, and the +option +`--init-file' specifies an init file to be loaded, with +later settings overriding earlier ones. +

+

The init files specified with +`--init-file' are searched +first in the current directory, then in the `$HOME/.texi2html/' +directory, in the `/usr/local/etc/texi2html/' directory and lastly +in the `/usr/local/share/texi2html/' directory. +

+

A file is also included based on the language selected, +by +$LANG, +`--lang' or @documentlanguage. +If no language was selected `en' is considered to be +the language. All the files with name the language name in +`/usr/local/share/texi2html/i18n/', +`/usr/local/etc/texi2html/i18n/', +`$HOME/.texi2html/i18n/' and then `./i18n/' are included. +

+

The default initialization options are defined in the +`texi2html.init' file contained in the texi2html +distribution (which gets included near the beginning of the +texi2html script that gets installed). +

+

To customize texi2html it is best if you copy the +appropriate sections from the `texi2html.init' +contents into an appropriate local initialization file, +make the necessary changes there, and then have +texi2html read this initialization file by one of +the means described above. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

5. Overview of initialization files content and loading

+ +

The initialization files are perl files, read as explained +in Use initialization files for fine tuning. You don't need to know much of 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 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 HTML manual. You should be able to change the value of some +normal variables without a deep knowledge of perl, by looking +at the existing examples. The possible mistakes in that case could be +omitted `;', and bad quoting. +

+

Initialization file are loaded from the main program by +the mean of a require, while in the 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 +our specifier, such that it should be possible to use the +use strict pragma in the initialization file code. +

+

To avoid messing with the variables in the main namespace +all the global variables which could be of use in the init files +are in the Texi2HTML namespace. Notice that the functions +of the main program are still in the main namespace. +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

5.1 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 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 +$anchor. Thus if you want to override the +corresponding function +you could write: +

+
 
# 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
+}
+
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

5.2 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 \@array for a reference on an array and similarly +\%hash for a reference on a hash. +

+

Thus, the prototype for the function associated with the function +reference `$formatting_function' will be: +

+
+
Function Reference: $text formatting_function $arg1 \@arg2 + +
+

formatting_function takes as first argument $arg2, +as second argument a reference on an array \@arg2 +and returns the formatted text $text. +

+ +

To redefined the corresponding function, you should write: +

+
 
$formatting_function = \&my_formatting_function
+
+sub my_formatting_function($ $)
+{
+    my $arg1 = shift;
+    my $arg2 = shift;
+    # prepare $formatted_text
+    .....
+    return $formatted_text
+}
+
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6. 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 +Page layout related command line options. +Fine tuning of the page layout may be achieved +with redefinition of other variables and function references in the +initialization files. +

+ + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.1 The different categories of pages and sectioning elements

+ +

The following sectioning elements can be associated with pages: +

+
+
Normal elements
+

These are normal sections or nodes. Their association with pages is +determined by the splitting of the document. See section Specifying where to split the generated document. +

+
Top element
+

The top element is the higher element in the document structure. +If there is a @top section it is the element associated with +that section. Otherwise it is the element associated with the +@node Top. If there is no @node Top the first element is the +top element. +

+

The top element is formatted differently than a normal element if there +is a @top section or the @node Top isn't associated +with a sectioning command. +

+
Misc elements
+

These elements are associated with pages if the document is split. +There are four misc elements: +

    +
  1. Table of contents +
  2. Short table of contents, also called Overview +
  3. Footnotes page +
  4. About page +
+ +

The About page shouldn't be present for documents consisting +in only one sectioning element. The Footnote page should only +be present if the footnotes appear on a separated page +(see section Page layout related command line options), however a footnote element is present if +the document isn't split. The Table of contents should only +be formatted if @contents is present in the document. +Similarly the Overview should only appear if @shortcontents +or @summarycontents is present. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.2 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 +$SMALL_RULE, + +$DEFAULT_RULE, +$MIDDLE_RULE and +$BIG_RULE +for rules of different sizes. +The defaults are +

 
$SMALL_RULE = '<hr size="1">';
+$DEFAULT_RULE = '<hr>';
+$MIDDLE_RULE = '<hr size="2">';
+$BIG_RULE = '<hr size="6">';
+
+ +

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

+ +

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 (@chapter, +@unnumbered…) or by the nodes (in that case the node +directions are specified on node line or in menu organization). +These items are called element labels. They may be associated with +a button (see section Specifying the buttons formatting), and used in the formatting functions +(see section Main program variables and usefull functions). +

+

Here is the list: +

+
+
` '
+

An empty button +

+
Top
+

Top element. The associated name is +$TOP_HEADING if that variable is +defined. This variable is not set by default. +

+
Contents
+

Table of contents +

+
About
+

About (help) page +

+
Overview
+

Overview, short table of contents +

+
First
+

First element in reading order +

+
Last
+

Last element in reading order +

+
Index
+

The first chapter with @printindex. The associated name +is +$INDEX_CHAPTER, if the variable is set. This variable is not set +by default. +

+
This
+

The current element +

+
Back
+

Preceding element in reading order +

+
FastBack
+

Beginning of this chapter or previous chapter if the element is a chapter +

+
Prev
+

Previous section on the same level +

+
NodePrev
+

Previous node +

+
Forward
+

Next element in reading order +

+
FastForward
+

Next chapter +

+
Next
+

Next section on the same level +

+
NodeNext
+

Next node +

+
Following
+

Next node in node reading order +

+
Up
+

Up section +

+
NodeUp
+

Up node +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.3 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. +

+ + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.3.1 Controlling the navigation panel panel at a high level

+ +

The global formatting of the navigation panels may be +changed with the following variables: +

+
+
$VERTICAL_HEAD_NAVIGATION + +
+

A vertical navigation panel will be used for the header navigation +panel if this variable is true. +

+
$ICONS + +
+

Icons are used instead of +textual buttons if this variable is true. +

+
$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 (see section Page layout related command line options). +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.3.2 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: +

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

+
@SECTION_FOOTER_BUTTONS + +
+
@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 +$WORDS_IN_PAGE is set and the output is split at nodes, these +buttons are only present if there are more than +$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. +

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

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

+
+ +

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

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

+
reference on a scalar
+

The scalar value is printed. For some possibly +usefull scalars, Accessing elements informations. +

+
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 +

 
[ 'Next', \$Texi2HTML::NODE{Next} ] 
+
+

The button will be a link to the next section with text + +$Texi2HTML::NODE{Next}. +

+
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 +%NAVIGATION_TEXT hash, surrounded +by `[' and `]'. If the element label is ` ', there is +no `[' and `]'. +The element of the %NAVIGATION_TEXT hash are defined +dynamically, in the init_out function reference +(see section Preparing the output). +

+

If icons are used, the button is an image with file determined by +the value associated with the element label in the +%ACTIVE_ICONS +hash if the the link really leads to an element, or in the +%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. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.3.3 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: +

+
+
Function Reference: print_navigation $filehandle \@buttons $vertical + +
+

$filehandle is the opened filehandle the function should write to. +\@buttons is an array reference which should hold the specification of +the buttons for that navigation panel. $vertical is true if the +navigation panel should be vertical. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.4 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. +

+ + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.4.1 Accessing elements informations

+ +

Four hashes are available, with key the elements labels (as described +in Element labels) and values: +

+
+
%Texi2HTML::NAME + +
+

The formatted element name +

+
%Texi2HTML::HREF + +
+

The element hypertext reference +

+
%Texi2HTML::NODE + +
+

The element node name +

+
%Texi2HTML::NO_TEXI + +
+

The element name after removal of texi commands +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.4.2 Accessing global informations

+ +

Three kinds of global informations are available, miscalleneous global +strings, flags set by @set and special flags and section lines. +

+ +

Global strings

+

The +%Texi2HTML::THISDOC hash holds some global informations: +

+
+
fulltitle
+

title set by @title. If there is no @title other +possibilities are tried (@settitle, @shorttitlepage…). +

+
title
+

title set by @settitle, or fulltitle. +

+
title_no_texi
+

title without texi formatting +

+
title_texi
+

title with texi commands +

+
author
+

Authors list set by @author. +

+
authors
+

A reference on an array containing each author set by @author. +

+
copying
+

Text appearing in @copying with all the texinfo commands removed, +put in comments. +

+
program
+

The name and version of texi2html. +

+
program_homepage
+

Homepage for texi2html. +

+
program_authors
+

Authors of texi2html. +

+
file_base_name
+

base name of the texinfo manual file. +

+
destination_directory
+

Destination directory for the resulting files. +

+
toc_file
+

The file name of the table of contents. +

+
today
+

The date. +

+
+ +

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

+ + +

Flags

+

Flags defined by @set may be accessed through the + +%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 @setfilename, or @settitle, +@author… The corresponding flag is the command name with +`_' appended, for example, _titlefont corresponds with +@titlefont. Like other flags they are available in + +%main::value. +

+ + +

Section lines

+ +

The following array references or arrays holds formatted lines: +

+
+
$Texi2HTML::THIS_SECTION + +
+

Lines of the current element. +

+
$Texi2HTML::THIS_HEADER + +
+

Lines of the current element appearing before the element label (anchors). +

+
$Texi2HTML::OVERVIEW + +
+

Lines of short table of contents. See section Special pages formatting. +

+
$Texi2HTML::TOC_LINES + +
+

Lines of table of contents. See section Special pages formatting. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.4.3 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. +

+
+
Function: $words_number main::print_lines $filehandle \@lines_array + +
+

$filehandle is the opened filehandle the function should write to. +\@lines_array is the array line the function should write to the file. +If this argument is omitted, the function uses +$Texi2HTML::THIS_SECTION. +$words_number is the number of words in the array, only defined if +split at nodes and +$WORDS_IN_PAGE is defined. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.5 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 @set or @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: +

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

+ +

In the default case the +$BODYTEXT (see section Customizing the page header) +and the hashes +%NAVIGATION_TEXT (see section Specifying the buttons formatting) and + +%BUTTONS_GOTO (see section Formatting of 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) : +

+
 
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'} = ' &gt; ';
+   return $encoding;
+}
+
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.6 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: +

+
+
Function Reference: finish_out + +
+

This function is called after the document generation. +

+ +

The default is to do nothing. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.7 Customizing the texi2html css lines

+ +

It is possible to modify the texi2html css lines by modifying +the entries or adding to the +%css_map hash. Each key is a css +selector, the corresponding value is a style string. +

+

The whole css text is in the variable +$CSS_LINES. If this +variable is defined the variable value is used instead of being +constructed using the +%css_map entries. For example if you don't +want any css entries, set +

+
 
$CSS_LINES = '';
+
+

It is also possible to change completely the way +$CSS_LINES are +generated by redefining the following function reference: +

+ +
+
Function Reference: css_lines \@import_lines \@rule_lines + +
+

This function should be used to construct the +$CSS_LINES. +\@import_lines are the @import lines of the +files specified with +`--include-css', +and \@rule_lines are the css commands lines of these files. +See section Customizing the HTML and text style. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.8 Customizing the page header

+ +

It is possible to add lines to the text within the <head> +HTML elements, by defining the variable +$EXTRA_HEAD. +Similarly it is possible to add text just after the <body> +element with the variable +$AFTER_BODY_OPEN. +These variables are empty by default. +

+

The encoding of the texinfo file is defined by +$DOCUMENT_ENCODING +if no @documentencoding appears in the document. +The default is a `en-ascii' encoding. +The encoding of the resulting document is defined by + +$ENCODING. The default is the $DOCUMENT_ENCODING. +

+

The description of the document may be specified in + +$DOCUMENT_DESCRIPTION. If this variable is undef, the text +associated with @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 <body> element attributes may be set by defining the +variable +$BODYTEXT. If you want to define that variable +dynamically, you should use the init_out function reference +(see section Preparing the output). +

+

The default functions call the function associated with + +$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. +

+
+
Function Reference: print_head_navigation $filehandle \@buttons + +
+

$filehandle is the opened filehandle the function should write to. +\@buttons is an array reference which should hold the specification of +the buttons for the navigation panel. +

+ +

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 +$print_page_head is called for all the pages, and after that, +the function associated with +$print_chapter_header is called +if the document is split at chapters, or the function associated with + +$print_section_header is called if the document is split at sections. +

+
+
Function Reference: print_page_head $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function should print the page head, including the <body> +element. +

+ +
+
Function Reference: print_chapter_header $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function is called if the document is split at chapters, after +print_page_head. +

+ +
+
Function Reference: print_section_header $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function is called if the document is split at sections, after +print_page_head. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.9 Customizing the sections

+ +

The functions associated with the following function references are used for +the formatting of sections: +

+
+
Function Reference: print_section $filehandle $first_in_page $previous_is_top + +
+

$filehandle is the opened filehandle the function should write to. +$first_in_page is true if this section is the first section in the page. +$previous_is_top is true if this section is the section following the +Top section. +This function should print the current section. +

+ +
+
Function Reference: end_section $filehandle $last_element_or_before_top + +
+

$filehandle is the opened filehandle the function should write to. +$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. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.10 Customizing the page footer

+ +

It is possible to add text just before the </body> +element with the variable +$PRE_BODY_CLOSE. Nothing is added +by default. +

+ +

The default functions call the function associated with + +$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. +

+
+
Function Reference: print_foot_navigation $filehandle \@buttons + +
+

$filehandle is the opened filehandle the function should write to. +\@buttons is an array reference which should hold the specification of +the buttons for the navigation panel. +

+ +

If you want even more control, you can have full control the page footer +formatting by redefining three function references. +The function associated with +$print_chapter_footer is called +if the document is split at chapters, or the function associated with + +$print_section_footer is called if the document is split at sections. + After that the function associated +with +$print_page_foot is called. +

+
+
Function Reference: print_page_foot $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function should print the page foot, including the </body> +element. +

+ +
+
Function Reference: print_chapter_footer $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function is called if the document is split at chapters, before +print_page_foot. +

+ +
+
Function Reference: print_section_footer $filehandle + +
+

$filehandle is the opened filehandle the function should write to. +This function is called if the document is split at sections, before +print_page_foot. +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11 Special pages formatting

+ +

For the special elements, two things must be formatted: the content +and the page layout +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.1 Customizing the content of the special pages

+ + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.1.1 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: +

+
+
Function Reference: print_Top_header $filehandle $begin_page + +
+

$filehandle is the opened filehandle the function should write to. +$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. +

+ +
+
Function Reference: print_Top $filehandle $has_top_heading + +
+

$filehandle is the opened filehandle the function should write to. +$has_top_heading is true if there is a @heading command or +@titlefont command appearing in the Top element text. +This function should be used to format the Top element text and navigation +panel. +

+ +
+
Function Reference: print_Top_footer $filehandle $end_page + +
+

$filehandle is the opened filehandle the function should write to. +$end_page is true if the element is the last in a page. +This function should end the Top element. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.1.2 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: +

+
+
$DO_CONTENTS + +
+

If the variable is true a table of contents is done even if there is no +@contents command. +

+
$DO_SCONTENTS + +
+

If the variable is true a short table of contents is done even if there is no +@summarycontents command. +

+
$BEFORE_OVERVIEW + +
+

The variable value is inserted before the short table of contents text. +

+
$AFTER_OVERVIEW + +
+

The variable value is inserted after the short table of contents text. +

+
$BEFORE_TOC_LINES + +
+

The variable value is inserted before the table of contents text. +

+
$AFTER_TOC_LINES + +
+

The variable value is inserted after the table of contents text. +

+
$TOC_LIST_STYLE + +
+

This should contain a css style used for the list style if the tables of +content are formatted with a list. +

+
$TOC_LIST_ATTRIBUTE + +
+

This should contain an attribute text used for the list element if the tables of +content are formatted with a list. +

+
+ +

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

+
+
Function Reference: toc_body \@elements + +
+

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

+
+
top
+

true if the element is the top element, +

+
index_page
+

true if the element is an index page added because of index splitting, +

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

+
tocid
+

label used for reference linking to the element in table of +contents, +

+
file
+

the file containing the element, usefull to do href to that file +in case the document is split, +

+
text
+

text of the element, with section number, +

+
name
+

text of the element, without section number. +

+
+ +

This function doesn't return anything but should fill the array corresponding +with the + +$Texi2HTML::TOC_LINES and + +$Texi2HTML::OVERVIEW references with the table of contents and short +table of contents. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.1.3 Formatting of footnotes text

+ +

The footnotes text is allready formatting when @footnote commands +are expanded. See section Customizing the footnotes formatting. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.1.4 Formatting of about text

+ +

The default about element contains an explaination of the buttons used +in the document (@SECTION_BUTTONS, Specifying the buttons formatting) and +an example locating the buttons targets in an example. +The formatting of this text may be influenced by the following +hashes and variables: +

+
+
$PRE_ABOUT
+
$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. +

+
%BUTTONS_GOTO
+
+

The keys of this hash are element labels (see 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 init_out function reference +(see section Preparing the output). +

+ +
+
%BUTTONS_EXAMPLE
+
+

The keys of this hash are element labels (see Element labels). The value +is the text associated with the element label in the about example, +typically a section number. +

+
+
+ +

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

+
+
Function Reference: $about_text print_about + +
+

This function should return the about text. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.11.2 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: +

+
+
print_Top + +
+
print_Top_header + +
+
print_Top_footer + +
+

Formatting of top element page or section. It is also used for the formatting +of the top element text (see section Top element text formatting). +

+
print_Toc + +
+

Formatting of table of contents page or section +

+
print_Overview + +
+

Formatting of short table of contents page or section +

+
print_About + +
+

Formatting of about (help) page or section +

+
print_Footnotes + +
+

Formatting of footnotes section or page in case footnotes are on a +separated page or the document isn't split. +

+
+ +

In the default case, +$print_Top calls +$print_Top_header for +the header and +$print_Top_footer for the footer of top element. +All the other function call +$print_misc which in turn calls + +$print_misc_header for the headers and +$print_misc_footer +for the footers. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.12 Customizing the file names

+ +

It is possible to specify the file names with more control than with the +command line options (see section Setting output file and directory names). +First the extension may be overrided by the variable +$EXTENSION +value. +Two function references enable +further customization. One is usefull in case +$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. +

+
+
Function Reference: ($node_file $redirection_node_file) node_file_name $node + +
+

$node is a hash reference with the following interesting keys (there +are much more keys): +

+
texi
+

The texinfo node name. +

+
with_section
+

True if associated with a section. +

+
+

The result is the node file name $node_file, and the file containing +a redirection to the node $redirection_node_file. +

+ +

The other is usefull if $NODE_FILES isn't true. It is used to +customize the file associated with each element. +

+
Function Reference: $file element_file_name $element $is_top $docu_name + +
+

$element is a hash reference with the following interesting keys (there +are much more keys): +

+
texi
+

The texinfo element name. +

+
number
+

The number associated with a section. +

+
doc_nr
+

A number incremented whenever a new file should begin, based on how the +document is split (see section Specifying where to split the generated document). +

+
text
+

The element text. +

+
name
+

The element text without section number. +

+
+

$is_top is true if the element is considered as the top element. +$docu_name is the basename of the texinfo manual. +The result is the element file name. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

6.13 Generation of external files for index entries

+ +

Within the document, @printindex commands are expanded as explained +in Customizing the formatting of index lists. In case you want to do something special with index +entries, outside of the document, you should first set the 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. +

+
+
Function Reference: index_summary_file_begin $index_name $is_printed + +
+

$index_name is the two letters name for the index. +This function +is called for each index +appearing in the document, before +index_summary_file_entry. +$is_printed is true if there is a @printindex for that index. +

+ +
+
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. index_name is the +name of the index. $entry_text is the entry in plain text, +$formatted_entry is the index entry formatted, $texi_entry is the +entry with texinfo commands. $entry_reference is the reference placed +at the index entry place, in the form `file#id'. +$entry_element_header is the formatted header of the element containing +the index entry. entry_element_header is the reference to the +beginning of the element containing the index entry, in the form +`file#id'. +$is_printed is true if there is a @printindex for that index. +

+ +
+
Function Reference: index_summary_file_end $index_name $is_printed + +
+

$index_name is the two letters name for the index. This function +is called for each index appearing in the document, after +index_summary_file_entry. +$is_printed is true if there is a @printindex for that index. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7. Customizing 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, Customizing the HTML and text style. +

+

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

+ + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.1 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 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 @display or @example regions, and in +menu comments (see section Menu formatting). The preformatted regions are usually +rendered in <pre> elements in HTML. +The string context occurs when rendering strings without formatting elements, +in comments or titles for example. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.2 Customizing the formatting of commands without argument

+ +

This includes the commands whose name is a nonletter character like @@, +the commands with lettered characters and braces +but whose braces should be empty, like @TeX{}, or some commands +associated with accentted letters like @AA{}. If there happens to +be something within the braces, it is put after the command, thus +

 
@TeX{something}
+

leads to the same than +

 
@TeX{} something
+
+

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

+ + + +

command type

normal text

preformatted text

string +

one nonlettered character

+

%simple_map

+

%simple_map_pre

+

%simple_map_texi +

nothing in braces

+

%things_map

+

%pre_map

+

%texi_map +

+ +

To change the HTML resulting from these constructs, just change the +value. For example, if you want &shy; to be outputted for @- +in normal and preformatted context, write in your init file: +

+
 
$simple_map{'-'} = '&shy;';
+$simple_map_pre{'-'} = '&shy;';
+
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.3 Customizing accent, style and other simple commands

+ +

The formatting of the HTML produced by style and indicatric +commands (@tt, @code, +@email, @titlefont), the accentuation related +commands taking argument (@', @udotaccent, @dotless) +and miscalleneous commands (@email, @verb, @w, +@uref, @math, @asis) is controlled by two hash in the +default case, + +%style_map for normal context, +%style_map_pre for +preformatted context and +%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: +

+ + + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.3.1 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 +

+
 
$style_map{'command'} = { 'args' => ['code'], 'attribute' => 'code'};
+
+

the arguments for @command are interpreted as specified by +the values associated with the `args' key while the attribute associated +with that command is `code'. +

+

The following keys in the hashes associated with each command have the +following meaning: +

+
+
`args'
+

+The value associated is a reference on an array. Each element of the array +defines how the arguments (separated by `,' in the texinfo code) for +the @-command should be +formatted. The possibilities are +

+
normal
+

for normal text, +

+
code
+

for text with `---', `--', `''' and ```' kept as is, +

+
keep
+

if the texinfo should be kept as is, without interpretation of the @-commands. +

+
+ +

For example, we have +

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

because `---', `--', `''' and ```' should be kept as is in +the first argument of @email. +

+

The default is `['normal']'. +

+
+
`attribute'
+
+

If the associated value is a word, it is considered to be an HTML +element name, and the argument is enclosed between the element opening +and the element closing. For example, if the value is elem, the +resulting HTML is <elem>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 elem class="elem" leads to +<elem class="elem">arg</elem>. +

+

This works only if there is only one argument. +

+
+
`begin'
+
+

The associated value is added in front of the text. +

+
+
`begin'
+
+

The associated value is added after the text. +

+
+
`quotes'
+
+

If the corresponding value is true, the result is +enclosed in quotes +$OPEN_QUOTE_SYMBOL and + +$CLOSE_QUOTE_SYMBOL, with defaults +``' and `''. +

+
+
`function'
+
+

The corresponding value should be a function reference. The corresponding +function is called with the following arguments: +

+
+
$command
+

The @-command name +

+
$args
+

A reference on an array containing the arguments of the @-command. +

+
$style_stack
+

A reference on an array containing the name of the @-commands containing +the @-command being formatted. +

+
$state
+

A reference on a hash containing a lot of informations about the context +of the @-command. +

+
$line_nr
+

An opaque structure containing the information about the line number of the +@-command. It can be used to call main::echo_error or +main::echo_warning with first argument a message, and second argument +$line_nr. +

+
+
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.3.2 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 `"', the result is +enclosed in quotes +$OPEN_QUOTE_SYMBOL and + +$CLOSE_QUOTE_SYMBOL, with defaults +``' and `''. +

+

The command argument is allready formatted as HTML. +The remaining of the value text +(or the value text if there were no `"') is interpreted as follow: +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.3.3 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: +

+
+
Function Reference: $resulting_text style $style $command $text $args $no_close $no_open $line_nr $state $style_stack + +
+

$command is the @-command, $style is the value associated with +the $command in the %style_map, %style_map_pre +or %style_map_texi hashes. +The $text is the text appearing within the @-command braces. +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 +$arg key as described in Reference hash args). +If $text is split in paragraphs each paragraph is passed through +the function, and $no_close is true if it is not the last paragraph, +while $no_open is true if it is not the first paragraph. +$line_nr +is an opaque structure containing the information about the line number of the +@-command. It can be used to call main::echo_error or +main::echo_warning with first argument a message, and second argument +$line_nr. +$state +is a reference on a hash containing a lot of informations about the context +of the @-command. +$style_stack +is a reference on an array containing the name of the @-commands containing +the @-command being formatted. +

+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.4 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 +$anchor, but the function +associated with the function reference does more, it is usefull +to produce a reference target or link. +

+
Function Reference: $anchor anchor $identifier $href $text $attributes + +
+

If $identifier is not empty, this value should be used to create +a target for links (typically associated with a name or id +attribute in HTML). +The $href argument specifies a hpertextual reference which should be +used to link to a target. +In case both $identifier and $href are given the text produced +should be both a target for $identifier and a link to $href. +$text is the text to be displayed. +$attributes are additional attributes. +It should be reasonable to assume that the attributes are for a <a> +HTML element. +

+ +

The formatting of @image is controlled by: +

+
Function Reference: $image image $file_path $basename $preformatted $file_name + +
+

$file_path is the image file name with the path, $basename is the +alternate text or the file name without extension if no alternate text is +given. $preformatted is true if the image +appears in preformatted text. $file_name is the file name without path +but with extension. +

+ +

The formatting of @sp is controlled by: +

+
Function Reference: $sp sp $number $preformatted + +
+

$number is the numeric argument of @sp. +$preformatted is true if the @sp appears in preformatted text. +

+ +

The formatting of @acronym and @abbr is controlled by: +

+
Function Reference: $acronym acronym_like $acronym_texi $acronym_text $with_explanation \@explanation_lines $explanation_text $explanation_simply_formatted + +
+

$acronym_texi is the acronym argument with texinfo @-commands, +$acronym_text is formatted. +

+

The other arguments are related with +the explanation, the second arg of the acronym. $with_explanation is +true if the second argument of the acronym command is present. If an +explanation exists, coming from previous @acronym or as an arg of this +command, the other args are defined: \@explanation_lines is a +reference on an array containing the unformatted explanation lines, +$explanation_text is the explanation text formatted, +$explanation_simply_formatted is the explanation with a light formatting, +unabling in HTML (or XML) the explanation to be in an +attribute. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.5 Processing special characters in text

+ +

Some characters are processed especially in text: `---', `--', +```' and `'''. This is done only if in normal text and not in +some commands (@code, @env…). A function reference +is called to process those characters in text +

+
+
Function Reference: $processed_text normal_text $text + +
+

The function processes `---', `--', ```' and `''' +in $text and returns $processed_text. The default is to +change `---' to `--', `--' to `-', and ```' and +`''' to `"'. +

+ +

Some characters are special in HTML (`&', `"', +`<' and `>') and should be protected. +This is done by the function associated with the function reference +

+
+
Function Reference: $protected_text protect_text $text + +
+

The function processes the unprotected text $text and returns +the resulting protected text $protected_text. +

+ +

Empty lines are processed by the following function reference, which could +be usefull if empty lines are to be removed for example +

+
+
Function Reference: $resulting_text empty_line $empty_line + +
+

This function processes an $empty_line and returns the resulting +text $resulting_text. Empty lines are left as is by default. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.6 Customizing strings written by texi2html

+ + +

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 +`--lang', +$LANG or +@documentlanguage). This is the basis for internationalization +as it allows for strings translations. +

+

The strings are found in a hash reference, +$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 +

+
 
$LANGUAGES->{'fr'} = {
+              ' Up ' => 'Plus haut',
+};
+
+

It means that whenever the string ` Up ' is to be written +and the language is `fr', `Plus haut' is written. It is possible +to customize the english strings by redefining the `en' language hash. +

+

When a string contains a `%' followed by `{' name `}' +it means that the string will be expanded by texi2html. For +example, if we have +

+
 
$LANGUAGES->{'fr'} = {
+              'See %{node_file_href}' => 'Voir %{node_file_href}',
+};
+
+

`%{node_file_href}' will be expanded to an href for a node in a +file by texi2html in the string. A `%%' will be expanded +as `%'. +

+

For more on internationalization, see Internationalization. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.7 References

+ + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.7.1 Reference to 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. +

+
+
Function Reference: $href external_href $node $node_identifier $xml_node_identifier $manual_file_name + +
+

$node is the node name, with @-commands. $node_identifer is the +node name mapped to an identifier acceptable as a file name. +$xml_node_identifier is the +node name mapped to an identifier acceptable as an XML identifier. +Those identifiers are built as explained in (texinfo)HTML Xref, +thus allowing for cross references to external manuals. $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 +makeinfo (see (texinfo)HTML Xref). +

+ +
+
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 $command is the ref command (ref, xref or +pxref, in text, at sentence beginning or in parenthesis). +The optionnal $section argument is the section in the book and + book is the book title. +$node_and_file is the node and file name formatted according to the +convention used in info: `(file)node'. $href it an hypertextual +reference to the distant manual constructed using the above function. +$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. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.7.2 Reference to an internal node

+ +

A function reference is available for internal references. +

+
+
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 $command is the ref command (ref, xref or +pxref, in text, at sentence beginning or in parenthesis). +$href it an hypertextual reference linking to the corresponding +node or section. $short_name and $name hold the text for the +reference but $short_name can be the node name which is assumed to +be shorter than the section name. +$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. +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.8 Commands used for centering and flushing of text

+ + +

When a command controlling the alignement of text is used (@center, +@flushleft and @flushright), the main program takes +care of opening and closing paragraphs. The alignement commands are the +key of the +%paragraph_style hash. +The value is used in the function doing the formatting of the paragraphs. +See section Formatting or not a paragraph or a preformatted region. +

+

A function references allows for a customization of the formatting of the text +appearing in the command block. +

+
+
Function Reference: $result paragraph_style_command $command $text + +
+

$command is the command name, $text is the text appearing within +the command. This function returns a formatted text. +The default is to return the text unmodified. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.9 Formatting or not a paragraph or a preformatted region

+ + + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.9.1 Paragraph and preformatted region formatting

+ + +

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

+
+
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. $text is the text of the paragraph, +$alignement is the empty string when no alignement command has +been seen, otherwise it is the current alignement command name. +See section Commands used for centering and flushing of text. +

+

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 (@itemize…) +may have +an associated formatting command. +$formatting_command is this formatting command +(like @minus). +$formatting_command_formatted is the command formatted in html +in case the formatting command is a leading command (like @minus) +which should be leading the first paragraph. +\$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. $format is the format command. +See section Formatting individual table and list items. +

+

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

+ +
+
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. $text is the text of the +preformatted region, $style is the css style associated with that +preformatted region (See section Customizing the texi2html css lines). $region_name is the +name of the command opening +the preformatted region (example…, see Formatting of complex formats (@example, @display…)) +or a identifier for the preformatted context (for example +menu-comment, see Menu formatting). +The alignment commands are not taken into account, as the spaces are +preserved in preformatted regions, you should flush and center by hand. +

+

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 (@itemize…) +may have +an associated formatting command. +$formatting_command is this formatting command +(like @minus). +$formatting_command_formatted is the command formatted in html +in case the formatting command is a leading command (like @minus) +which should be leading the first preformatted region. +\$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. $format is the +format command. +See section Formatting individual table and list items. +

+

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

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.9.2 Avoiding paragraphs in formats

+ + +

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, +%format_in_paragraph with a true value. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.10 Formatting of complex formats (@example, @display…)

+ + +

Here we see how a whole complex format is formatted. For the formatting +of the text, see Formatting or not a paragraph or a 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 +$complex_format_map. It has a key for each +of the complex format commands (example, smallexample, +lisp, smalllisp, display, smalldisplay, +format, smallformat). +

+

The associated value is also a reference on a hash. The keys are begin +and end. An eval of begin should lead to the beginning of the +formatted HTML, an eval of end should lead to the end of the +formatted HTML. The enclosed text will be formatted as described in +Formatting or not a paragraph or a 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: +

+
+
Function Reference: $complex_format_text complex_format $format_name $preformatted_text + +
+

$format_name is the complex format name, $preformatted_text is the +text allready formatted as described in Formatting or not a paragraph or a preformatted region. +This function returns the whole complex format. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.11 Customizing the formatting of lists and tables

+ +

The formatting of lists and tables is done at two levels: +

+ + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.11.1 Formatting individual table and list items

+ +

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

 
@table @minus
+
+

The default is to apply the command to the text item, however it is possible +to avoid it. +The hash +%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: +

+
 
$special_list_commands{'itemize'} = { 'bullet' => '' };
+
+

and we have the following @itemize: +

 
@itemize @bullet
+@item an item
+@end itemize
+
+

then @bullet will not be applied to an item. +

+
+
lists
+

The items of lists are formatted using the following function reference: +

+
Function Reference: $list_item list_item $text $format $command $formatted_command $item_number $enumerate_style $number + +
+

This function formats the text between @item commands. $text +is the text corresponding with the item. $format is the type of format, +`itemize' or `enumerate'. $command is the formatting command +given in argument to @itemize, $formatted_command is this command +formatted if it is a leading command, like @minus. +

+

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

+ +
+
two column tables
+

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

+
+
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 @item line. +$text_item is the text line. In case there is an index entry +associated with the @item (as with @ftable and +@vtable), $index_label_text is the text inserted at +the place where an index entry appears. See section Formatting of index entries. +$format is the type of format, +`table', `ftable' or `vtable'. $command is the formatting command +given in argument to the table format command, $formatted_command is +this command formatted if it is a leading command, like @minus. +

+ +
+
Function Reference: $table_line table_line $text + +
+

This function is used to format the text on the lines following +the @item line. $text is the corresponding text. +

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

+
+
Function Reference: $multitable_cell cell $text + +
+

This function is used to format the text of a multitable cell, the text +following a @item or a @tab. +$text is the corresponding text. +

+ +
+
Function Reference: $multitable_row row $text $item_command + +
+

This function is used to format a multitable row. $text is +the row text, with cells allready formatted with the +$cell +function reference. $item_command is the command used to introduce +the row, such that it is possible to distinguish between @item and +@headitem. +

+
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.11.2 Formatting of a whole table or list

+ +

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

+ + +

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

+
+
Function Reference: $whole_table_list table_list $command $text + +
+

$command is the Texinfo command name, $text is the formatted +items. +

+ +

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

+
+
Function Reference: $whole_table_list format $command $format $text + +
+

$command is the @-command, $format is the entry associated with +$command in %format_map. $text is the formatted items. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.12 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. +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.12.1 Customizing the interpretation of a definition line

+ +

The keys of the hash +%def_map are definition command names. +There are two types of entries: +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.12.2 Customization of the definition formatting

+ +

Four functions are used when formatting a definition command: +

+
+
category name
+
+
Function Reference: $category definition_category $category_or_name $class $style + +
+

This function precise a category or an index entry name associating a class +$class (if given) with $category_or_name. The $style of the +definition may be `f', for function, `v', for variable or `t', +for type. +

+
+
formatting of the definition line
+
+
Function Reference: $line def_line $category $name $type $arguments $index_label + +
+

This function formats the definition line. $category is the category +formatted with +$definition_category, $name, $type and +arguments are the element of the definition line. $index_label is +the text inserted at the place where an index entry appears. +See section Formatting of index entries. +

+ +
+
definition text
+
+
Function Reference: $definition_text def_item $text + +
+

This function formats the definition text, $text. +

+ +
+
the whole definition
+
+
Function Reference: $definition def $text + +
+

This function formats the whole definition. The definition line and text +formatted by the above functions are in $text. +

+ +
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.13 Customizing headings formatting

+ +

A function controls the formatting of sectioning element headings, +with the corresponding function reference: +

+
Function Reference: $heading_text heading \%element_reference + +
+

The \%element_reference is a reference on a hash corresponding +with the sectioning element. The following keys are of interest: +

+
text
+

The heading text +

+
name
+

The heading text without section number +

+
node
+

true if the sectioning element is a node without associated structuring command +

+
level
+

The level of the element in the document tree. `0' is for @top, +`1' for @chapter and so on +

+
tag_level
+

the sectioning element name, with @raisesections and +@lowersections taken into account +

+
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.14 Formatting of special regions (@verbatim, @cartouche, @quotation)

+ +

Regions corresponding with raw text, like @verbatim, @html +or @tex are formatted according to the following function reference: +

+
+
Function Reference: $raw_region raw $command $text + +
+

$command is the command name, $text is the raw text. +

+ +

If LaTeX2HTML is used, @tex regions are handled differently, +from within the main program. +

+

The @cartouche command formatting is controlled by the +function reference: +

+
+
Function Reference: $cartouche cartouche $text + +
+

$text is the text appearing within the cartouche. +

+ +

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

+
+
Function Reference: $prepended_string quotation_prepend_text $style $text + +
+

$style is the first argument of the @quotation if there are +two arguments. $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. +

+ +

The whole quotation is formatted by: +

+
+
Function Reference: $quotation quotation $quotation_text $argument_text $argument_style_texi $argument_style_id + +
+

$quotation_text is the quotation text, formatted, with the text +prepended by the function above. $argument_text is the second argument +of the @quotation or the first if there is one argument, formatted. +The other arguments are defiend if there are two arguments for the +@quotation, $argument_style_texi is this argument, with +@-commands, and $argument_style_id is this argument transformed in +an identifier which can be used as an XML identifier. +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.15 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. +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.15.1 The structure of a menu

+ +

In texi2html, a menu is considered to be composed of 2 parts, the +menu entries and the menu comments. Menu entries are further +divided in an entry link and optionnaly an entry description. +The entry link consists in a node name and an optionnal menu entry +name. +

+

A menu entry begins with `*' 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: +

+
 
@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 text
+of the description, even if the line begins at the first character,
+because we are in @emph.
+@end menu
+
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.15.2 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 +$NODE_NAME_IN_MENU is +true, however, node names are used. If +$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, +$MENU_SYMBOL is put at the beginning of menu entries +when the node name is used. The default is `&bull;'. +If +$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 + +$MENU_PRE_STYLE. Default is `font-family: serif'. +The css class associated with menu comments is menu-comments. +

+

Three function references are associated with the formatting of the +different parts of a menu: +

+
Function Reference: $link menu_link $section \%state $href $node $name $ending + +
+

$section is the section name corresponding with the link, $href +is the link hypertextual reference. $href may be absent. \%state +holds informations about the current context. The only key which could be +of interest is preformatted, true if the context is a preformatted +context. See section Three contexts for expansions: preformatted, normal and string. +$node is the node name, $name is the +name of the node, and $ending is the text ending the link entry. +

+ +
+
Function Reference: $description menu_description $description_text \%state + +
+

$description_text is the text of the menu description. \%state +should be used similarly than for the menu link. +

+ +
+
Function Reference: $menu_comment menu_comment $text + +
+

$text is the text of the menu comment. It is in a preformatted +environment. +

+ +

The following function reference controls the formatting of a wole menu: +

+
+
Function Reference: $menu menu $menu_components_text + +
+

$menu_components_text is the formatted menu components text, obtained +as explained above. +

+ +

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 HTML production. +In that case the menu description and menu comments are not formatted +specially, but treated like normal text. +

+
Function Reference: $link simple_menu_link $link_text $href $node $name $ending + +
+

$link_text is the text corresponding with the link name, $href +is the link hypertextual reference. +$node is the node name, $name is the +name of the node, and $ending is the text ending the link entry. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.16 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 @cindex determines where index entries +appear, and the index list is printed with a @printindex command. +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.16.1 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: +

+
+
Function Reference: $target index_entry_label $identifier $preformatted + +
+

$identifier should be used to create +a target for links (typically associated with a name or id +attribute in HTML). +$preformatted is true if the index entry appeared in preformatted text. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.16.2 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 +$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: +

+
+
formatting of a letter in a summary
+
+
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. +$letter is the letter. $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. $identifier is an identifier for the target +letter entry. +

+ +
+
formatting of a summary
+
+
Function Reference: $summary index_summary \@alphabetical_letters \@nonalphabetical_letters + +
+

\@alphabetical_letters and \@nonalphabetical_letters contain the +formatted summary letters, formatted with the above function. +

+ +
+
formatting of an index entry
+
+
Function Reference: $entry index_entry $entry_href $entry_text $section_href $section_heading + +
+

$entry_href is a reference to the place where the index entry +appeared, $entry_text is the corresponding text. $section_href +is a reference to the beginning of the sectioning element containing +the index entry, $section_heading is the heading of the element. +

+ +
+
formatting of letter entry
+
+
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. $letter is the letter, $identifier +should be used to create a target for links (typically links from summaries), +and $index_entries_text is the text of the index entries formatted as +described above. +

+ +
+
formatting of whole index
+
+
Function Reference: $index print_index $index_text $index_name + +
+

$index_text is the text of all the index entries grouped by letter +appearing in that page formatted as above. index_name is the name of +the index, the argument of @printindex. +

+
+
+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.17 Floats and lists of floats

+ +

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

+

A hash reference is associated with each float, it is available in some +formatting functions. The keys are: +

+
caption_texi
+
shortcaption_texi
+

A reference on an array containing the caption or shortcaption lines, +unformatted. +

+
style_texi
+

The style with texi @-commands. +

+
style_id
+

The unique identifier associated with the style. +

+
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). +

+
chapter_nr
+

The number of the chapter containing the float. +

+
nr_in_chapter
+

The number of the float in the chapter. +

+
absolut_nr
+

The number of the float in the document. +

+
texi
+

The label with @-commands. +

+
id
+

The unique identifier associated with the label. Usefull to make an anchor +or a reference. +

+
element
+

A reference on a structure representing the element the float appear in. +

+
+ + + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.17.1 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: +

+
+
Function Reference: (\@caption_lines_returned, \@shortcaption_lines_returned) caption_shortcaption \%float \@caption_lines \@shortcaption_lines + +
+

\%float is the structure defined above. \@caption_lines and +\@shortcaption_lines are references on arrays containing the +texinfo lines for caption and short caption. \@caption_lines_returned +and \@shortcaption_lines_returned are references on an array +containing the texinfo lines for the caption and shortcaption. +

+ +

Then the float is formatted with the following function reference: +

+
+
Function Reference: $text float $float_text \%float $caption_text $shortcaption_text + +
+

$float_text is the text appearing within the @float, formatted. +\%float is still the structure defined above. $caption_text and +$shortcaption_text are the caption and short caption build with the +above function and formatted. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.17.2 Formatting lists of floats

+ +

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

+
+
Function Reference: $style_texi_returned listoffloats_style $style_texi + +
+

$style_texi is the @listoffloats argument with texinfo +@-commands kept. It is possible to make changes to the $style_texi and +return a modified string, still with @-commands. The modified string +is formatted in the main program. +

+ +

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

+
+
Function Reference: $float_style_texi_returned listoffloats_float_style $style_texi \%float + +
+

$style_texi is the style, and \%float is the structure described +above. This function reference returns a style to be formatted in the +main program. +

+ +
+
Function Reference: $caption_texi_returned listoffloats_caption \%float + +
+

\%float is the structure described +above. This function reference returns a caption to be formatted in the +main program. +

+ +

Each entry is formatted by: +

+
+
Function Reference: $listoffloats_entry listoffloats_entry $style_texi \%float $float_style $caption $href + +
+

$style_texi is the style with @-commands, $float_style is the +style returned by the above function and formatted. $caption is the +caption returned by the above function formatted. \%float is the +structure corresponding with the float, and $href is an href pointing to +the float location. +

+ +

Lastly, the whole @listoffloats is formatted by: +

+
+
Function Reference: $listoffloats listoffloats $style_texi $style \@listoffloats_entries + +
+

$style_texi is the style with @-commands, $style is the +style returned by the above function and formatted. The array reference +\@listoffloats_entries holds the entries formatted by the above +function. +

+ +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.18 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: +

+
+
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 + +
+

$number_in_doc is the footnote number in the whole document, +$number_in_page is the footnote number in the current page. +$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 $place_id is an identifier for the location of the footnote +in the main document. Similarly, $document_file is the file name +of the file containing the text where the footnote appears in the main +document, while $footnote_file is the file name of the file where +the footnote text appears. +

+

\@lines is a reference on an array containing the footnote text +lines, allready formatted. +And \%state holds informations about the context at the footnote +place in the main document. As usual the most usefull entry is +preformatted which is true if the footnote appears in a preformatted +context. +

+

This function returns a reference on an array, \@lines containing +the updated footnote text for the footnote entry, and $text_for_document, +the text appearing at the footnote place in the main document, linking +to the footnote entry. +

+ +

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, Customizing the layout of the special pages. For +the determination of the footnote locations, Page layout related command line options. +

+
+
Function Reference: foot_section \@footnotes_lines + +
+

This function formats a group of footnotes. \@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. +

+ + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

7.19 Customizing other commands, and unknown commands

+ + + +

Many commands without braces are available in texinfo, sometimes with +a specific syntax. For example we have @sp, @noindent, +@documentlanguage, @oddheading, @headings, +@shortcontents, @shorttitlepage or @comment. +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: + +%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 line +for the arg property for the command @-command. +

+
 
$misc_command{'command'} = {'arg' => 'line', 'skip' => 'space'};
+
+

The properties and possible values are: +

+
+
skip
+

This property enables to set what is skipped after the command arguments. +Here are the possible values: +

+
line
+

The remaining of the line is skipped. +

+
space
+

Spaces are skipped but not newline. +

+
whitespace
+

Spaces are skipped +

+
linewhitespace
+

Spaces are skipped if there are only spaces remaining on the line. +

+
linespace
+

Spaces are skipped, but not newline if +there are only spaces remaining on the line +

+
+ +
+
arg
+

If the associated value is line the line is considered to be the +argument. If it is a number it is the number of args (separated by spaces). +

+
texi
+

If true the arguments are considered to real texinfo, therefore + @value and @macro are expanded. +

+
keep
+

If true the args and the macro are kept, otherwise they are discarded. +The defaut is to have keep undef for all the commands. +If keep is true for @verbatiminclude the default +action for this macro isn't done. +

+
+ + +

Commands which don't appear in the hashes + +%simple_map, +%simple_map_pre, + +%simple_map_texi and %misc_command, or that appear in +%misc_command but with keep true are processed by the +following function reference: +

+
+
Function Reference: ($result_line, $result, $result_text, $message) unknown $command $line + +
+

$command is the @-command, $line is the line following the +$command. $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 $result is true, $result_line is the new line +to be processed further, $result_text is the resulting formatted text +and $message, if defined is a message outputted to the output +with line number added by texi2html. +

+ +

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

+
+
Function Reference: ($result, $result_text, $message) unknown_style $command $text + +
+

$command is the @-command, $text is the text appearing within +the braces (allready formatted). $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 $result is true, $result_text is the resulting +formatted text +and $message, if defined is a message outputted to the output +with line number added by texi2html. +

+ + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

A. 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 Customizing strings written by texi2html. This also enables translation of the +strings. +

+ + + + + +
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

A.1 Translating strings

+ + +

If the language is allready supported, then there will be a file +in the `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 $LANGUAGES->{'language'} +hash in that file. The keys are the english strings, in '', the +values (in '' after =>) are the translations. +When a string contains a `%' followed by `{' name `}' +it means that the string will be expanded by texi2html. For +an example, see Customizing strings written by texi2html. +

+

After that you should run the command ./manage_i18n.pl all in +the top directory, it should merge your file with the existing files in +`translations.pl', which is incorporated to the `texi2html' script +by ./configure. +

+

If the language isn't currently supported, copy the `en' file in +`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 `manage_i18n.pl' file in the +@known_languages array. +

+

After that you should similarly run the command +./manage_i18n.pl all in +the top directory. +

+

Obsoleted strings are not removed from the files, they are still present +in the $T2H_OBSOLETE_STRINGS->{'language'} hash in case +the string is reused later. +

+

If you made change to strings specified in installed files +(see section Installation of texi2html) +you will have to reinstall them otherwise the installated files will +take precedence (see section Use initialization files for fine tuning). +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

A.2 Adding new strings written to document

+ + +

If you need to write strings, for example the new string a string +to the resulting document, call &$I('a string'). Use simple quotes. +If you want to substitute a value in the string put +%{string_value}, in the string, and give a second argument +to &$I, a hash reference with key string_value and value +the what you want to substitute. +Here is an example: +

+
 
return &$I('%{name} of %{class}', { 'name' => $name, 'class' => $class });
+
+

In that case %{name} is substituted by $name in the translated +string. +

+

After that you should run the command ./manage_i18n.pl all in the top +directory, it should add your new strings to all the files in the `i18n' +directory. +

+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

B. Command Line Option Index

+
Jump to:   C +   +D +   +F +   +H +   +I +   +L +   +M +   +N +   +O +   +P +   +S +   +T +   +U +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry Section

C
css-include=file4.6 Customizing the HTML and text style

D
def-table4.6 Customizing the HTML and text style
doctype=DTD4.6 Customizing the HTML and text style
Dvar4.4 Command line options related to Texinfo language features

F
frames4.5 Page layout related command line options
frameset-doctype4.6 Customizing the HTML and text style
frameset-doctype=DTD4.6 Customizing the HTML and text style

H
html-xref-prefix=path4.6 Customizing the HTML and text style

I
Idir4.4 Command line options related to Texinfo language features
if<region>4.3 Specifying which regions get expanded
include-css6.7 Customizing the texi2html css lines
init-file4.8 Use initialization files for fine tuning
init-file4.8 Use initialization files for fine tuning
iso4.6 Customizing the HTML and text style

L
l2h4.7 Expanding @tex and @math regions using LaTeX2HTML
l2h-file4.7 Expanding @tex and @math regions using LaTeX2HTML
l2h-l2h=program4.7 Expanding @tex and @math regions using LaTeX2HTML
l2h-tmp4.7 Expanding @tex and @math regions using LaTeX2HTML
lang4.8 Use initialization files for fine tuning
lang7.6 Customizing strings written by texi2html
lang=lang4.4 Command line options related to Texinfo language features

M
menu4. Invoking texi2html

N
no-if<region>4.3 Specifying which regions get expanded
node-files4.2 Setting output file and directory names
nomenu4. Invoking texi2html
nomenu4.3 Specifying which regions get expanded
nosec-nav4.5 Page layout related command line options
number4.6 Customizing the HTML and text style

O
output4.2 Setting output file and directory names
output4.2 Setting output file and directory names

P
Pdir4.4 Command line options related to Texinfo language features
pkgdatadir=dir3. Installation of texi2html
pkgdatadir=dir4.8 Use initialization files for fine tuning
prefix4.2 Setting output file and directory names

S
separated-footnotes4.5 Page layout related command line options
short-ext4.2 Setting output file and directory names
short-ref4.6 Customizing the HTML and text style
split4.1 Specifying where to split the generated document
sysconfdir=dir4.8 Use initialization files for fine tuning

T
toc-file4.2 Setting output file and directory names
toc-links4.6 Customizing the HTML and text style
top-file4.2 Setting output file and directory names

U
use-nodes4.1 Specifying where to split the generated document
use-nodes4.1 Specifying where to split the generated document
use-nodes4.1 Specifying where to split the generated document
Uvar4.4 Command line options related to Texinfo language features

+
Jump to:   C +   +D +   +F +   +H +   +I +   +L +   +M +   +N +   +O +   +P +   +S +   +T +   +U +   +
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

C. Variable Index

+
Jump to:   $ +   +% +   +@ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry Section

$
$AFTER_BODY_OPEN6.8 Customizing the page header
$AFTER_OVERVIEW6.11.1.2 Table of contents and Short table of contents
$AFTER_TOC_LINES6.11.1.2 Table of contents and Short table of contents
$anchor5.1 Redefining functions in initialization files
$anchor7.4 Formatting of special simple commands
$AVOID_MENU_REDUNDANCY7.15.2 The formatting of the different menu components
$BEFORE_OVERVIEW6.11.1.2 Table of contents and Short table of contents
$BEFORE_TOC_LINES6.11.1.2 Table of contents and Short table of contents
$BIG_RULE6.2 Page layout and navigation panel overview
$BODYTEXT6.5 Preparing the output
$BODYTEXT6.8 Customizing the page header
$cell7.11.1 Formatting individual table and list items
$CLOSE_QUOTE_SYMBOL7.3.1 An interface for commands formatting with a hash reference
$CLOSE_QUOTE_SYMBOL7.3.2 An interface for commands formatting with a string
$complex_format_map7.10 Formatting of complex formats (@example, @display…)
$CSS_LINES6.7 Customizing the texi2html css lines
$CSS_LINES6.7 Customizing the texi2html css lines
$CSS_LINES6.7 Customizing the texi2html css lines
$DEF_TABLE4.6 Customizing the HTML and text style
$DEFAULT_RULE6.2 Page layout and navigation panel overview
$definition_category7.12.2 Customization of the definition formatting
$DO_CONTENTS6.11.1.2 Table of contents and Short table of contents
$DO_SCONTENTS6.11.1.2 Table of contents and Short table of contents
$DOCTYPE4.6 Customizing the HTML and text style
$DOCUMENT_DESCRIPTION6.8 Customizing the page header
$DOCUMENT_ENCODING6.8 Customizing the page header
$ENCODING6.8 Customizing the page header
$EXTENSION6.12 Customizing the file names
$EXTERNAL_DIR4.6 Customizing the HTML and text style
$EXTRA_HEAD6.8 Customizing the page header
$FRAMES4.5 Page layout related command line options
$FRAMESET_DOCTYPE4.6 Customizing the HTML and text style
$ICONS6.3.1 Controlling the navigation panel panel at a high level
$IDX_SUMMARY6.13 Generation of external files for index entries
$INDEX_CHAPTERElement labels
$L2H_L2H4.7 Expanding @tex and @math regions using LaTeX2HTML
$L2H_TMP4.7 Expanding @tex and @math regions using LaTeX2HTML
$LANG4.4 Command line options related to Texinfo language features
$LANG4.8 Use initialization files for fine tuning
$LANG7.6 Customizing strings written by texi2html
$LANGUAGES7.6 Customizing strings written by texi2html
$LANGUAGESA.1 Translating strings
$MENU_PRE_STYLE7.15.2 The formatting of the different menu components
$MENU_SYMBOL7.15.2 The formatting of the different menu components
$MIDDLE_RULE6.2 Page layout and navigation panel overview
$NODE_FILES4.2 Setting output file and directory names
$NODE_FILES6.12 Customizing the file names
$NODE_NAME_IN_MENU7.15.2 The formatting of the different menu components
$NUMBER_SECTIONS4.6 Customizing the HTML and text style
$OPEN_QUOTE_SYMBOL7.3.1 An interface for commands formatting with a hash reference
$OPEN_QUOTE_SYMBOL7.3.2 An interface for commands formatting with a string
$OUT4.2 Setting output file and directory names
$PRE_BODY_CLOSE6.10 Customizing the page footer
$PREFIX4.2 Setting output file and directory names
$print_chapter_footer6.10 Customizing the page footer
$print_chapter_header6.8 Customizing the page header
$print_foot_navigation6.10 Customizing the page footer
$print_head_navigation6.8 Customizing the page header
$print_misc6.11.2 Customizing the layout of the special pages
$print_misc_footer6.11.2 Customizing the layout of the special pages
$print_misc_header6.11.2 Customizing the layout of the special pages
$print_page_foot6.10 Customizing the page footer
$print_page_head6.8 Customizing the page header
$print_section_footer6.10 Customizing the page footer
$print_section_header6.8 Customizing the page header
$print_Top6.11.2 Customizing the layout of the special pages
$print_Top_footer6.11.2 Customizing the layout of the special pages
$print_Top_header6.11.2 Customizing the layout of the special pages
$SECTION_NAVIGATION4.5 Page layout related command line options
$SECTION_NAVIGATION6.3.1 Controlling the navigation panel panel at a high level
$SEPARATED_FOOTNOTES4.5 Page layout related command line options
$SHORT_REF4.6 Customizing the HTML and text style
$SHORTEXTN4.2 Setting output file and directory names
$SHOW_MENU4.3 Specifying which regions get expanded
$SMALL_RULE6.2 Page layout and navigation panel overview
$SPLIT4.1 Specifying where to split the generated document
$SPLIT_INDEX7.16.2 Customizing the formatting of index lists
$T2H_OBSOLETE_STRINGSA.1 Translating strings
$Texi2HTML::NODE{Next}6.3.2 Specifying the buttons formatting
$Texi2HTML::OVERVIEWSection lines
$Texi2HTML::OVERVIEW6.11.1.2 Table of contents and Short table of contents
$Texi2HTML::THIS_HEADERSection lines
$Texi2HTML::THIS_SECTIONSection lines
$Texi2HTML::THIS_SECTION6.4.3 Function usefull in page formatting
$Texi2HTML::TOC_LINESSection lines
$Texi2HTML::TOC_LINES6.11.1.2 Table of contents and Short table of contents
$TOC_FILE4.2 Setting output file and directory names
$TOC_LINKS4.6 Customizing the HTML and text style
$TOC_LIST_ATTRIBUTE6.11.1.2 Table of contents and Short table of contents
$TOC_LIST_STYLE6.11.1.2 Table of contents and Short table of contents
$TOP_FILE4.2 Setting output file and directory names
$TOP_HEADINGElement labels
$UNNUMBERED_SYMBOL_IN_MENU7.15.2 The formatting of the different menu components
$USE_ISO4.6 Customizing the HTML and text style
$USE_NODES4.1 Specifying where to split the generated document
$VERTICAL_HEAD_NAVIGATION6.3.1 Controlling the navigation panel panel at a high level
$WORDS_IN_PAGE6.3.2 Specifying the buttons formatting
$WORDS_IN_PAGE6.3.2 Specifying the buttons formatting
$WORDS_IN_PAGE6.4.3 Function usefull in page formatting

%
%accent_map7.3 Customizing accent, style and other simple commands
%ACTIVE_ICONS6.3.2 Specifying the buttons formatting
%BUTTONS_GOTO6.5 Preparing the output
%css_map6.7 Customizing the texi2html css lines
%css_map6.7 Customizing the texi2html css lines
%def_map7.12.1 Customizing the interpretation of a definition line
%format_in_paragraph7.9.2 Avoiding paragraphs in formats
%format_map7.11.2 Formatting of a whole table or list
%format_map7.11.2 Formatting of a whole table or list
%main::valueFlags
%main::valueFlags
%misc_command7.19 Customizing other commands, and unknown commands
%NAVIGATION_TEXT6.3.2 Specifying the buttons formatting
%NAVIGATION_TEXT6.5 Preparing the output
%paragraph_style7.8 Commands used for centering and flushing of text
%PASSIVE_ICONS6.3.2 Specifying the buttons formatting
%pre_map7.2 Customizing the formatting of commands without argument
%simple_map7.2 Customizing the formatting of commands without argument
%simple_map7.19 Customizing other commands, and unknown commands
%simple_map_pre7.2 Customizing the formatting of commands without argument
%simple_map_pre7.19 Customizing other commands, and unknown commands
%simple_map_texi7.2 Customizing the formatting of commands without argument
%simple_map_texi7.19 Customizing other commands, and unknown commands
%special_list_commands7.11.1 Formatting individual table and list items
%style_map7.3 Customizing accent, style and other simple commands
%style_map7.19 Customizing other commands, and unknown commands
%style_map_pre7.3 Customizing accent, style and other simple commands
%style_map_pre7.19 Customizing other commands, and unknown commands
%style_map_texi7.3 Customizing accent, style and other simple commands
%style_map_texi7.19 Customizing other commands, and unknown commands
%Texi2HTML::HREF6.4.1 Accessing elements informations
%Texi2HTML::NAME6.4.1 Accessing elements informations
%Texi2HTML::NO_TEXI6.4.1 Accessing elements informations
%Texi2HTML::NODE6.4.1 Accessing elements informations
%Texi2HTML::THISDOCGlobal strings
%texi_map7.2 Customizing the formatting of commands without argument
%things_map7.2 Customizing the formatting of commands without argument

@
@CHAPTER_BUTTONS6.3.2 Specifying the buttons formatting
@CSS_FILES4.6 Customizing the HTML and text style
@EXPAND4.3 Specifying which regions get expanded
@INCLUDE_DIRS4.4 Command line options related to Texinfo language features
@MISC_BUTTONS6.3.2 Specifying the buttons formatting
@NODE_FOOTER_BUTTONS6.3.2 Specifying the buttons formatting
@PREPEND_DIRS4.4 Command line options related to Texinfo language features
@SECTION_BUTTONS6.3.2 Specifying the buttons formatting
@SECTION_FOOTER_BUTTONS6.3.2 Specifying the buttons formatting

+
Jump to:   $ +   +% +   +@ +
+
+ + + + + + + + + + + + + + + + + +
[ < ][ > ]   [ << ][ Up ][ >> ]         [Top][Contents][Index][ ? ]
+

D. Concept Index

+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +I +   +M +   +P +   +R +   +S +   +T +   +U +   +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Index Entry Section

A
Avoid paragraph opening7.9.2 Avoiding paragraphs in formats

B
bug reportTexi2HTML

C
centering7.8 Commands used for centering and flushing of text
complex format7.10 Formatting of complex formats (@example, @display…)
`Config'4.8 Use initialization files for fine tuning
configure3. Installation of texi2html

D
downloading texi2html source2. Obtaining texi2html

E
examples of manuals1. Overview
external manual7.7.1 Reference to external manual

F
flushing text7.8 Commands used for centering and flushing of text

I
i18n7.6 Customizing strings written by texi2html
i18nA.1 Translating strings
Installation3. Installation of texi2html
internationalization4.8 Use initialization files for fine tuning
internationalized stringsA.2 Adding new strings written to document

M
makeinfo1.1 Why texi2html and not makeinfo?
manage_i18n.plA.2 Adding new strings written to document

P
paragraph7.9.1 Paragraph and preformatted region formatting
preformatted region7.9.1 Paragraph and preformatted region formatting

R
reference7.7 References

S
skipped command7.19 Customizing other commands, and unknown commands
source code for texi2html, downloading2. Obtaining texi2html

T
texi2html source, downloading2. Obtaining texi2html
Texinfo1. Overview
text alignement7.8 Commands used for centering and flushing of text
TranslationA.1 Translating strings

U
unknown command7.19 Customizing other commands, and unknown commands

+
Jump to:   A +   +B +   +C +   +D +   +E +   +F +   +I +   +M +   +P +   +R +   +S +   +T +   +U +   +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

Table of Contents

+
+ + +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

Short Table of Contents

+
+ +
+
+ + + + + + +
[Top][Contents][Index][ ? ]
+

About This Document

+

+ This document was generated by Derek R. Price on February, 3 2005 using texi2html 1.76. +

+

+ The buttons in the navigation panels have the following meaning: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Button Name Go to From 1.2.3 go to
[ < ] Backprevious section in reading order1.2.2
[ > ] Forwardnext section in reading order1.2.4
[ << ] FastBackbeginning of this chapter or previous chapter1
[ Up ] Upup section1.2
[ >> ] FastForwardnext chapter2
[Top] Topcover (top) of document  
[Contents] Contentstable of contents  
[Index] Indexindex  
[ ? ] Aboutabout (help)  
+ +

+ where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure: +

+ + + +
+

+ + This document was generated by Derek R. Price on February, 3 2005 using texi2html 1.76. + +
+ +

+ + -- cgit v1.2.3