Overview

This manual describes the L^ATEX2HTML translator which is used to create Web pages from document source written for the L^ATEX typesetting system, or simply containing L^ATEX commands.

To use L^ATEX2HTML to translate a file <file>.tex containing L^ATEX commands, simply type:

latex2html <file>.tex

This will create a new directory called <file> which will contain the generated HTML files, some log files and possibly some images.

Basically the translator reads the source document and creates a linked set of HTML pages, displaying the information it contains. The L^ATEX commands and environments that are found are interpreted either as “markup” instructions, or as macros expanding into more text or markup commands. Where such markup corresponds to the intended use for markup tags in the HTML language, a direct translation is made. If there is no natural way to present the information using simple text embellished with HTML markup tags, then an image is generated, using L^ATEX itself to interpret the portion of code.

Of course this is a drastically over-simplified description of what L^ATEX2HTML actually does. Many questions spring readily to mind. The answers to these and the options available to handle particular situations are discussed elsewhere in this manual.

• What does “natural way to present the information” really mean?

Text and paragraphing clearly should appear as such, whether printed or on-screen. Different font sizes and styles such as “bold-face” or “italic” are generally rendered accordingly. However, whereas L^ATEX has access to appropriate fonts for specialised purposes such as mathematical symbols, these cannot be guaranteed to be available with all Web-browsers. So for information requiring such things, L^ATEX2HTML will generally resort to making an image, using L^ATEX itself to typeset the material required for that image.

The next page contains a brief overview of how L^ATEX's standard environments are handled within L^ATEX2HTML. It also mentions some of the extra features that are available.
In general L^ATEX2HTML attempts to use textual constructions to represent the required information. Generation of an image is done only when there is no adequate textual construction with the required version of HTML, or when specifically requested to do so. Various extensions, to cope with the different HTML versions and extra features, are discussed elsewhere. That describes what to expect on the HTML pages, with little or no changes required to the L^ATEX source.

Just as L^ATEX has various packages which can be used to present specific types of information in appropriate ways, so is L^ATEX2HTML capable of handling the commands from many of these packages. See this table for a listing of those packages which currently have special support.

• Some features of HTML have no direct counterpart in a L^ATEX typeset document.
  Can such features be used with L^ATEX2HTML?

Any effect currently available with any version of the HTML standard can be specified for a document processed by L^ATEX2HTML. New L^ATEX commands are defined in the html.sty package; the features that these commands allow are the subject of a whole section of this manual. Some of the new commands provide improved strategies for effects already existing in L^ATEX; e.g. cross-references and citations. To use these effectively requires only small changes to the L^ATEX source.

Other commands define new environments which are completely ignored when processed by L^ATEX. Indeed the full scope of HTML 3.2 is available, using L^ATEX-like macros to help structure the source, reduce the tedium of repetitious use of tags, and ensure that all appropriate tags are correctly closed.

• What determines the amount of information that goes onto a single HTML page?
  How are different pages linked?

The HTML pages can contain whole chapters, sections, (sub)subsections or (sub)paragraphs. This is fully customisable using the command-line options discussed in detail in a separate section of this manual.

• Does the original document have to be a valid L^ATEX document, typesetting without errors? If not, does it help if it is?

In fact any document can be fed to the L^ATEX2HTML processor, but it is designed specifically to recognise and sensibly translate the intentions expressed by L^ATEX markup commands. Although sensible results can be obtained even when the L^ATEX source is not valid, the most reliable translations are obtained when it is. Relevant issues are discussed in a later section.

• When developing a document which contains special HTML features, is it best to regularly test it in L^ATEX or with L^ATEX2HTML?

The answer to such a question changes as the developer gains more experience with the available tools. Some aspects to be considered are discussed in a later section of this manual.

Information relevant to obtaining the latest version of L^ATEX2HTML, installation within the local environment, and where to look for help when things do not go as expected, can be found in the support section.

What follows next is a brief summary of the features supported within L^ATEX2HTML....

List of Features

Following is a listing of the main features of the translator; more specific details on these is given elsewhere in this manual.

The L^ATEX2HTML translator ...

• breaks up a document into one or more components as specified by the user¹;

• provides optional, customisable iconic navigation panels on every page which contain links to other parts of the document, or other documents;

• handles inlined equations ( $\sum_{{i=1}}^{{n}}$x_i = $\int_{{0}}^{{1}}$f), handles equation alignment ( A_BC+D), right-justified numbered equations (see example), tables (see example), figures (see example), and any arbitrary environment. Either the complete environment or sub-parts thereof... are passed to L^ATEX for conversion to images, which are then either included in the document or are made available through hypertext links.

• figures or tables can be arbitrarily scaled and oriented, and shown either as inlined images or “thumbnail” sketches... or their contents displayed within a table constructed using the <TABLE> tags of HTML 3.2.

• theorem-like environments are supported, along with automatic numbering and counter dependencies.

• can produce output suitable for browsers that support inlined images or character-based browsers (as specified by the user). In particular the TEX or L^ATEX code for mathematical expressions and formulas will be displayed in character-based browsers, such as lynx.

• coloured text and/or background is fully supported, as is the ability to use an image to create a tiled backdrop.

• handles definitions of new commands, environments and counters even when these are defined in external files for input²;

• handles footnotes³, tables of contents, lists of figures and tables, bibliographies and can generate an index. By including hyperlinks between index entries, simple navigation aids can be built into the index, for easy browsing.

• automatically translates cross-references and citations into hyper-links, and extends the L^ATEX cross-referencing mechanism to work not just within a document but between documents which may reside in remote locations;

• translates L^ATEX accent and special character commands (e.g. Â Ø ö £ © ¶) to the equivalent ISO–Latin–1 or Unicode character set, else an image can be created;

• recognises hypertext links (to multi-media resources or arbitrary Internet services such as sound, video, ftp, http, news) and links which invoke arbitrary program scripts—all expressed as L^ATEX commands;

• recognises conditional text which is intended only for the hypertext version, or only for the paper (.dvi) version;

• can include raw HTML in a L^ATEX document (e.g. in order to specify interactive forms);

• can deal sensibly with at least the Common L^ATEX Commands summarised at the back of
  virtually all of the concepts and commands described in the L^ATEX blue book, where there is a meaningful interpretation appropriate to an HTML document. Also many other L^ATEX constructions are handled, including many described in the L^ATEX Companion and L^ATEX Graphics Companion (e.g. X_Y-pic);

• can be configured to translate equations either as GIF images or as HTML 3.0 mark-up (as browsers become available which are suitable for the task), or by making images of subparts of equations, as required.

• links symbolic references across document segments which have been independently processed;

• will try to translate any document with embedded L^ATEX commands, irrespective of whether it is complete or syntactically legal.