6  Flags

TeX2page has a handful of flags that you can set to govern the HTML output. These flags are TeX control sequences such as \TZPcolophontimestamp, etc., and are set using \let or \def or even \gdef, \edef, or \xdef. (If using one of the \defs for a boolean flag, only the first character in the \def-body is significant.)

All these TeX2page flags are named \TZP..., and as long as you avoid using these names for other purposes, setting these flags should not affect the print output.

External title

By default, the ‘‘external’’ title of the HTML document --- i.e., the string that appears on the title bar of the browser window --- is either the same as the internal title, as specified with the \title command, or, if that is not available, the basename of the document source file. If you wish the external title to be something else, you can set the control sequence \TZPtitle, e.g.,

\def\TZPtitle{The Odyssey} 

Note that in LaTeX, \title merely specifies the title; the command that actually places the title is \maketitle. TeX2page does the same for LaTeX documents. For other formats, TeX2page will assume that \title should set its argument as a title immediately. For TeX to do likewise, the document must include supply an appropriate TeX-only definition for \title, e.g., the one in tex2page.tex.

Colophon flags

These flags govern the placement and content of the colophon. By default, TeX2page prints a two-line colophon at the bottom of the first page, the first line giving the time of last change of the source document, and the second line identifying TeX2page and linking to its website.

To put the colophon on the last rather than the first page,

\let\TZPcolophonlastpage=1 

To avoid mentioning the timestamp of the document in the colophon,

\let\TZPcolophontimestamp=0 

If the underlying Scheme is incapable of determining a file’s write date, TeX2page will not mention the timestamp, regardless of the \TZPcolophontimestamp setting.

To avoid crediting TeX2page in the colophon,

\let\TZPcolophoncredit=0 

To avoid linking to the TeX2page website in the colophon,

\let\TZPcolophonweblink=0 

If \TZPcolophoncredit is 0, the colophon won’t link to the TeX2page site, regardless of the \TZPcolophonweblink setting.

Math image flag

The \TZPmathimage flag specifies whether mathematical fragments in the document should be rendered as image or text. By default, TeX2page will generate images for displayed math and for ‘‘complicated’’ in-text math (i.e., math embedded in running text). If the in-text math is simple according its judgment, TeX2page will economize by generating its text (UTF-8) equivalent.

The assignment

\let\TZPmathimage=0 

forces subsequent math to be typeset as text, until the end of the document or until you reset to the flag to 1.

It is a good idea to set this flag to 0 if the mathematical notation in part or all of your document is simple enough to not require complicated notation.

Image conversion flags

These flags specify the conversion tactics used for generating HTML-suitable images from the user’s graphics requests. TeX2page invokes a combination of TeX and Dvips [32] to create a PostScript version of the graphic, and then Ghostscript [13] and either (a) the NetPBM library [28], or (b) the ImageMagick library [18], to convert the PS into the HTML-suitable image.

The defaults are: NetPBM to convert, and GIF to convert to. You may set the flags \TZPimageconverter and \TZPimageformat to change this, e.g,

\def\TZPimageconverter{imagemagick}  % use ImageMagick 
\def\TZPimageconverter{netpbm}       % use NetPBM (default) 
 
\def\TZPimageformat{png}  % for PNG images 
\def\TZPimageformat{jpeg} % for JPEG images 
\def\TZPimageformat{gif}  % for GIF images (default) 

TeX executable used for image generation

TeX2page uses one of the variants of TeX (typically pdftex) to generate images. To change this, set the flag \TZPtexprogname to contain the name of your preferred TeX executable, e.g.,

\def\TZPtexprogname{xetex} 

You only need to set the executable name used for the ‘‘plain’’ format: TeX2page will deduce the appopriate name for the LaTeX executable, which will be used to generate images if the entire document is in the LaTeX format. (This is so that any image preambles (p. 9) you use match the document’s format.)

Flag for Scheme code comments

The flag \TZPslatexcomments governs whether Scheme comments should inside verbatim Scheme code should be rendered verbatim or as TeX. By default, they are rendered verbatim. To allow TeX commands inside Scheme comment text, do

\let\TZPslatexcomments=1 

This is the style favored by SLaTeX. With \TZPslatexcomments set, the text

\scm{ 
(open-input-string ; in Scsh, use \scm{string->input-port} 
  s) 
} 

produces

(open-input-string ; in Scsh, use string‑>input‑port
  s)

Note that \TZPslatexcomments=1 is not an unmixed blessing, as it restricts your Scheme comments to text that is valid TeX.

