next up previous contents index
Next: Command-Line Options Up: Customising the Layout of Previous: Customising the Layout of   Contents   Index

Developing Documents using LATEX2HTML

Although any document containing LATEX commands can be translated by the LATEX2HTML translator, the best results are obtained when that document is itself a valid LATEX document. Indeed it is generally a good idea to develop documents so that they produce good readable results in both the LATEX typeset version as well as a set of HTML pages. This is not just a nicety; there are several good practical reasons for doing this.

* LATEX macros:
The macro commands that LATEX2HTML recognises are based upon corresponding commands for LATEX. If one tries to use syntax that is incorrect for LATEX then there is no reason why LATEX2HTML should be able to ``get it right'', by somehow recognising the true intent.

* error checking:
Processing the document first using LATEX is the easiest, and quickest, way to check for valid syntax.
Whereas LATEX stops at each error (when run in interactive mode), allowing a fix to be made ``on the spot'' or a ``stop-fix-restart'', LATEX2HTML does not stop when it detects an error in LATEX syntax. Useful messages are given concerning missing or unmatched braces, but other apparent anomalies generate only warning messages, which are saved to the end. (Some warnings are also shown immediately when the $VERBOSITY variable is set to at least 3.)
In practice it can be much quicker to test for invalid syntax using LATEX before attempting to use the LATEX2HTML translator.

Furthermore, LATEX warns of cross-reference labels that have not been defined. This is useful to help avoid having hyperlinks which point to nowhere.

The case of missing braces, or an unmatched opening brace, is an error that LATEX2HTML actually handles better than LATEX (or rather, the underlying TEX processor). Whereas TEX only detects an error when something else goes wrong later in the processing, LATEX2HTML shows where the unmatched brace itself occurs.

* auxiliary file:
Some information that LATEX2HTML might need is normally read from the .aux file for the document being processed; or perhaps from the .aux file of a different document, of which the current document is just a portion. Clearly a valid LATEX run is required to produce the .aux file.

Of course if no information in the .aux file is actually used, then this LATEX run can be neglected. Also, if the .aux file has already been created, and edits are made on the source which do not alter the information stored within the .aux file, then there is no need for a fresh LATEX run (except for the purposes of error-checking).

* bibliography:
Suppose the document requires a bibliography, or list of references, which is to be prepared using BibTEX. LATEX2HTML reads citation information from the .aux file, and can import the bibliography itself from the .bbl file. However these must first be created using LATEX.

* document segmentation:
With the document segmentation technique, discussed fully in a later section, it is vitally important that the full document processes correctly in LATEX. The desired effect is that of a single large document, whereas the pieces will actually be processed separately. To achieve this, LATEX writes vital information into special .ptr files. Like the .aux file, these files are read by LATEX2HTML to get section-numbering and other information to be used while processing each segment.

* print quality:
When a document contains automatically-generate images, these images are usually bitmaps designed for viewing on-screen. In general the resolution of these is too poor to give a good result when printed on a high-resolution laser-printer. Thus if it is likely that the reader will want to obtain a printed version of your document, then it is best to include a hyperlink to the typeset .dvi version, or to a PostScript conversion of the .dvi file. (In either case, a link to a compressed version is even better.)

next up previous contents index
Next: Command-Line Options Up: Customising the Layout of Previous: Customising the Layout of   Contents   Index
Rob MacLeod 2004-10-10