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

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:

@node node1
@chapter node 1
node1 text

@node node2
node2 text

@node node3
node3 text
@chapter node 3
chapter text

@node node1
@chapter node 1
node1 text

@node node2
node2 text

@node node3
node3 text
@chapter node 3
chapter text

@node node1
@chapter node 1
node1 text

@node node2
node2 text

@node node3
node3 text
@chapter node 3
chapter text

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.

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.

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.

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.

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.

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

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.

This document was generated by Derek R. Price on July, 14 2005 using texi2html 1.77.