IV  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 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. 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 [16, 20] 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 manual [16, sec 4.3.2, p 71].

Index generation

TeX2page can use the external program MakeIndex [3, 15] to generate indices. TeX2page’s index-generation feature follows the same conventions as traditionally used with TeX and its derived packages [16, sec. 4.5 & appendix A].

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:

1. 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.

2. 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.

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.†

Color

TeX2page recognizes the macros \color and \definecolor [2]. These are provided by the LaTeX package color.sty, which can also be loaded into plain TeX using miniltx. E.g.,

{\color[gray]{.17} light gray}, 
{\color[rgb]{.69, .19, .38} maroon}, 
{\color[cmyk]{0, .89, .94, .28} brick red}, 
{\color[RGB]{220, 20, 60} crimson}, 
and {\color{blue} blue}. 

produces:

light gray, maroon, brick red, crimson, and blue.

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

\definecolor{BrickRed}{cmyk}{0, .89, .94, .28} 

Most color-capable browsers support the very large list of named colors in the X11 file rgb.txt. In order for your printed document to have access to these same color names, definitions for them are provided in the TeX macro file x11rgb.tex, included in the TeX2page distribution.

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.