Flags for page and paragraph layout

By default, TeX2page produces block paragraphs with about a baseline’s worth of vertical space separating paragraphs, and text width expands to fill the browser width, allowing for some margins.

To produce more TeX-like layout, i.e., with no parskip and with some parindent, with the page width not exceeding \hsize, with left and top margins that are an inch greater than \hoffset and \voffset respectively, and with a navigation bar that uses \headline and \footline, do

\let\TZPtexlayout=1 

The HTML page will be set according to the values of the lengths \hsize, \hoffset, \voffset, \parskip, \parindent, and the tokens \headline and \footline as they are at the end of the document.

The command \folio inside the tokens \headline and \footline --- and only inside them --- produces in HTML not the current page number but rather twin links to the adjacent pages. \folio thus lets you create navigation bars.

Note that the plain TeX default (which TeX2page reuses) is to have \folio in the \footline and nothing in the \headline. If you wish to have a navigation bar in the header, you should set \headline.

It is not necessary that these values be identical to what TeX sees for the same document, as you can make HTML-only settings such as

\ifx\shipout\UnDeFiNeD 
  \hsize=36em 
  \headline={\folio, ~~ \urlh{#ToC}{ToC}, ~~ \urlh{#Index}{Index}} 
  \footline={\the\headline}  % i.e., footline same as headline 
\fi 

where the tags ToC and Index are set near the ToC and Index respectively.

Paragraphs preceded by \noindent will always have no initial indentation, even if \TZPtexlayout=1 and \parskip is non-zero.

Because it is too drastic a change, \TZPtexlayout=1 will not cause text to be right-justified. To make that happen,

\let\TZPraggedright=0 

Setting \TZPraggedright has no effect unless \TZPtexlayout is also set.

Finally, TeX uses pseudo-ligatures to convert occurrences of `, ', ``, '', ‑‑, and ‑‑‑ in the source to left quote, right quote, left double quote, right double quote, en-dash, and em-dash respectively. If you use a Unicode-friendly TeX such as XƎTeX with a Unicode font and a text editor that lets you enter these quotes and dashes directly, then you may not need the ligatures, and may indeed, want ‑‑ to show up as two hyphens, both in the HTML and the DVI. To disable the ligatures,

\let\TZPtextext=0 

In this case, you also have to ensure that the fonts you use in XƎTeX do not have mapping=tex‑text.

Making a slideshow

To cause your source to be converted into slideshow-ready HTML pages, set the flag \TZPslides:

\let\TZPslides=1 

This causes TeX2page to use the macro file t2pslides.tex, which uses the process described in the MozPoint [33] library to convert your sequence of HTML pages into a Web presentation. t2pslides.tex is included in the TeX2page distribution, and must be placed somewhere in TEXINPUTS or TEX2PAGEINPUTS. It has no effect on the DVI version of the document.

HTML pages meant for presentation use larger, bolder fonts, and avoid navigation bars. The following table describes the keys used to control the presentation:

To bring up the next slide, (left-)click the mouse anywhere on the screen, or press the space bar, n, right or down arrow. To go back to the previous slide, right-click the mouse, or press p, left or up arrow. To go immediately to the first (i.e., title) slide, press t or 0. To go immediately to the nth slide after the title slide, type n. If n has two or more digits, they should be pressed fairly rapidly so that they are interpreted together. To blank the screen, press b (black) or w (white); to unblank, press the same key again.

Page redirection

If you wish your HTML output to immediately redirect elsewhere, set the flag \TZPredirect to contain the target URL.

\def\TZPredirect{http://newhome.com/path/samedoc.html} 

This is useful when you’ve moved the location of a page but the old URL is still being used.

The content of the document is obviously irrelevant. However, you may put in \ejects in your TeX source to create the same number of pages as in the original document. If the user consults any of these pages directly, they will get redirected to the new location.

Not all browsers support automatic redirection. The (original) page therefore includes an informative sentence containing the link to the desired page, which the user can explicitly click.

By default, the redirection takes place in 5 seconds. To change this, set \TZPredirectseconds, e.g.,

\def\TZPredirectseconds{10} 

Scheme or Common Lisp?

Finally, the flag \TZPcommonlisp can be used to decide whether calls to \eval (p. 10) should contain Scheme or Common Lisp code. Typically, the construct \ifx\TZPcommonlisp 1 is used to introduce the Common Lisp and Scheme versions as the two conditional clauses, so the document remains processable in both languages.

TeX2page pre-sets \TZPcommonlisp to 1 in Common Lisp and 0 in Scheme.