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 [23]
and LaTeX [25] formats.4
TeX2page also recognizes some commonly used macros
that are loaded from external macro files or LaTeX
packages. With
the aid of a macro file texinfo.t2p
(section 2.2), TeX2page can also process
Texinfo documents [12].
TeX2page silently ignores non-mathematical 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
\input
ting external TeX macro files), it is
usually a good idea to have them explicitly ignored
(section 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.
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 (section 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
.
.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 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 may be found in the TeX2page
distribution.
4
TeX2page processes both plain TeX
and LaTeX commands, without the need for a format file
parameter. It can even process documents written in a
mix of plain TeX and LaTeX. This is not an uncommon
scenario, with LaTeX users frequently using plain TeX
commands, and plain TeX users frequently implementing
their own version of sectioning and other commands
using the LaTeX names. In the few cases where the same
command name (eg, \footnote
) is used in both
formats but with different behavior, TeX2page will
choose the correct behavior based on which format it
thinks the overall document is in. The plain TeX and
LaTeX document structures are sufficiently different
(as human readers can readily testify by reading just a
few opening lines) to allow this disambiguation.