4  TeX​ ​commands with a difference

Most TeX​ ​commands, whether from the format or from macro files, are translated into an obvious HTML equivalent, and therefore need no further description than what is available in the TeX​ ​and LaTeX​ ​manuals. However, some commands are treated specially. We now turn to these commands.

Multiple pages

Unlike TeX, TeX2page does not automatically split the document into pages at regular vertical lengths. TeX2page will start a new HTML page only at \chapter commands and at explicit page break commands such as \eject or LaTeX’s \clearpage. It is possible to disable pagebreaks entirely with the \TZPsinglepage flag (p. 6).

(It is advisable to place a \vfill before \eject so the DVI document doesn’t cause the pre-\eject text to increase its interparagraph space unsightlily in order to fill the physical page.)

Conditionals may be used to specify page breaks for only the DVI output, or for only the HTML output.

By default, TeX2page will generate a navigation bar at the top and at the bottom of each HTML page, with links to the first, previous, and next page. If the document has a table of contents or an index, links to the pages containing these elements are also included in the navigation bar. The nav bar is customizable if you set the \TZPtexlayout flag (p. 6).

Table of contents

TeX2page recognizes LaTeX’s \tableofcontents and Eplain’s \readtocfile, both of which list the table of contents (ToC). Each section name in the ToC links to the page on which the section occurs. In LaTeX, the ToC lists the numbered section names in the document, upto the depth specified by the count \tocdepth.

In formats other than LaTeX, the user would have to define section commands that explicitly wrote to the ToC. A helper macro for this is \writenumberedtocline, whose three arguments are the section’s depth, number, and heading, all of which can be empty ({}). Your TeX​ ​format may have its own macro for writing lines into the ToC (\writenumberedtocline is the Eplain name for this macro). TeX2page also understands LaTeX’s \addcontentsline. For other formats, if you intend to use their explicit ToC addition macro, you will need to furnish an HTML-only definition for it in terms of \writenumberedtocline.

Footnotes

Both unnumbered and numbered footnotes — plain TeX’s \footnote and \vfootnote, LaTeX’s \footnote, Eplain’s \numberedfootnote — are recognized. They are translated as in DVI (modulo what constitutes a page), but additionally, the footnote mark in the text body is a link to the footnote mark in the footnote text, and vice versa. Here is an example footnote.¹

Since Plain TeX​ ​does not provide an automatically numbering footnote macro, users can define their own as follows:

\newcount\footnotenumber

\def\numberedfootnote{%
  \global\advance\footnotenumber by 1
  \footnote{$^{\the\footnotenumber}$}}

This definition could be made TeX-only, since TeX2page already recognizes \numberedfootnote. However, the TeX​ ​programming in this definition is recognized by TeX2page, so it does not matter if it overrides TeX2page’s internal definition.

Indeed, one could define a more complicated macro such as the following \sfootnote, which produces symbolic rather than numeric footnote marks, cycling through a set of nine symbols:

\def\fnsymbol#1{%
  % #1 is between 1 and 9 inclusive
  \ifcase#1\or
    *\or\dag\or\ddag\or\S\or\P\or
    $\Vert$\or**\or\dag\dag\or\ddag\ddag
  \fi}

\def\sfootnote{%
  \global\advance\footnotenumber by 1
  \ifnum\footnotenumber>9 \global\footnotenumber=1 \fi
  \footnote{\fnsymbol{\the\footnotenumber}}}

TeX2page produces the expected output for all the footnote macros, including the user-defined ones.

Bibliographies

TeX2page can use the external program BibTeX [33, 36, 39] to generate bibliographies from bibliographic database (.bib) files. The bibliography commands — \cite and the rest — are included in LaTeX, but for Plain TeX​ ​must be explicitly loaded via the macro file btxmac.tex. In HTML, the citation created by \cite is a link to the corresponding entry in the bibliography.

Bibliographies can also be manually embedded in the document via the thebibliography environment, without the need for the BibTeX​ ​program. For more details, see the LaTeX documentation [33, 36].

Index generation

TeX2page can use the external program MakeIndex [6, 32] to generate indices. TeX2page’s index-generation feature follows the same conventions as traditionally used with TeX​ ​and its derived packages [33, 36].

The sorted index is inserted in the document with a command such LaTeX’s \printindex or the more general \inputindex. The latter does not include a section header, so you can print your index your own way, e.g., with a different section type and title, and with some introductory prose.

