latex2html - translate LaTeX files to HTML (HyperText Markup
Language)
latex2html [options] [target [target ...]]
This manual page explains the LaTeX2HTML utility, which is
a Perl program that translates LaTeX document into HTML
format. For each source file given as an argument the translator will create
a directory containing the corresponding HTML files. For details and
examples, please consult the online html documentation, a copy of which
should be available in /usr/share/doc/latex2html/manual.ps.gz or
/usr/share/doc/latex2html/html/
This documentation has been derived from the TeX manual, and may
not be up to date. Please refer to the online manual for authoritative
documentation.
- -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 descendants,
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.
The switches described here govern the type of HTML code
that can be generated, and how to choose between the available options when
there are alternative strategies for implementing portions of LaTeX
code.
- -html_version
(2.0|3.2|4.0|5.0)[,(math|i18n)]*
- Same as setting: $HTML_VERSION = ... ; This specifies both the
HTML version to generate, and any extra (non-standard) HTML
features that may be required. The version number corresponds to a
published DTD for an HTML standard. A corresponding Perl
file in the versions/ subdirectory is loaded; these files are named
`html<num>.pl'. Following the version number, a comma-separated list
of extensions can be given. Each corresponds to a file `<name>.pl'
also located in the versions/ subdirectory. When such a file is loaded the
resulting HTML code can no longer be expected to validate with the
specified DTD. An exception is math when the -no_math switch is also used,
which should still validate. Currently, versions 2.0, 3.2, 4.0 and 5.0 are
available. The default version is usually set to be `5.0', within
latex2html.config.
- -no_tex_defs
- Same as setting: $TEXDEFS = 0; (default is 1) When $TEXDEFS
is set (default) the file texdefs.perl will be read. This provides code to
allow common TEX commands like \def, \newbox, \newdimen and others, to be
recognised, especially within the document preamble. In the case of \def,
the definition may even be fully interpreted, but this requires the
pattern-matching to be not too complicated. If $TEXDEFS is `0' or
empty, then texdefs.perl will not be loaded; the translator will make no
attempt to interpret any raw TEX commands. This feature is intended to
enable sophisticated authors the ability to insert arbitrary TEX commands
in environments that are destined to be processed by LaTeX anyway;
e.g. figures, theorems, pictures, etc. However this should rarely be
needed, as now there is better support for these types of environment.
There are now other methods to specify which chunks of code are to be
passed to LaTeX for explicit image-generation; see the discussion
of the makeimage environment.
- -external_file
<filename>
- Same as setting: $EXTERNAL_FILE = <filename> ; Specifies the
prefix of the .aux file that this document should read. The .aux extension
will be appended to this prefix to get the complete filename, with
directory path if needed. This file could contain necessary information
regarding citations, figure, table and section numbers from LaTeX
and perhaps other information also. Use of this switch is vital for
document segments, processed separately and linked to appear as if
generated from a single LaTeX document.
- -font_size
<size>
- Same as setting: $FONT_SIZE = <size> ; This option provides
better control over the font size of environments made into images using
LaTeX. <size> must be one of the font sizes that LaTeX
recognizes; i.e. `10pt', `11pt', `12pt', etc. Default is `10pt', or
whatever option may have been specified on the \documentclass or
\documentstyle line. Whatever size is selected, it will be magnified by
the installation variables $MATH_SCALE_FACTOR,
$FIGURE_SCALE_FACTOR and $DISP_SCALE_FACTOR as appropriate.
Note: This switch provides no control over the size of text on the HTML
pages. Such control is subject entirely to the user's choices of settings
for the browser windows.
- -scalable_fonts
- Same as setting: $SCALABLE_FONTS = 1; This is used when scalable
fonts, such as PostScript versions of the TEX fonts, are available for
image-generation. It has the effect of setting $PK_GENERATION to
`1', and $DVIPS_MODE to be empty, overriding any previous settings
for these variables.
- -no_math
- Same as setting: $NO_SIMPLE_MATH = 1; Ordinarily simple
mathematical expressions are set using the ordinary text font, but
italicized. When part of the expression can not be represented this way,
an image is made of the whole formula. This is called ``simple math''.
When $NO_SIMPLE_MATH is set, then all mathematics is made into
images, whether simple or not. However, if the math extension is loaded,
using the -html_version switch described earlier, then specifying -no_math
produces a quite different effect. Now it is the special <MATH> tags
and entities which are canceled. In their place a sophisticated scheme for
parsing mathematical expressions is used. Images are made of those
sub-parts of a formula which cannot be adequately expressed using
(italicized) text characters and <SUB> and <SUP> tags. See the
subsection on mathematics for more details.
- -local_icons
- Same as setting: $LOCAL_ICONS = 1; A copy of each of the icons
actually used within the document is placed in the directory along with
the HTML files and generated images. This allows the whole document
to be fully self-contained, within this directory; otherwise the icons
must be retrieved from a (perhaps remote) server. It is also the default
behavior if $ICONSERVER is not set. The icons are normally copied from a
subdirectory of the
$LATEX2HTMLDIR,
set within latex2html.config. An alternative set of icons can be used by
specifying a (relative) directory path in $ALTERNATIVE_ICONS to where
the customised images can be found.
- -init_file
<file>
- Load the specified initialisation file. This Perl file will be
loaded after loading $HOME/.latex2html-init, or .latex2html-init in
the local directory, if either file exists. It is read at the time the
switch is processed, so the contents of the file may change any of the
values of any of the variables that were previously established, as well
as any default options. More than one initialisation file can be read in
this way.
- -no_fork
- Same as setting: $NOFORK = 1; When set this disables a feature in
the early part of the processing whereby some memory-intensive operations
are performed by `forked' child processes. Some single-task operating
systems, such as DOS, do not support this feature. Having $NOFORK
set then ensures that unnecessary file-handles that are needed with the
forked processes, are not consumed unnecessarily, perhaps resulting in a
fatal Perl error.
- -iso_language
<type>
- This enables you to specify a different language type than 'EN' to be used
in the lang attribute of the HTML document, e.g. 'en-US'.
- -short_index
- Same as setting: $SHORT_INDEX = 1; Creates shorter Index listings,
using codified links; this is fully compatible with the makeidx
package.
- Same as setting: $NO_FOOTNODE = 1; Suppresses use of a separate
file for footnotes; instead these are placed at the bottom of the
HTML pages where the references occur. When this option is used, it
is frequently desirable to change the style of the marker used to indicate
the presence of a footnote. This is done as in LaTeX, using code
such as follows. \renewcommand{\thefootnote}{\arabic{footnote}} All the
styles \arabic, \alph, \roman, \Alph and \Roman are available.
- Same as setting: $NUMBERED_FOOTNOTES = 1; If this is set you will
get every footnote applied with a subsequent number, to ease
readability.
- -address
<author-address>
- Same as setting: $ADDRESS = <author-address> ; Sign each page
with this address. See latex2html.config for an example using Perl
code to automatically include the date. A user-defined Perl
subroutine called &custom_address can be used instead, if defined; it
takes the value of $ADDRESS as a parameter, which may be used or
ignored as desired. At the time when this subroutine will be called,
variables named $depth, $title, $file hold the
sectioning-level, title and filename of the HTML page being
produced; $FILE holds the name of the filename for the title-page
of the whole document.
- -info
<string>
- Same as setting: $INFO = <string> ; Generate a new section
``About this document'' containing information about the document being
translated. The default is to generate such a section with information on
the original document, the date, the user and the translator. An empty
string (or the value `0') disables the creation of this extra section. If
a non-empty string is given, it will be placed as the contents of the
``About this document'' page instead of the default information.
These switches affect whether images are created at all, whether
old images are reused on subsequent runs or new ones created afresh, and
whether anti-aliasing effects are used within the images themselves.
- -use_dvipng
- Use the dvipng program to generate png images, rather than using dvips
followed by gs. This method produces better alignment of math formulas
which extend significantly above or below the line of text in which they
are contained.
- -nouse_pdftex
- Generate intermediate images with plain latex instead of pdflatex. If your
document is written for pdflatex, run ``pdflatex'' first and then
``latex2html''. If your document is written for plain, dvi-producing
latex, run ``latex'' first and then ``latex2html -nouse_pdftex''.
- -use_luatex
- Generate intermediate images with lualatex instead of plain latex.
Produced PDF output will then be translated into images with GhostScript.
Useful for lualatex documents which cannot be translated by latex or
pdflatex.
- -use_luadvi
- Generate intermediate images with dvilualatex instead of plain latex.
Useful for dvilualatex documents which cannot be translated by latex.
- -ascii_mode
- Same as setting: $ASCII_MODE = $EXTERNAL_IMAGES = 1; Use only ASCII
characters and do not include any images in the final output. With
-ascii_mode the output of the translator can be used on character-based
browsers, such as lynx, which do not support inlined images (via the
<IMG> tag).
- -nolatex
- Same as setting: $NOLATEX = 1; Disable the mechanism for passing
unknown environments to LaTeX for processing. This can be thought
of as ``draft mode'' which allows faster translation of the basic document
structure and text, without fancy figures, equations or tables. (This
option has been superseded by the -no_images option, see below.)
- -external_images
- Same as setting: $EXTERNAL_IMAGES = 1; Instead of including any
generated images inside the document, leave them outside the document and
provide hypertext links to them.
- -ps_images
- Same as setting: $PS_IMAGES = $EXTERNAL_IMAGES = 1; Use links to
external PostScript files rather than inlined images in the chosen
graphics format.
- -discard
- Same as setting: $DISCARD_PS = 1; The temporary PostScript files
are discarded immediately after they have been used to create the image in
the desired graphics format.
- -no_images
- Same as setting: $NO_IMAGES = 1; Do not attempt to produce any
inlined images. The missing images can be generated ``off-line'' by
restarting LaTeX2HTML with the option -images_only .
- -images_only
- Same as setting: $IMAGES_ONLY = 1; Try to convert any inlined
images that were left over from previous runs of LaTeX2HTML.
- -reuse
<reuse_option>
- Same as setting: $REUSE = <reuse_option>; This switch
specifies the extent to which image files are to be shared or recycled.
There are three valid options: [*] 0 Do not ever share or recycle image
files. This choice also invokes an interactive session prompting the user
about what to do about a pre-existing HTML directory, if it exists.
[*] 1 Recycle image files from a previous run if they are available, but
do not share identical images that must be created in this run. [*] 2
Recycle image files from a previous run and share identical images from
this run. This is the default. A later section provides additional
information about image-reuse.
- -no_reuse
- Same as setting: $REUSE = 0; Do not share or recycle images
generated during previous translations. This is equivalent to -reuse 0 .
(This will enable the initial interactive session during which the user is
asked whether to reuse the old directory, delete its contents or
quit.)
- -antialias
- Same as setting: $ANTI_ALIAS = 1; (Default is 0.) Generated images
of figure environments and external PostScript files should use
anti-aliasing. By default anti-aliasing is not used with these images,
since this may interfere with the contents of the images themselves.
- -antialias_text
- Same as setting: $ANTI_ALIAS_TEXT = 1; (Default is 1.) Generated
images of typeset material such as text, mathematical formulas, tables and
the content of makeimage environments, should use anti-aliasing effects.
The default is normally to use anti-aliasing for text, since the resulting
images are much clearer on-screen. However the default may have been
changed locally.
- -no_antialias
- Same as setting: $ANTI_ALIAS = 0; (Default is 0.) Generated images
of figure environments and external PostScript files should not use
anti-aliasing with images, though the local default may have been changed
to use it.
- -no_antialias_text
- Same as setting: $ANTI_ALIAS_TEXT = 0; (Default is 1.) Generated
images of typeset material should not use anti-aliasing effects. Although
on-screen images of text are definitely improved using anti-aliasing,
printed images can be badly blurred, even at 300dpi. Higher resolution
printers do a much better job with the resulting grey-scale images.
- -white
- Same as setting: $WHITE_BACKGROUND = 1; (Default is 1.) Ensures
that images of figure environments have a white background. Otherwise
transparency effects may not work correctly.
- -no_white
- Same as setting: $WHITE_BACKGROUND = ''; (Default is 1.) Cancels
the requirement that figure environments have a white background.
- -ldump
- Same as setting: $LATEX_DUMP = 1; (Default is 0.) Use this if you
want to speed up image processing during the 2nd and subsequent runs of
LaTeX2HTML on the same document. The translator now produces a
LaTeX format-dump of the preamble to images.tex which is used on
subsequent runs. This significantly reduces the startup time when
LaTeX reads the images.tex file for image-generation. This process
actually consumes additional time on the first run, since LaTeX is
called twice -- once to create the format-dump, then again to load and use
it. The pay-off comes with the faster loading on subsequent runs.
Approximately 1 Meg of disk space is consumed by the dump file.
The following switches govern whether to include one or more
navigation panels on each HTML page, also which buttons to include
within such a panel.
- -no_navigation
- Same as setting: $NO_NAVIGATION = 1; Disable the mechanism for
putting navigation links in each page. This overrides any settings of the
$TOP_NAVIGATION, $BOTTOM_NAVIGATION and
$AUTO_NAVIGATION variables.
- -top_navigation
- Same as setting: $TOP_NAVIGATION = 1; Put navigation links at the
top of each page.
- -bottom_navigation
- Same as setting: $BOTTOM_NAVIGATION = 1; Put navigation links at
the bottom of each page as well as the top.
- -auto_navigation
- Same as setting: $AUTO_NAVIGATION = 1; Put navigation links at the
top of each page. Also put one at the bottom of the page, if the page
exceeds $WORDS_IN_PAGE number of words (default = 450).
- -next_page_in_navigation
- Same as setting: $NEXT_PAGE_IN_NAVIGATION = 1; Put a link to the
next logical page in the navigation panel.
- -previous_page_in_navigation
- Same as setting: $PREVIOUS_PAGE_IN_NAVIGATION = 1; Put a link to
the previous logical page in the navigation panel.
- -contents_in_navigation
- Same as setting: $CONTENTS_IN_NAVIGATION = 1; Put a link to the
table-of-contents in the navigation panel if there is one.
- -index_in_navigation
- Same as setting: $INDEX_IN_NAVIGATION = 1; Put a link to the
index-page in the navigation panel if there is an index.
When processing a single stand-alone document, the switches
described in this section should not be needed at all, since the
automatically generated navigation panels, described on the previous page
should generate all the required navigation links. However if a document is
to be regarded as part of a much larger document, then links from its first
and final pages, to locations in other parts of the larger (virtual)
document, need to be provided explicitly for some of the buttons in the
navigation panel. The following switches allow for such links to other
documents, by providing the title and URL for navigation panel hyperlinks.
In particular, the ``Document Segmentation'' feature necessarily makes great
use of these switches. It is usual for the text and targets of these
navigation hyperlinks to be recorded in a Makefile, to avoid tedious typing
of long command-lines having many switches.
- -up_url
<URL>
- Same as setting: $EXTERNAL_UP_LINK = <URL> ; Specifies a
universal resource locator (URL) to associate with the ``UP'' button in
the navigation panel(s).
- -up_title
<string>
- Same as setting: $EXTERNAL_UP_TITLE = <string> ; Specifies a
title associated with this URL.
- -prev_url
<URL>
- Same as setting: $EXTERNAL_PREV_LINK = <URL> ; Specifies a
URL to associate with the ``PREVIOUS'' button in the navigation
panel(s).
- -prev_title
<string>
- Same as setting: $EXTERNAL_PREV_TITLE = <string> ; Specifies
a title associated with this URL.
- -down_url
<URL>
- Same as setting: $EXTERNAL_DOWN_LINK = <URL> ; Specifies a
URL for the ``NEXT'' button in the navigation panel(s).
- -down_title
<string>
- Same as setting: $EXTERNAL_DOWN_TITLE = <string> ; Specifies
a title associated with this URL.
- -contents
<URL>
- Same as setting: $EXTERNAL_CONTENTS = <URL> ; Specifies a URL
for the ``CONTENTS'' button, for document segments that would not
otherwise have one.
- -index
<URL>
- Same as setting: $EXTERNAL_INDEX = <URL> ; Specifies a URL
for the ``INDEX'' button, for document segments that otherwise would not
have an index.
- -biblio
<URL>
- Same as setting: $EXTERNAL_BIBLIO = <URL> ; Specifies the URL
for the bibliography page to be used, when not explicitly part of the
document itself. Warning: On some systems it is difficult to give
text-strings <string> containing space characters, on the
command-line or via a Makefile. One way to overcome this is to use the
corresponding variable. Another way is to replace the spaces with
underscores (_).
The first two of the following switches are self-explanatory. When
problems arise in processing a document, the switches -debug and -verbosity
will each cause LaTeX2HTML to generate more output to the screen.
These extra messages should help to locate the cause of the problem.
- -tmp
<path>
- Define a temporary directory to use for image generation. If <path>
is 0, the standard temporary directory /tmp is used.
- -h(elp)
- Print out the list of all command-line options.
- -v
- Print the current version of LaTeX2HTML.
- -debug
- Same as setting: $DEBUG = 1; Run in debug-mode, displaying messages
and/or diagnostic information about files read, and utilities called by
LaTeX2HTML. Shows any messages produced by these calls. More
extensive diagnostics, from the Perl debugger, can be obtained by
appending the string `-w-' to the 1st line of the latex2html (and other)
Perl script(s).
- -verbosity
<num>
- Same as setting: $VERBOSITY = <num>; Display messages
revealing certain aspects of the processing performed by LaTeX2HTML
on the provided input file(s). The <num> parameter can be an integer
in the range 0 to 8. Each higher value adds to the messages produced.
- 0.
- No special tracing; as for versions of LaTeX2HTML prior to
V97.1.
- 1.
- (This is the default.) Show section-headings and the corresponding HTML
file names, and indicators that major stages in the processing have been
completed.
- 2.
- Print environment names and identifier numbers, and new theorem-types.
Show warnings as they occur, and indicators for more stages of processing.
Print names of files for storing auxiliary data arrays.
- 3.
- Print command names as they are encountered and processed; also any
unknown commands encountered while pre-processing. Show names of new
commands, environments, theorems, counters and counter-dependencies, for
each document partition.
- 4.
- Indicate command-substitution the pre-process of math-environments. Print
the contents of unknown environments for processing in LaTeX, both
before and after reverting to LaTeX source. Show all operations
affecting the values of counters. Also show links, labels and sectioning
keys, at the stages of processing.
- 5.
- Detail the processing in the document preamble. Show substitutions of new
environments. Show the contents of all recognised environments, both
before and after processing. Show the cached/encoded information for the
image keys, allowing two images to be tested for equality.
- 6.
- Show replacements of new commands, accents and wrapped commands.
- 7.
- Trace the processing of commands in math mode; both before and after.
- 8.
- Trace the processing of all commands, both before and after. The
command-line option sets an initial value only. During processing the
value of $VERBOSITY can be set dynamically using the
\htmltracing{...} command, whose argument is the desired value, or by
using the more general \HTMLset command as follows:
\HTMLset{VERBOSITY}{<num>}.
The configuration variables described here do not warrant having a
command-line switch to assign values. Either they represent aspects of
LaTeX2HTML that are specific to the local site, or they govern
properties that should apply to all documents, rather than something that
typically would change for the different documents within a particular
sub-directory. Normally these variables have their value set within the
latex2html.config file. In the following listing the defaults are shown, as
the lines of Perl code used to establish these values. If a different value
is required, then these can be assigned from a local .latex2html-init
initialisation file, without affecting the defaults for other users, or
documents processed from other directories.
- $dd
- holds the string to be used in file-names to delimit directories; it is
set internally to `/', unless the variable has already been given a value
within latex2html.config . Note: This value cannot be set within a
.latex2html-init initialisation file, since its value needs to be known in
order to find such a file.
- $LATEX2HTMLDIR
- Read by the install-test script from latex2html.config, its value is
inserted into the latex2html Perl script as part of the
installation process.
- $LATEX2HTMLSTYLES = $LATEX2HTMLDIR/styles ;
- Read from the latex2html.config file by install-test, its value is checked
to locate the styles/ directory.
- $LATEX2HTMLVERSIONS = $LATEX2HTMLDIR/versions ;
- The value of this variable should be set within latex2html.config to
specify the directory path where the version and extension files can be
found.
- $ALTERNATIVE_ICONS = '';
- This may contain the (relative) directory path to a set of customised
icons to be used in conjunction with the -local_icons switch.
- $TEXEXPAND = $LATEX2HTMLDIR/texexpand ;
- Read by the install-test Perl script from latex2html.config, its
value is used to locate the texexpand Perl script.
- $PSTOIMG = $LATEX2HTMLDIR/pstoimg ;
- Read by the install-test Perl script from latex2html.config, its
value is used to locate the pstoimg Perl script.
- $IMAGE_TYPE = '<image-type>';
- Set in latex2html.config, the currently supported <image-type>s are:
svg, png and gif. Vector formats such as svg look better at high
resolution, while bitmap formats such as png or gif are generally faster
to download and to render.
- $DVIPS = 'dvips';
- Read from latex2html.config by install-test, its value is checked to
locate the dvips program or script. There could be several reasons to
change the value here:
add a switch -P<printer> to load a specific
configuration-file; e.g. to use a specific set of PostScript fonts, for
improved image-generation.
to prepend a path to a different version of dvips than normally
available as the system default (e.g. the printing requirements are
different).
to append debugging switches, in case of poor quality images; one
can see which paths are being searched for fonts and other resources.
to prepend commands for setting path variables that dvips may need
in order to locate fonts or other resources.
If automatic generation of fonts is required, using Metafont, the
following configuration variables are important.
- $PK_GENERATION = 1;
- This variable must be set, to initiate font-generation; otherwise fonts
will be scaled from existing resources on the local system. In particular
this variable must not be set, if one wishes to use PostScript fonts or
other scalable font resources (see the -scalable_fonts switch).
- $DVIPS_MODE = 'toshiba';
- The mode given here must be available in the modes.mf file, located with
the Metafont resource files, perhaps in the misc/ subdirectory.
- $METAFONT_DPI = 180;
- The required resolution, in dots-per-inch, should be listed specifically
within the MakeTeXPK script, called by dvips to invoke Metafont with the
correct parameters for the required fonts.
- $LATEX = 'latex';
- Read from latex2html.config by install-test, its value is checked to
locate the latex program or script. If LaTeX is having trouble
finding style-files and/or packages, then the default command can be
prepended with other commands to set environment variables intended to
resolve these difficulties; e.g. $LATEX = 'setenv TEXINPUTS <path to
search> ; latex' . There are several variables to help control
exactly which files are read by LaTeX2HTML and by LaTeX when
processing images:
- $TEXINPUTS
- This is normally set from the environment variable of the same name. If
difficulties occur so that styles and packages are not being found, then
extra paths can be specified here, to resolve these difficulties.
- $DONT_INCLUDE
- This provides a list of filenames and extensions to not include, even if
requested to do so by an \input or \include command. (Consult
latex2html.config for the default list.)
- $DO_INCLUDE = '';
- List of exceptions within the $DONT_INCLUDE list. These files are
to be read if requested by an \input or \include command.
- $ICONSERVER = '<URL>';
- This is used to specify a URL to find the standard icons, as used for the
navigation buttons. Names for the specific images size, as well as size
information, can be found in latex2html.config. The icons themselves can
be replaced by customised versions, provided this information is correctly
updated and the location of the customised images specified as the value
of $ICONSERVER. When the -local_icons switch is used, so that a copy of
the icons is placed with the HTML files and other generated images,
the value of $ICONSERVER is not needed within the HTML files
themselves.
- $NAV_BORDER = <num>;
- The value given here results in a border, measured in points, around each
icon. A value of `0' is common, to maintain strict alignment of inactive
and active buttons in the control panels.
- $LINKNAME = '"index.$EXTN"';
- This is used when the $NO_AUTO_LINK variable is empty, to allow a
URL to the working directory to be sufficient to reach the main page of
the completed document. It specifies the name of the HTML file
which will be automatically linked to the directory name. The value of
$EXTN is .html unless $SHORTEXTN is set, in which case it is
.htm .
- $LINKPOINT = '"$FILE$EXTN"';
- This specifies the name of the HTML file to be duplicated, or
symbolically linked, with the name specified in $LINKNAME. At the
appropriate time the value of $FILE is the document name, which
usually coincides with the name of the working directory.
- $CHARSET = 'utf-8';
- This specifies the character set used within the HTML pages
produced by LaTeX2HTML. If no value is set in a configuration or
initialisation file, the default value will be assumed. The lowercase form
$charset is also recognised, but this is overridden by the
uppercase form.
- $ACCENT_IMAGES = 'large';
- Accented characters that are not part of the ISO-Latin fonts can be
generated by making an image using LaTeX. This variable contains a
(comma-separated) list of LaTeX commands for setting the style to
be used when these images are made. If the value of this variable is empty
then the accent is simply ignored, using an un-accented font character
(not an image) instead.
Within the color.perl package, the following two variables are
used to identify the names of files containing specifications for named
colors. Files having these names are provided, in the
$LATEX2HTMLSTYLES directory, but they could be moved elsewhere, or
replaced by alternative files having different names. In such a case the
values of these variables should be altered accordingly.
$RGBCOLORFILE = 'rgb.txt';
$CRAYOLAFILE = 'crayola.txt';
The following variables may well be altered from the system
defaults, but this is best done using a local .latex2html-init
initialisation file, for overall consistency of style within documents
located at the same site, or sites in close proximity.
- $default_language = 'english';
- This establishes which language code is to be placed within the
<!DOCTYPE ... > tag that may appear at the beginning of the
HTML pages produced. Loading a package for an alternative language
can be expected to change the value of this variable. See also the
$TITLES_LANGUAGE variable, described next.
- $TITLES_LANGUAGE = 'english';
- This variable is used to specify the actual strings used for standard
document sections, such as ``Contents'', ``References'', ``Table of
Contents'', etc. Support for French and German titles is available in
corresponding packages. Loading such a package will normally alter the
value of this variable, as well as the $default_language variable
described above.
- $WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
- Specifies how many words to use from section titles, within the textual
hyperlinks which accompany the navigation buttons.
- $WORDS_IN_PAGE = 450;
- Specifies the minimum page length required before a navigation panel is
placed at the bottom of a page, when the $AUTO_NAVIGATION variable
is set.
- $CHILDLINE = "<BR><HR> (dq;
- This gives the HTML code to be placed between the child-links table
and the ordinary contents of the page on which it occurs.
- $NETSCAPE_HTML = 0;
- When set, this variable specifies that HTML code may be present
which does not conform to any official standard. This restricts the
contents of any <!DOCTYPE ... > tag which may be placed at the
beginning of the HTML pages produced.
- $BODYTEXT = '';
- The value of this variable is used within the <BODY ... > tag; e.g.
to set text and/or background colors. It's value is overridden by the
\bodytext command, and can be added-to or parts changed using the
\htmlbody command or \color and \pagecolor from the color package.
- $INTERLACE = 1;
- When set, interlaced images should be produced. This requires graphics
utilities to be available to perform the interlacing operation.
- $TRANSPARENT_FIGURES = 1;
- When set, the background of images should be made transparent; otherwise
it is white. This requires graphics utilities to be available which can
specify the color to be made transparent.
- $FIGURE_SCALE_FACTOR = 1;
- Scale factor applied to all images of figure and other environments, when
being made into an image. Note that this does not apply to recognised
mathematics environments, which instead use the contents of
$MATH_SCALE_FACTOR and $DISP_SCALE_FACTOR to specify scaling.
- $MATH_SCALE_FACTOR = 1;
- Scale factor applied to all images of mathematics, both inline and
displayed. A value of 1.4 is a good alternative, with anti-aliased
images.
- $DISP_SCALE_FACTOR = 1;
- Extra scale factor applied to images of displayed math environments. When
set, this value multiplies $MATH_SCALE_FACTOR to give the total
scaling. A value of `1.2' is a good choice to accompany $MATH_SCALE_FACTOR
= 1.4;.
- $EXTRA_IMAGE_SCALE
- This may hold an extra scale factor that can be applied to all generated
images. When set, it specifies that a scaling of $EXTRA_IMAGE_SCALE
be applied when images are created, but to have their height and width
recorded as the un-scaled size. This is to coax browsers into scaling the
(usually larger) images to fit the desired size; when printed a better
quality can be obtained. Values of `1.5' and `2' give good print quality
at 600dpi.
- $PAPERSIZE = 'a5';
- Specifies the size of a page for typesetting figures or displayed math,
when an image is to be generated. This affects the lengths of lines of
text within images. Since images of text or mathematics should use larger
sizes than when printed, else clarity is lost at screen resolutions, then
a smaller paper-size is generally advisable. This is especially so if both
the $MATH_SCALE_FACTOR and $DISP_SCALE_FACTOR scaling factors are
being used, else some images may become excessively large, including a lot
of blank space.
- $LINE_WIDTH = 500;
- Formerly specified the width of an image, when the contents were to be
right- or center-justified. (No longer used.)
The following variables are used to access the utilities required
during image-generation. File and program locations on the local system are
established by the configure-pstoimg Perl script and stored within
$LATEX2HTMLDIR/local.pm as Perl code, to be read by pstoimg
when required. After running the configure-pstoimg Perl script it should not
be necessary to alter the values obtained. Those shown below are what
happens on the author's system; they are for illustration only and do not
represent default values.
$GS_LIB = '/usr/local/share/ghostscript/4.02';
$PNMCAT = '/usr/local/bin/pnmcat';
$PPMQUANT = '/usr/local/bin/ppmquant';
$PNMFLIP = '/usr/local/bin/pnmflip';
$PPMTOGIF = '/usr/local/bin/ppmtogif';
$HOWTO_TRANSPARENT_GIF = 'netpbm';
$GS_DEVICE = 'pnmraw';
$GS = '/usr/local/bin/gs';
$PNMFILE = '/usr/local/bin/pnmfile';
$HOWTO_INTERLACE_GIF = 'netpbm';
$PBMMAKE = '/usr/local/bin/pbmmake';
$PNMCROP = '/usr/local/bin/pnmcrop';
$TMP = '/usr/var/tmp'; The following variables are no longer needed, having
been replaced by the more specific information obtained using the Perl
script configure-pstoimg.
$USENETPBM = 1;
$PBMPLUSDIR = '/usr/local/bin';
Nikos Drakos, Computer Based Learning Unit, University of Leeds
<nikos@cbl.leeds.ac.uk>. Several people have contributed suggestions,
ideas, solutions, support and encouragement. The current maintainer is Ross
Moore. This manual page was written by Manoj Srivastava
<srivasta@debian.org>, for the Debian GNU/Linux system, based on the
LaTeX documentation accompanying the program.