Developing Documents using L^ATEX2HTML

Although any document containing L^ATEX commands can be translated by the L^ATEX2HTML translator, the best results are obtained when that document is itself a valid L^ATEX document. Indeed it is generally a good idea to develop documents so that they produce good readable results in both the L^ATEX 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.

L^ATEX macros:

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

 

error checking:

Processing the document first using L^ATEX is the easiest, and quickest, way to check for valid syntax.
Whereas L^ATEX stops at each error (when run in interactive mode), allowing a fix to be made ``on the spot'' or a ``stop-fix-restart'', L^ATEX2HTML does not stop when it detects an error in L^ATEX 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 L^ATEX before attempting to use the L^ATEX2HTML translator.

Furthermore, L^ATEX 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 L^ATEX2HTML actually handles better than L^ATEX (or rather, the underlying TEX processor). Whereas TEX only detects an error when something else goes wrong later in the processing, L^ATEX2HTML shows where the unmatched brace itself occurs.

 

auxiliary file:

Some information that L^ATEX2HTML 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 L^ATEX run is required to produce the .aux file.

Of course if no information in the .aux file is actually used, then this L^ATEX 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 L^ATEX 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. L^ATEX2HTML reads citation information from the .aux file, and can import the bibliography itself from the .bbl file. However these must first be created using L^ATEX.

 

document segmentation:

With the document segmentation technique, discussed fully in a later section, it is vitally important that the full document processes correctly in L^ATEX. The desired effect is that of a single large document, whereas the pieces will actually be processed separately. To achieve this, L^ATEX writes vital information into special .ptr files. Like the .aux file, these files are read by L^ATEX2HTML 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.)