Permalink
Cannot retrieve contributors at this time
1324 lines (1322 sloc)
44.3 KB
.\" Hey, Emacs! This is an -*- nroff -*- source file. | |
.\" Copyright (c) 1997 Manoj Srivastava <srivasta@debian.org> | |
.\" | |
.\" This is free documentation; you can redistribute it and/or | |
.\" modify it under the terms of the GNU General Public License as | |
.\" published by the Free Software Foundation; either version 2 of | |
.\" the License, or (at your option) any later version. | |
.\" | |
.\" The GNU General Public License's references to "object code" | |
.\" and "executables" are to be interpreted as the output of any | |
.\" document formatting or typesetting system, including | |
.\" intermediate and printed output. | |
.\" | |
.\" This manual is distributed in the hope that it will be useful, | |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
.\" GNU General Public License for more details. | |
.\" | |
.\" You should have received a copy of the GNU General Public | |
.\" License along with this manual; if not, write to the Free | |
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 | |
.\" USA. | |
.\" | |
.\" | |
.TH LaTeX2HTML 1 "January 1 2021" "Debian" "Debian GNU/Linux manual" | |
.SH NAME | |
latex2html \- translate LaTeX files to HTML (HyperText Markup Language) | |
.SH SYNOPSIS | |
.B latex2html | |
.I [options] | |
\&[target [target ...]] | |
.SH DESCRIPTION | |
This manual page explains the | |
.B "LaTeX2HTML" | |
utility, which is a | |
.B Perl | |
program that translates | |
.B LaTeX | |
document into | |
.B 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 | |
.I /usr/share/doc/latex2html/manual.ps.gz | |
or | |
.I /usr/share/doc/latex2html/html/ | |
.SH CAVEAT | |
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. | |
.SH Options controlling Titles, File-Names and Sectioning | |
.TP | |
.B -t <top-page-title> | |
Same as setting: | |
.I $TITLE = "<top-page-title>"; | |
Name the document using this title. | |
.TP | |
.B -short_extn | |
Same as setting: | |
.I $SHORTEXTN = 1; | |
Use a filename prefix of .htm for the produced | |
.B 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. | |
.TP | |
.B -long_titles <num> | |
Same as setting: | |
.I $LONG_TITLES = <num>; | |
Instead of the standard names: node1.html, node2.html,... the filenames | |
for each | |
.B 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. | |
.TP | |
.B -custom_titles | |
Same as setting: | |
.I $CUSTOM_TITLES = 1; | |
Instead of the standard names: node1.html, node2.html, ... the | |
filenames for each | |
.B HTML | |
page are constructed using a | |
.B 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). | |
.TP | |
.B -dir <output-directory> | |
Same as setting: | |
.I $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. | |
.TP | |
.B -no_subdir | |
Same as setting: | |
.I $NO_SUBDIR = 1; | |
Place the generated | |
.B HTML | |
files into the current directory. This | |
overrides any | |
.I $DESTDIR | |
setting. | |
.TP | |
.B -prefix <filename-prefix> | |
Same as setting: | |
.I $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 | |
.B LaTeX2HTML | |
to peacefully coexist in the same directory. However, do not | |
attempt to simultaneously run multiple instances of | |
.B LaTeX2HTML | |
using | |
the same output directory, else various temporary files will overwrite | |
each other. | |
.TP | |
.B -auto_prefix | |
Same as setting: | |
.I $AUTO_PREFIX = 1; | |
Constructs the prefix as `<title>-' to be prepended to all the files | |
produced, where <title> is the name of the | |
.B LaTeX | |
file being processed. | |
(Note the `-' in this prefix.) | |
This overrides any | |
.I $PREFIX | |
setting. | |
.TP | |
.B -no_auto_link | |
Same as setting: | |
.I $NO_AUTO_LINK = 1; | |
If $NO_AUTO_LINK is empty and variables | |
.I $LINKPOINT | |
and | |
.I $LINKNAME | |
are | |
defined appropriately (as is the default in the latex2html.config | |
file), then a hard link to the main | |
.B HTML | |
page is produced, using the | |
name supplied in | |
.I $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 | |
.I $LINKNAME | |
may be appropriate. Typically | |
.I $LINKPOINT | |
has | |
value | |
.I $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. | |
.TP | |
.B -split <num> | |
Same as setting: | |
.I $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 | |
.B HTML | |
file. See | |
below for the different levels of sectioning. Also see the next item | |
for how to set a ``relative'' depth for splitting. | |
.TP | |
.B -split +<num> | |
Same as setting: | |
.I $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 | |
.B HTML | |
file. | |
.TP | |
.B -link <num> | |
Same as setting: | |
.I $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 | |
.B 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 | |
.B HTML | |
page. Now the table is located at the top of this page, | |
unless placed elsewhere using the \\tableofchildlinks command. | |
.TP | |
.B -toc_depth <num> | |
Same as setting: | |
.I $TOC_DEPTH = <num>; (default is 4) | |
Sectioning levels down to <num> are to be included within the | |
Table-of-Contents tree. | |
.TP | |
.B -toc_stars | |
Same as setting: | |
.I $TOC_STARS = 1; | |
Sections created using the starred-form of sectioning commands are | |
included within the Table-of-Contents. As with | |
.B LaTeX, | |
normally such | |
sections are not listed. | |
.TP | |
.B -show_section_numbers | |
Same as setting: | |
.I $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. | |
.TP | |
.B -add_ref_name | |
Same as setting: | |
.I $ADD_REF_NAME = 1; | |
Usually cross reference text contains only the caption number as a | |
hyperlink to the corresponding | |
.B LaTeX | |
label. However, it could be | |
handy to see the name of the object referenced, if the reference text | |
would contain both the caption number and the caption name. | |
With -add_ref_name the caption name is shown additionally when available. | |
.TP | |
.B -cut_ref_num | |
Same as setting: | |
.I $CUT_REF_NUM = 1; | |
Usually cross reference text contains only the caption number as a | |
hyperlink to the corresponding | |
.B LaTeX | |
label. With -add_ref_name the | |
caption name can be shown additionally. If the caption number is not | |
desired, it can be cut out with -cut_ref_num. If -cut_ref_num is | |
given and -add_ref_name is not, then the cross reference text is | |
suppressed completely and a cross reference button shown instead. | |
.TP | |
.B -unsegment | |
Same as setting: | |
.I $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: | |
.RS | |
0 document | |
1 part | |
2 chapter | |
3 section | |
4 subsection | |
5 subsubsection | |
6 paragraph | |
7 subparagraph | |
8 subsubparagraph | |
.RE | |
.P | |
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 | |
.B LaTeX's | |
article document-class. | |
.SH Options controlling Extensions and Special Features | |
The switches described here govern the type of | |
.B HTML | |
code that can be | |
generated, and how to choose between the available options when there are | |
alternative strategies for implementing portions of | |
.B LaTeX | |
code. | |
.TP | |
.B -html_version (2.0|3.2|4.0|5.0)[,(math|i18n)]* | |
Same as setting: | |
.I $HTML_VERSION = "... "; | |
This specifies both the | |
.B HTML | |
version to generate, and any extra | |
(non-standard) | |
.B HTML | |
features that may be required. | |
The version number corresponds to a published DTD for an | |
.B HTML | |
standard. A | |
corresponding | |
.B 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. | |
.TP | |
.B -no_tex_defs | |
Same as setting: | |
.I $TEXDEFS = 0; (default is 1) | |
When | |
.I $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 | |
.I $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 | |
.B 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 | |
.B LaTeX | |
for explicit | |
image-generation; see the discussion of the makeimage environment. | |
.TP | |
.B -external_file <filename> | |
Same as setting: | |
.I $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 | |
.B 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. | |
.TP | |
.B -font_size <size> | |
Same as setting: | |
.I $FONT_SIZE = "<size>"; | |
This option provides better control over the font size of environments | |
made into images using | |
.B LaTeX. | |
<size> must be one of the font sizes that | |
.B 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 | |
.I $MATH_SCALE_FACTOR, | |
.I $FIGURE_SCALE_FACTOR | |
and | |
.I $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. | |
.TP | |
.B -scalable_fonts | |
Same as setting: | |
.I $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 | |
.I $PK_GENERATION | |
to `1', and | |
.I $DVIPS_MODE | |
to | |
be empty, overriding any previous settings for these variables. | |
.TP | |
.B -no_math | |
Same as setting: | |
.I $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 | |
.I $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. | |
.TP | |
.B -local_icons | |
Same as setting: | |
.I $LOCAL_ICONS = 1; | |
A copy of each of the icons actually used within the document is placed | |
in the directory along with the | |
.B 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 | |
.B $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. | |
.TP | |
.B -init_file <file> | |
Load the specified initialisation file. This | |
.B Perl | |
file will be loaded | |
after loading | |
.I $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. | |
.TP | |
.B -no_fork | |
Same as setting: | |
.I $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 | |
.I $NOFORK | |
set then ensures that | |
unnecessary file-handles that are needed with the forked processes, are | |
not consumed unnecessarily, perhaps resulting in a fatal | |
.B Perl | |
error. | |
.TP | |
.B -iso_language <type> | |
This enables you to specify a different language type than 'EN' to be | |
used in the lang attribute of the | |
.B HTML | |
document, e.g. 'en-US'. | |
.TP | |
.B -short_index | |
Same as setting: | |
.I $SHORT_INDEX = 1; | |
Creates shorter Index listings, using codified links; this is fully | |
compatible with the makeidx package. | |
.TP | |
.B -no_footnode | |
Same as setting: | |
.I $NO_FOOTNODE = 1; | |
Suppresses use of a separate file for footnotes; instead these are | |
placed at the bottom of the | |
.B 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 | |
.B LaTeX, | |
using code such as follows. | |
\\renewcommand{\\thefootnote}{\\arabic{footnote}} | |
All the styles \\arabic, \\alph, \\roman, \\Alph and \\Roman are available. | |
.TP | |
.B -numbered_footnotes | |
Same as setting: | |
.I $NUMBERED_FOOTNOTES = 1; | |
If this is set you will get every footnote applied with a subsequent | |
number, to ease readability. | |
.TP | |
.B -address <author-address> | |
Same as setting: | |
.I $ADDRESS = "<author-address>"; | |
Sign each page with this address. | |
See latex2html.config for an example using | |
.B Perl | |
code to automatically | |
include the date. | |
A user-defined | |
.B Perl | |
subroutine called &custom_address can be used | |
instead, if defined; it takes the value of | |
.I $ADDRESS | |
as a parameter, | |
which may be used or ignored as desired. At the time when this | |
subroutine will be called, variables named $depth, | |
.I $title, | |
.I $file | |
hold | |
the sectioning-level, title and filename of the | |
.B HTML | |
page being | |
produced; | |
.I $FILE | |
holds the name of the filename for the title-page of | |
the whole document. | |
.TP | |
.B -info <string> | |
Same as setting: | |
.I $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. | |
.SH Switches controlling Image Generation | |
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. | |
.TP | |
.B -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. | |
.TP | |
.B -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''. | |
.TP | |
.B -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. | |
.TP | |
.B -use_luadvi | |
Generate intermediate images with dvilualatex instead of plain latex. | |
Useful for dvilualatex documents which cannot be translated by latex. | |
.TP | |
.B -ascii_mode | |
Same as setting: | |
.I $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). | |
.TP | |
.B -nolatex | |
Same as setting: | |
.I $NOLATEX = 1; | |
Disable the mechanism for passing unknown environments to | |
.B 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.) | |
.TP | |
.B -external_images | |
Same as setting: | |
.I $EXTERNAL_IMAGES = 1; | |
Instead of including any generated images inside the document, leave | |
them outside the document and provide hypertext links to them. | |
.TP | |
.B -ps_images | |
Same as setting: | |
.I $PS_IMAGES = $EXTERNAL_IMAGES = 1; | |
Use links to external PostScript files rather than inlined images in | |
the chosen graphics format. | |
.TP | |
.B -discard | |
Same as setting: | |
.I $DISCARD_PS = 1; | |
The temporary PostScript files are discarded immediately after they | |
have been used to create the image in the desired graphics format. | |
.TP | |
.B -no_images | |
Same as setting: | |
.I $NO_IMAGES = 1; | |
Do not attempt to produce any inlined images. The missing images can be | |
generated ``off-line'' by restarting | |
.B LaTeX2HTML | |
with the option | |
-images_only . | |
.TP | |
.B -images_only | |
Same as setting: | |
.I $IMAGES_ONLY = 1; | |
Try to convert any inlined images that were left over from previous | |
runs of | |
.B LaTeX2HTML. | |
.TP | |
.B -reuse <reuse_option> | |
Same as setting: | |
.I $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 | |
.B 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. | |
.TP | |
.B -no_reuse | |
Same as setting: | |
.I $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.) | |
.TP | |
.B -antialias | |
Same as setting: | |
.I $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. | |
.TP | |
.B -antialias_text | |
Same as setting: | |
.I $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. | |
.TP | |
.B -no_antialias | |
Same as setting: | |
.I $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. | |
.TP | |
.B -no_antialias_text | |
Same as setting: | |
.I $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. | |
.TP | |
.B -white | |
Same as setting: | |
.I $WHITE_BACKGROUND = 1; (Default is 1.) | |
Ensures that images of figure environments have a white background. | |
Otherwise transparency effects may not work correctly. | |
.TP | |
.B -no_white | |
Same as setting: | |
.I $WHITE_BACKGROUND = ''; (Default is 1.) | |
Cancels the requirement that figure environments have a white | |
background. | |
.TP | |
.B -ldump | |
Same as setting: | |
.I $LATEX_DUMP = 1; (Default is 0.) | |
Use this if you want to speed up image processing during the 2nd and | |
subsequent runs of | |
.B LaTeX2HTML | |
on the same document. The translator now | |
produces a | |
.B LaTeX | |
format-dump of the preamble to images.tex which is | |
used on subsequent runs. This significantly reduces the startup time | |
when | |
.B LaTeX | |
reads the images.tex file for image-generation. | |
This process actually consumes additional time on the first run, since | |
.B 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. | |
.SH Switches controlling Navigation Panels | |
The following switches govern whether to include one or more navigation | |
panels on each | |
.B HTML | |
page, also which buttons to include within such a panel. | |
.TP | |
.B -no_navigation | |
Same as setting: | |
.I $NO_NAVIGATION = 1; | |
Disable the mechanism for putting navigation links in each page. | |
This overrides any settings of the | |
.I $TOP_NAVIGATION, | |
.I $BOTTOM_NAVIGATION | |
and | |
.I $AUTO_NAVIGATION | |
variables. | |
.TP | |
.B -top_navigation | |
Same as setting: | |
.I $TOP_NAVIGATION = 1; | |
Put navigation links at the top of each page. | |
.TP | |
.B -bottom_navigation | |
Same as setting: | |
.I $BOTTOM_NAVIGATION = 1; | |
Put navigation links at the bottom of each page as well as the top. | |
.TP | |
.B -auto_navigation | |
Same as setting: | |
.I $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 | |
.I $WORDS_IN_PAGE | |
number of words | |
(default = 450). | |
.TP | |
.B -next_page_in_navigation | |
Same as setting: | |
.I $NEXT_PAGE_IN_NAVIGATION = 1; | |
Put a link to the next logical page in the navigation panel. | |
.TP | |
.B -previous_page_in_navigation | |
Same as setting: | |
.I $PREVIOUS_PAGE_IN_NAVIGATION = 1; | |
Put a link to the previous logical page in the navigation panel. | |
.TP | |
.B -contents_in_navigation | |
Same as setting: | |
.I $CONTENTS_IN_NAVIGATION = 1; | |
Put a link to the table-of-contents in the navigation panel if there is | |
one. | |
.TP | |
.B -index_in_navigation | |
Same as setting: | |
.I $INDEX_IN_NAVIGATION = 1; | |
Put a link to the index-page in the navigation panel if there is an | |
index. | |
.SH Switches for Linking to other documents | |
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. | |
.TP | |
.B -up_url <URL> | |
Same as setting: | |
.I $EXTERNAL_UP_LINK = "<URL>"; | |
Specifies a universal resource locator (URL) to associate with the | |
``UP'' button in the navigation panel(s). | |
.TP | |
.B -up_title <string> | |
Same as setting: | |
.I $EXTERNAL_UP_TITLE = "<string>"; | |
Specifies a title associated with this URL. | |
.TP | |
.B -prev_url <URL> | |
Same as setting: | |
.I $EXTERNAL_PREV_LINK = "<URL>"; | |
Specifies a URL to associate with the ``PREVIOUS'' button in the | |
navigation panel(s). | |
.TP | |
.B -prev_title <string> | |
Same as setting: | |
.I $EXTERNAL_PREV_TITLE = "<string>"; | |
Specifies a title associated with this URL. | |
.TP | |
.B -down_url <URL> | |
Same as setting: | |
.I $EXTERNAL_DOWN_LINK = "<URL>"; | |
Specifies a URL for the ``NEXT'' button in the navigation panel(s). | |
.TP | |
.B -down_title <string> | |
Same as setting: | |
.I $EXTERNAL_DOWN_TITLE = "<string>"; | |
Specifies a title associated with this URL. | |
.TP | |
.B -contents <URL> | |
Same as setting: | |
.I $EXTERNAL_CONTENTS = "<URL>"; | |
Specifies a URL for the ``CONTENTS'' button, for document segments that | |
would not otherwise have one. | |
.TP | |
.B -index <URL> | |
Same as setting: | |
.I $EXTERNAL_INDEX = "<URL>"; | |
Specifies a URL for the ``INDEX'' button, for document segments that | |
otherwise would not have an index. | |
.TP | |
.B -biblio <URL> | |
Same as setting: | |
.I $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 (_). | |
.SH Switches for Help and Tracing | |
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 | |
.B LaTeX2HTML | |
to generate more output to the screen. These extra messages | |
should help to locate the cause of the problem. | |
.TP | |
.B -tmp <path> | |
Define a temporary directory to use for image generation. If <path> is | |
0, the standard temporary directory /tmp is used. | |
.TP | |
.B -h(elp) | |
Print out the list of all command-line options. | |
.TP | |
.B -v | |
Print the current version of | |
.B LaTeX2HTML. | |
.TP | |
.B -debug | |
Same as setting: | |
.I $DEBUG = 1; | |
Run in debug-mode, displaying messages and/or diagnostic information | |
about files read, and utilities called by | |
.B LaTeX2HTML. | |
Shows any | |
messages produced by these calls. | |
More extensive diagnostics, from the | |
.B Perl | |
debugger, can be obtained by | |
appending the string `-w-' to the 1st line of the latex2html (and | |
other) | |
.B Perl | |
script(s). | |
.TP | |
.B -verbosity <num> | |
Same as setting: | |
.I $VERBOSITY = <num>; | |
Display messages revealing certain aspects of the processing performed | |
by | |
.B 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. | |
.TP | |
0. | |
No special tracing; as for versions of | |
.B LaTeX2HTML | |
prior to V97.1. | |
.TP | |
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. | |
.TP | |
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. | |
.TP | |
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. | |
.TP | |
4. | |
Indicate command-substitution the pre-process of | |
math-environments. Print the contents of unknown environments for | |
processing in | |
.B LaTeX, | |
both before and after reverting to | |
.B LaTeX | |
source. Show all operations affecting the values of counters. Also | |
show links, labels and sectioning keys, at the stages of | |
processing. | |
.TP | |
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. | |
.TP | |
6. | |
Show replacements of new commands, accents and wrapped commands. | |
.TP | |
7. | |
Trace the processing of commands in math mode; both before and | |
after. | |
.TP | |
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 | |
.I $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>}. | |
.SH Other Configuration Variables, without switches | |
The configuration variables described here do not warrant having a | |
command-line switch to assign values. Either they represent aspects of | |
.B 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. | |
.TP | |
.B $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. | |
.TP | |
.B $LATEX2HTMLDIR | |
Read by the install-test script from latex2html.config, its value is | |
inserted into the latex2html | |
.B Perl | |
script as part of the installation | |
process. | |
.TP | |
.B $LATEX2HTMLSTYLES = "$LATEX2HTMLDIR/styles"; | |
Read from the latex2html.config file by install-test, its value is | |
checked to locate the styles/ directory. | |
.TP | |
.B $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. | |
.TP | |
.B $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. | |
.TP | |
.B $TEXEXPAND = "$LATEX2HTMLDIR/texexpand"; | |
Read by the install-test | |
.B Perl | |
script from latex2html.config, its value | |
is used to locate the texexpand | |
.B Perl | |
script. | |
.TP | |
.B $PSTOIMG = "$LATEX2HTMLDIR/pstoimg"; | |
Read by the install-test | |
.B Perl | |
script from latex2html.config, its value | |
is used to locate the pstoimg | |
.B Perl | |
script. | |
.TP | |
.B $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. | |
.TP | |
.B $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: | |
.RS | |
.RS | |
.P | |
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. | |
.P | |
to prepend a path to a different version of dvips than normally | |
available as the system default (e.g. the printing requirements | |
are different). | |
.P | |
to append debugging switches, in case of poor quality images; | |
one can see which paths are being searched for fonts and other | |
resources. | |
.P | |
to prepend commands for setting path variables that dvips may need | |
in order to locate fonts or other resources. | |
.RE | |
.P | |
If automatic generation of fonts is required, using Metafont, the | |
following configuration variables are important. | |
.TP | |
.B $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). | |
.TP | |
.B $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. | |
.TP | |
.B $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. | |
.RE | |
.TP | |
.B $LATEX = 'latex'; | |
Read from latex2html.config by install-test, its value is checked to | |
locate the latex program or script. | |
If | |
.B 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. | |
.I $LATEX = 'setenv TEXINPUTS <path to search> ; latex' . | |
There are several variables to help control exactly which files are | |
read by | |
.B LaTeX2HTML | |
and by | |
.B LaTeX | |
when processing images: | |
.RS | |
.TP | |
.B $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. | |
.TP | |
.B $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.) | |
.TP | |
.B $DO_INCLUDE = ''; | |
List of exceptions within the | |
.I $DONT_INCLUDE | |
list. These files are | |
to be read if requested by an \\input or \\include command. | |
.RE | |
.TP | |
.B $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 | |
.B HTML | |
files and other generated images, the value of | |
$ICONSERVER is not needed within the | |
.B HTML | |
files themselves. | |
.TP | |
.B $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. | |
.TP | |
.B $LINKNAME = '"index.$EXTN"'; | |
This is used when the | |
.I $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 | |
.B HTML | |
file which will | |
be automatically linked to the directory name. | |
The value of | |
.I $EXTN | |
is .html unless | |
.I $SHORTEXTN | |
is set, in which case it | |
is .htm . | |
.TP | |
.B $LINKPOINT = '"$FILE$EXTN"'; | |
This specifies the name of the | |
.B HTML | |
file to be duplicated, or | |
symbolically linked, with the name specified in | |
.I $LINKNAME. | |
At | |
the appropriate time the value of | |
.I $FILE | |
is the document name, which | |
usually coincides with the name of the working directory. | |
.TP | |
.B $CHARSET = 'utf-8'; | |
This specifies the character set used within the | |
.B HTML | |
pages produced by | |
.B LaTeX2HTML. | |
If no value is set in a configuration or initialisation | |
file, the default value will be assumed. The lowercase form | |
.I $charset | |
is | |
also recognised, but this is overridden by the uppercase form. | |
.TP | |
.B $ACCENT_IMAGES = 'large'; | |
Accented characters that are not part of the ISO-Latin fonts can be | |
generated by making an image using | |
.B LaTeX. | |
This variable contains a | |
(comma-separated) list of | |
.B 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. | |
.P | |
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 | |
.I $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. | |
.P | |
.B $RGBCOLORFILE = 'rgb.txt'; | |
.P | |
.B $CRAYOLAFILE = 'crayola.txt'; | |
.P | |
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. | |
.TP | |
.B $default_language = 'english'; | |
This establishes which language code is to be placed within the | |
<!DOCTYPE ... > tag that may appear at the beginning of the | |
.B HTML | |
pages | |
produced. Loading a package for an alternative language can be expected | |
to change the value of this variable. | |
See also the | |
.I $TITLES_LANGUAGE | |
variable, described next. | |
.TP | |
.B $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 | |
.I $default_language | |
variable described above. | |
.TP | |
.B $WORDS_IN_NAVIGATION_PANEL_TITLES = 4; | |
Specifies how many words to use from section titles, within the textual | |
hyperlinks which accompany the navigation buttons. | |
.TP | |
.B $WORDS_IN_PAGE = 450; | |
Specifies the minimum page length required before a navigation panel is | |
placed at the bottom of a page, when the | |
.I $AUTO_NAVIGATION | |
variable is | |
set. | |
.TP | |
.B $CHILDLINE = \(dq<BR><HR>\\\\n\(dq; | |
This gives the | |
.B HTML | |
code to be placed between the child-links table and | |
the ordinary contents of the page on which it occurs. | |
.TP | |
.B $NETSCAPE_HTML = 0; | |
When set, this variable specifies that | |
.B 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. | |
.TP | |
.B $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. | |
.TP | |
.B $INTERLACE = 1; | |
When set, interlaced images should be produced. | |
This requires graphics utilities to be available to perform the | |
interlacing operation. | |
.TP | |
.B $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. | |
.TP | |
.B $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 | |
.I $MATH_SCALE_FACTOR | |
and | |
$DISP_SCALE_FACTOR to specify scaling. | |
.TP | |
.B $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. | |
.TP | |
.B $DISP_SCALE_FACTOR = 1; | |
Extra scale factor applied to images of displayed math environments. | |
When set, this value multiplies | |
.I $MATH_SCALE_FACTOR | |
to give the total | |
scaling. A value of `1.2' is a good choice to accompany | |
$MATH_SCALE_FACTOR = 1.4;. | |
.TP | |
.B $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 | |
.I $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. | |
.TP | |
.B $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 | |
.I $DISP_SCALE_FACTOR | |
scaling factors are being | |
used, else some images may become excessively large, including a lot of | |
blank space. | |
.TP | |
.B $LINE_WIDTH = 500; | |
Formerly specified the width of an image, when the contents were to be | |
right- or center-justified. (No longer used.) | |
.PP | |
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 | |
.B Perl | |
script and stored within | |
.I $LATEX2HTMLDIR/local.pm | |
as | |
.B 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. | |
.PP | |
$GS_LIB = '/usr/local/share/ghostscript/4.02'; | |
$PNMCAT = '/usr/local/bin/pnmcat'; | |
$PNMQUANT = '/usr/local/bin/pnmquant'; | |
$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'; | |
.SH "SEE ALSO" | |
.BR latex (1) | |
.SH AUTHOR | |
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. |