For HTML, the page numbers listed for an index entry are of course the HTML page numbers, and are furthermore links to them. Two things need be noted:

(i) The link in the index goes directly to the spot where the corresponding \index command was called. This is convenient, especially as the target HTML page could be arbitrarily long, and it may not be as easy to hunt for the occurrence of the indexed item as on a paper page.

(ii) An index entry could link to the same HTML page several times. In the print index, a page would be mentioned only once per entry, but since an HTML page could be equivalent to many contiguous paper pages, it makes little sense to collapse into one all these references to (different locations in) the same page. The TeX2page index therefore repeats the page number with different links, and adds a roman number to the second and subsequent occurrences to distinguish them visually.

TeX2page also supports OPmac’s index generation macros \ii, \iid, \iis, and \makeindex. However, unlike OPmac, which rolls its own index-sorting routine within TeX, TeX2page relies on MakeIndex.

Internal cross-references

LaTeX’s \label and \ref produce internal cross-references in the HTML. The \label anchors a location in the document, and a \ref anywhere else in the document links to it. The link text used by \ref is the number of closest section (or footnote or other document fragment) that surrounds the \label. The LaTeX​ ​\pageref takes a label and produces the number of the page where the label was defined. In HTML, this is the HTML page number, and it is a link.

For formats that do not assume the presence of numbered sections as intensely as LaTeX, TeX2page also recognizes the \xrtag command as a generator of anchors. Where \label uses the nearest section number, \xrtag requires an explicit link text as its second argument.

\xrtag{ alabel}{ alabelvalue}

A reference to this tag, i.e., \ref{alabel}, will typeset as alabelvalue, which will link to the location identified by the \xrtag.²

Colors

TeX2page recognizes the macros \color, \colorbox, and \definecolor [5] provided by the LaTeX​ ​package color.sty. It also recognizes the color models cmyk, gray, hsb, rgb, and RGB provided by color.sty. It also supports the color models cmy, Gray, Hsb, HSB, HTML, and wave, provided by the LaTeX​ ​package xcolor.sty, which is a superset of color.sty. Furthermore, it supports the models hsl and Hsl.

{\color[cmy]{.46, .8, .86} burnt umber},
{\color[cmyk]{0, .89, .94, .28} brick red},
{\color[gray]{.4117} dim gray},
{\color[Gray]{11.2941} silver},
{\color[hsb]{.75, .6667, .6} rebecca purple},
{\color[Hsb]{196, 1, .65} cerulean},
{\color[HSB]{20, 199.2, 192} ochre},
{\color[rgb]{.69, .19, .38} maroon},
{\color[RGB]{220, 20, 60} crimson},
{\color[HTML]{77216F} aubergine},
{\color[wave]{455.528} cesium blue},
{\color[hsl]{.0389, .78, .62} burnt sienna},
{\color[Hsl]{10, .36, .37} venetian red},
and {\color{magenta} magenta}.

produces

burnt umber, brick red, dim gray, silver, rebecca purple, cerulean, ochre, maroon, crimson, aubergine, cesium blue, burnt sienna, venetian red, and magenta.

TeX2page doesn’t need either color.sty or xcolor.sty to process these commands, but you need these packages if you wish to see the color in your PDF output. Unfortunately, while color.sty can be loaded into plain TeX(after loading miniltx), xcolor.sty cannot. The TeX2page distribution does provide a plain-TeX-loadable macro file coloraug.tex that provides some of the functionality of xcolor.sty, and also the color models hsl and Hsl.

\definecolor defines new color names, e.g.,

\definecolor{dodgerblue}{Hsl}{210, 1, .56}
\definecolor{orangered}{Hsl}{16, 1, .5}
\definecolor{thistle}{Hsl}{288, 1, .71}

Poor Mr Norrell could only watch on helplessly as the gentleman
with the \colorbox{gray}{\color{thistle}thistle hair} seized his
copies of \colorbox{dodgerblue}{\color{white} The \TeX book} and
\colorbox{orangered}{\color{white} The \MF book}.

produces

Poor Mr Norrell could only watch on helplessly as the gentleman with the thistle hair seized his copies of The TeXbook and The METAFONTbook.

cmyk definitions for the 68 standard DVIPS color names are available in the standard LaTeX​ ​macro file dvipsnam.def. These are not predefined by browsers, so you will need to load dvipsnam.def explicitly if your HTML document is to benefit from them.