NAME
latex2html - translate LaTeX files to HTML (HyperText Markup
Language)
SYNOPSIS
latex2html [-split num] [-link num] [-nolatex] [-t
top_page_title] [-dir output_directory] [-address
author_address] [-info string] [-h ] filename...
DESCRIPTION
Latex2html is a Perl program that translates LaTeX source
files into HTML. For each source file given as an argument
the translator will create a directory containing the
corresponding HTML files.
The translator:
o breaks up a document into sectioning components,
o provides a 'next', 'previous', and 'up' navigation
panel on every page,
o handles equations, tables, figures, and any arbitrary
environments by passing them to LaTeX and including
them as HTML inlined images,
o handles definitions of new commands, environments, and
theorems (this opens up the possibility of defining
HTML macros in LaTeX!),
o handles footnotes, tables of contents, lists of figures
and tables, bibliographies and can generate an index,
o translates cross-references into hyperlinks,
o provides hooks for including arbitrary links (internal
to the document or external) as LaTeX commands
o can deal sensibly at least with the Common LaTeX
commands summarized at the back of the LaTeX blue book
[1].
o will try and translate any document with embedded LaTeX
commands irrespective of whether it is complete or
syntactically legal.
OPTIONS
-split num
Stop splitting sections into separate files at this
depth. A value of 0 will put the document into a
single HTML file. The default is 8.
-link num
Stops revealing child nodes at each node at this depth.
(A node is a section/subsection/subsubsection etc.). A
value of 0 will show NO links to child nodes, a value
of 1 will show only the immediate child nodes, etc. A
value at least as big as that of the -split option will
produce a table of contents for the tree structure,
rooted at each given node. The default is 4.
-nolatex
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 without fancy figures,
equations or tables.
-t top_page_title
Name the document using this title.
-dir output_directory
Redirect the output to this directory.
-address author_address
Sign each page with this address.
-info string
Generate a new section "About this document ..."
containg more information about the document being
translated. The default is to generate 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.
-h Print out the list of options.
PROBLEMS
Correctness and Efficiency
The translator cannot be guaranteed to perform as
expected. Apart from possible bugs the translator may
place heavy demands on your resources.
Unrecognized Commands and Environments
As mentioned earlier the translator can handle at least
the Common LaTeX commands summarized at the back of the
LaTeX blue book [1]. Although it is very easy to extend
the command and environment set, there is currently no
way of doing so, short of modifying the Perl script.
Unrecognized commands are ignored and any arguments are
left in the text. Unrecognized environments are passed
to LaTeX and the result is included in the document as
one or more inlined images.
Cross-references
Obviously it is not possible to deal with explicit
(hard-wired) cross-references that do not use the
'label' - 'ref' mechanism. Such references are left
dangling. References from an environment that is passed
to for processing (e.g. a 'cite', or a 'ref' command),
are ignored unless they occur in a caption. In the
latter case a link will be active but not in the actual
caption in the main document (this will be part of the
inlined image) but in the caption in the list of
Figures or the list of Tables.
In some instances it would be more appropriate to use
numeric references rather than active links e.g. when
there are references to several axioms or theorems.
Bibliographic References
Unless the bibliography is constructed manually (using
the 'thebibliography' environment), the translator
requires an up to date <file>.bbl for each <file> input
argument. The bbl file should be present in the same
directory as <file>.
Index
The translator generates its own index by saving the
arguments of the index command. The contents of the
'theindex' environment and the 'printindex' command are
ignored.
Foreign Characters
Are not supported.
New Definitions
New definitions ('newcommand', 'newenvironment', and
'newtheorem' will not work as expected if they are
defined more than once. Only the last definition is
used throughout the document.
Scope of declarations and environments
If the scope of a declaration or environment crosses
section boundaries, then the output will not be as
expected, because each section is processed
independently.
Postscript to GIF conversion
The conversion from postscript to the GIF format is
done partly through gs (ghostscript). The conversion
will not work if gs is invoked with the -dSAFER option.
Also, the result of the conversion may be poor.
AUTHOR
Nikos Drakos, Computer Based Learning Unit, University of
Leeds. (nikos@cbl.leeds.ac.uk) Several other people have
contributed suggestions, ideas, solutions, support and
encouragement.
Some of these are Roderick Williams, Ana Maria Paiva, Jamil
Sawar and Andrew Cole here at the Computer Based Learning
Unit of the University of Leeds.
The idea of splitting LaTeX files into more than one
components linked with hyperlinks came from a Perl script
written by Toni Lantunen at CERN. Thanks to Robert Cailliau
of the World Wide Web Project also at CERN for giving me
access to the source code and documentation.
REFERENCES
[1] Leslie Lamport. LATEX User's Guide & Reference Manual.
Addison-Wesley Publishing Company, Inc., 1986.