2  TeX and TeX2page commands

A TeX document is a text file. Most of the text represents the content of the document, but a few characters are used specially to embed markup commands within the text. The TeX program, which recognizes a list of primitive commands, along with a format file that defines some additional commands, reads the text file, and uses the markup commands in the text to create an appropriately typeset version of the document in a DVI file, which can then be printed.

TeX2page understands many of the commands of TeX. It uses this understanding to convert a TeX document to its HTML version, much the same way that TeX converts the same document into its DVI version. TeX2page can process documents written in both the plain TeX [8] and LaTeX [9] formats.⁴ With the aid of a macro file texinfo.t2p (sec 2.2), TeX2page can also process Texinfo documents.

TeX2page silently ignores TeX commands that it does not understand, and often this is precisely the right treatment. Eg, it is acceptable to ignore commands such as \leavevmode, \noindent, \/, and \- when creating an HTML document from TeX source.

While TeX2page will attempt gamely to process any TeX definitions that you use in your document (perhaps by \inputting external TeX macro files), it is usually a good idea to have them explicitly ignored (sec 8). Eg, you can use macros for generating double columns -- while this is a great paper-saver for your printed copy, it is generally not important for the HTML version and so is no loss if ignored by TeX2page.

2.1  tex2page.tex and tex2page.sty

TeX2page also processes some TeX-like commands that are not present by default in the TeX formats. These include commands that are specific to HTML and its hyperlinks; commands for verbatim text, with special emphasis on syntax highlighting for computer-language fragments; and some rarely used (indeed discouraged) but sometimes unavoidable directives (sec 8) that allow TeX2page and TeX to produce differing content. If you use these commands in your document, and you want your document to still be processable by TeX, you need to supply some workable TeX definitions for them -- even if they do not quite produce the same effect in the DVI output as they do in the HTML output. Such definitions are provided in the macro file tex2page.tex. It may be included in your TeX document as

\input tex2page  

LaTeX users may alternatively access the macros of tex2page.tex via the file tex2page.sty, which has a name that fits better with LaTeX's \usepackage command:

\usepackage{tex2page} % if document is in LaTeX

This ensures that your document can be processed by both TeX2page and TeX.

As we have seen above, the language recognized by TeX2page is a combination of plain TeX and LaTeX. Most plain TeX commands are available to the LaTeX user; however the reverse is certainly not the case. This means that a plain TeX user of TeX2page can use quite a few LaTeX commands in his source that are processable by TeX2page but not by plain TeX. In the interest of generality, the file tex2page.tex includes some plain TeX definitions for these LaTeX commands.⁵ You can either choose not to use these commands or override their definitions in tex2page.tex with your own, better, definitions.

Note that TeX2page itself does not need the file tex2page.tex. Rather, plain TeX and LaTeX need the tex2page.tex macros in order to process files written using the extra notation supported by TeX2page. If your document does not use this extra notation, then you can do without tex2page.tex.

2.2  The .t2p file

Before processing a TeX document, TeX2page will automatically load a file with the same basename as the TeX main file but with extension .t2p, if this file exists. This is a good place to put HTML-specific definitions for the document without making changes in the document itself.

.t2p files are especially valuable when HTMLizing legacy or third-party documents without compromising their authenticity, integrity, and timestamp. .t2p files can also be used to adapt TeX2page to other formats of TeX besides plain TeX and LaTeX. For example, the file texinfo.t2p (provided in the distribution) helps TeX2page process Texinfo [4] documents.

Note that the definitions in the .t2p file are processed before the main file. But it often makes sense to activate these definitions sometime later. Eg, activating the .t2p definitions after the preamble in a LaTeX document allows you to redefine the preamble macros in a manner that is appropriate for HTML. Here is a technique for accomplishing this:

\let\PRIMdocument\document

\def\document{
... HTML-specific definitions ...
\PRIMdocument}

This code, which goes in the .t2p file, redefines the \document command to include a hook that loads some HTML-specific definitions. Since the \document command is called right after the preamble, the definitions introduced by the hook will shadow the preamble macros, as intended.

Sample .t2p files are provided in the t2p-example subdirectory in the TeX2page distribution.