Options controlling Titles, File-Names and Sectioning

* -t <top-page-title>
Same as setting: $TITLE = "<top-page-title>";
Name the document using this title.

* -short_extn
Same as setting: $SHORTEXTN = 1;
Use a filename prefix of .htm for the produced HTML files. This is particularly useful for creating pages to be stored on CD-ROM or other media, to be used with operating systems that require a 3-character extension.

* -long_titles <num>
Same as setting: $LONG_TITLES = <num>;
Instead of the standard names: node1.html, node2.html,... the filenames for each HTML page are constructed from the first <num> words of the section heading for that page, separated by the `_' character.
Commas and common short words (a an to by of and for the) are omitted from both title and word-count.

Warning: Use this switch with great caution. Currently there are no checks for uniqueness of names or overall length. Very long names can easily result from using this feature.

* -custom_titles
Same as setting: $CUSTOM_TITLES = 1;
Instead of the standard names: node1.html, node2.html, ... the filenames for each HTML page are constructed using a Perl subroutine named custom_title_hook . The user may define his/her own version of this subroutine, within a .latex2html-init file say, to override the default (which uses the standard names). This subroutine takes the section-heading as a parameter and must return the required name, or the empty string (default).

* -dir <output-directory>
Same as setting: $DESTDIR = "<output-directory>";
Redirect the output to the specified directory.
The default behaviour is to create (or reuse) a directory having the same name as the prefix of the document being processed.

* -no_subdir
Same as setting: $NO_SUBDIR = 1;
Place the generated HTML files into the current directory. This overrides any $DESTDIR setting.

* -prefix <filename-prefix>
Same as setting: $PREFIX = "<filename-prefix>";
The <filename-prefix> will be prepended to all .gif, .pl and .html files produced, except for the top-level .html file; it may include a (relative) directory path. This will enable multiple products of LATEX2HTML to peacefully coexist in the same directory. However, do not attempt to simultaneously run multiple instances of LATEX2HTML using the same output directory, else various temporary files will overwrite each other.

* -auto_prefix
Same as setting: $AUTO_PREFIX = 1;
Constructs the prefix as ` <title>-' to be prepended to all the files produced, where <title> is the name of the LATEX file being processed. (Note the `-' in this prefix.)
This overrides any $PREFIX setting.

* -no_auto_link
Same as setting: $NO_AUTO_LINK = 1;
If $NO_AUTO_LINK is empty and variables $LINKPOINT and $LINKNAME are defined appropriately (as is the default in the latex2html.config file), then a hard link to the main HTML page is produced, using the name supplied in $LINKNAME. Typically this is index.html; on many systems a file of this name will be used, if it exists, when a browser tries to view a URL which points to a directory. On other systems a different value for $LINKNAME may be appropriate. Typically $LINKPOINT has value $FILE.html, but this may also be changed to match whichever HTML page is to become the target of the automatic link.
Use of the -no_auto_link switch cancels this automatic linking facility, when not required for a particular document.

* -split <num>
Same as setting: $MAX_SPLIT_DEPTH = <num>; (default is 8)
Stop splitting sections into separate files at this depth. Specifying -split 0 will put the entire document into a single HTML file. See below for the different levels of sectioning. Also see the next item for how to set a ``relative'' depth for splitting.

* -split + <num>
Same as setting: $MAX_SPLIT_DEPTH = -<num>; (default is 8)
The level at which to stop splitting sections is calculated ``relative to'' the shallowest level of sectioning that occurs within the document. For example, if the document contains \section commands, but no \part or \chapter commands, then -split +1 will cause splitting at each \section but not at any deeper level; whereas -split +2 or -split +3 also split down to \subsection and \subsubsection commands respectively. Specifying -split +0 puts the entire document into a single HTML file.

* -link <num>
Same as setting: $MAX_LINK_DEPTH = <num>; (default is 4)
For each node, create links to child nodes down to this much deeper than the node's sectioning-level.
Specifying -link 0 will show no links to child nodes from that page,
-link 1 will show only the immediate descendents, etc.
A value at least as big as that of the -split <num> depth will produce a mini table-of-contents (when not empty) on each page, for the tree structure rooted at that node.

When the page has a sectioning-level less than the -split depth, so that the a mini table-of-contents has links to other HTML pages, this table is located at the bottom of the page, unless placed elsewhere using the \tableofchildlinks command.

On pages having a sectioning-level just less than the -split depth the mini table-of-contents contains links to subsections etc. occurring on the same HTML page. Now the table is located at the top of this page, unless placed elsewhere using the \tableofchildlinks command.

* -toc_depth <num>
Same as setting: $TOC_DEPTH = <num>; (default is 4)
Sectioning levels down to <num> are to be included within the Table-of-Contents tree.

* -toc_stars
Same as setting: $TOC_STARS = 1;
Sections created using the starred-form of sectioning commands are included within the Table-of-Contents. As with LATEX , normally such sections are not listed.

* -show_section_numbers
Same as setting: $SHOW_SECTION_NUMBERS = 1;
Show section numbers. By default section numbers are not shown, so as to encourage the use of particular sections as stand-alone documents. In order to be shown, section titles must be unique and must not contain inlined graphics.

* -unsegment
Same as setting: $UNSEGMENT = 1;
Treat a segmented document (see the section about document segmentation) like it were not segmented. This will cause the translator to concatenate all segments and process them as a whole. You might find this useful to check a segmented document for consistency.


For all documents the sectioning levels referred to above are:

0 document
1 part
2 chapter
3 section
4 subsection
5 subsubsection
6 paragraph
7 subparagraph
8 subsubparagraph
These levels apply even when the document contains no sectioning for the shallower levels; e.g. no \part or \chapter commands is most common, especially when using LATEX 's article document-class.


Ross Moore
1999-03-26