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

texi2html can accept more than one manual on the command line, and will proceed with each of the manuals in turn.

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

When more than one manual is processed, the command line apply to all the manuals, except for command-line switches setting the output file names.

4.1 General options

Miscellaneous general options:

‘--error-limit=num’

Quit after num errors (default 1000), (variable $ERROR_LIMIT).

‘--help’

Display a short help and exit.

‘--verbose’

Be verbose.

‘--version’

Display version information and exit.

4.2 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 section ‘Two Paths’ in GNU Texinfo).

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.3 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 is 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, ‘fot’ for footnotes if they are separated) 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 @setfilename to determine the manual name(1). Also 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). The default is false for this option. 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. This trick enables the generated HTML manual to be a target for the cross-references of other manuals generated by makeinfo or texi2html.

In case the files are named after the node names, another command-line option, ‘--transliterate-file-names’ can be set to trigger ASCII transliteration of node file names (variable $TRANSLITERATE_NODE). Transliteration is set in the default case.

4.4 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.5 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.6 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 ‘--no-headers’ (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 with ‘--footnote-style’ set to ‘end’ or on a separate page with ‘--footnote-style’ set to ‘separate’ (variable $SEPARATED_FOOTNOTES set to 0 or 1). The default is to have separated footnotes.

4.7 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 section ‘HTML CSS’ in GNU Texinfo. 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.

‘--css-ref=URL’

This command line switch provides for the inclusion of an reference to a Cascading Style Sheet (CSS) URL. More than one URL may be specified (array @CSS_REFS).

‘--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-sections’

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.8 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.9 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, ‘--document-language’ 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.

Some init files are provided with texi2html, for example ‘book.init’ which produces an output more in line with what could be in a book, or ‘chm.init’ outputs files that can be used to produce a CHM file.

This document was generated by Derek Price on January 1, 2009 using texi2html 1.80.