6  Flags

TeX2page has a handful of flags that you can set to govern the HTML output.

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

These flags are TeX​ ​control sequences 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.)

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, the first heading (i.e., chapter or section), or, if none such is 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.

Language

By default, the language of the document is assumed to be English. To change this, set the control sequence \TZPlang to the ISO 639-1 code for the preferred language, e.g.,

\def\TZPlang{de} % German

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.

(i) To put the colophon on the last rather than the first page,

\let\TZPcolophonlastpage=1

(ii) To avoid mentioning the timestamp of the document in the colophon,

\let\TZPcolophondisabletimestamp=1
If the underlying Lisp is incapable of determining a file’s write date, TeX2page will not mention the timestamp, regardless of the \TZPcolophondisabletimestamp setting.

(iii) To avoid crediting TeX2page in the colophon,

\let\TZPcolophondisablecredit=1

(iv) To avoid linking to the TeX2page website in the colophon,

\let\TZPcolophondisableweblink=1
If \TZPcolophondisablecredit is set, the colophon won’t link to the TeX2page site, regardless of the \TZPcolophondisableweblink setting.

Math image flag

The \TZPmathtext 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\TZPmathtext=1
forces subsequent math to be typeset as text, until the end of the document or until you reset to the flag to 0.

It is a good idea to set this flag to 1 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 [43] to create a PostScript version of the graphic, and then Ghostscript [15] and either (i) the NetPBM library [37], or (ii) the ImageMagick library [22], to convert the PS into the HTML-suitable image.

The defaults are: NetPBM to convert, and PNG 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{gif}  % for GIF images
\def\TZPimageformat{jpeg} % for JPEG images
\def\TZPimageformat{png}  % for PNG images (default)

TeX​ ​executable used for image generation

By default, TeX2page uses luatex 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 appropriate 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 Lisp code comments

The flag \TZPslatexcomments governs whether Lisp comments should inside verbatim Lisp code should be rendered verbatim or as TeX. By default, they are rendered verbatim. To allow TeX​ ​commands inside Lisp 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 Lisp 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.

(i) 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.

(ii) If you don’t really need a full-blown TeX-like layout, but would still like to have the HTML page’s text width be no more than, say, 6.25 inches, you could have

\def\TZPhsize{6.25 in}
The \TZPhsize value overrides the \hsize value, whether or not you set \TZPtexlayout.

(iii) To keep the body of the page horizontally centered, i.e., with equal left and right margins, use

\let\TZPautomargin=1
Note this centers the body as a block, not the individual lines (which would not be readable at all).

\TZPautomargin is ideally combined with a \TZPhsize setting so the text remains a readably compact width however much you zoom out. You may also use it alongside \TZPtexlayout, in which case the \hoffset (left margin) setting is ignored.

(iv) Because it is too drastic a change, \TZPtexlayout=1 will not cause text to be right-justified. If you really want it, use

\let\TZPrightjustify=1
Setting \TZPrightjustify has no effect unless \TZPtexlayout is also set. Use them together if you want to most closely mimic the print output.

(v) 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 produce a Web presentation, set the flag \TZPslides:

\let\TZPslides=1
This causes TeX2page to use the style sheet slidy.css and JavaScript file slidy.js from Slidy [42] to convert your document into a single HTML page containing slides. TeX2page looks for these files in the working directory, and if they’re not found there, it links them from the W3C website. It may be prudent to get these files beforehand and place them in your working directory, so the presentation doesn’t rely on WiFi.

A new slide is started for each “chapter” and “section”, i.e., \beginchapter, \chapter, \beginsection and \section. (Note of course that it doesn’t make sense to convert generic TeX​ ​documents into presentations. The sections have got to be pretty short!)

An HTML page meant for presentation uses larger, bolder fonts by default (but you can add your own CSS). There are no navigation bars between slides. Furthermore, enumerated and itemized lists (\enumerate and \itemize) display their items incrementally.

Consult the Slidy documentation for the keypresses and clicks you can use to progress through or dynamically alter the look of your presentation.

Page redirection

(i) 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.

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

\def\TZPredirectseconds{10}

Single output file

Sometimes it is desirable to generate just a single output HTML file, i.e., to not generate a page break as described on p. 4, and to have all the images embedded as data URIs within the document. To do this, set the \TZPsinglepage flag:

\let\TZPsinglepage=1

OPmac

The flag \TZPopmac can be set to 1 to inform TeX2page that you’re using OPmac macros [38] in your document. Typically this isn’t necessary as TeX2page can spot if you’ve \input opmac. The flag need be set only if somehow the loading of opmac occurs in a TeX-only portion of your document.

This flag, whether explicitly or implicitly set, helps TeX2page decide which form of the macros \cite and \nocite to use. In contrast to most other styles (including LaTeX), which use {} for these macros’ argument, OPmac uses [].

Common Lisp or Scheme?

The flag \TZPcommonlisp can be used to decide whether calls to \eval (p. 10) should contain Common Lisp or Scheme 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.

You may set \TZPcommonlisp to specify that the document needs either the Common Lisp or Scheme version of TeX2page. If the incorrect version is used, TeX2page will display a warning message, but will not crash for this reason alone.