index.tex

% This is a plain TeX file, and can be TeX’d as usual,
% but it can also be converted into an HTML document.  To do
% this latter, run
%
% tex2page index

% tex2page is available at
% http://ds26gte.github.io/tex2page/index.html

\input tex2page-doc-mac

\ifx\TZPtitle\UnDeFiNeD
\def\TZPtitle{TeX2page}\fi

\title \TeX2page

\smallskip

\c{\urlh{http://ds26gte.github.io}{Dorai Sitaram}}
%
\ifx\shipout\UnDeFiNeD
\c{Download
\urlh{https://github.com/ds26gte/tex2page}{Version \fmtversion}}
\else
\c{2023-01-01} %last change
%\ifx\shipout\UnDeFiNeD
%\c{(A copy is included in
%\urlh{http://www.plt-scheme.org}{PLT Scheme})}
\fi
%

%\medskip

\ifx\shipout\UnDeFiNeD
\centerline{\htmladdimg{t2p.png}}
\fi

{\obeylines\raggedleft
\ifx\shipout\UnDeFiNeD\small\else\eightfont\fi
{\it Making books is a skilled trade,
like making clocks.}
— Jean de la Bruyère (†1696)
}

%French original:
%“C’est un métier que de faire un livre,
%comme de faire une pendule.”
%JdlB’s lifespan: 1645–1696.

\medskip

%\index{plain TeX}
%\index{LaTeX}

\n
\TeX2page
makes Web pages
from \TeX~\cite{texbook} manuscripts.
It reads an
input document that is marked up in
plain \TeX\ or \LaTeX~\cite{latex,latex-companion}
and
produces an output document with the functionally
equivalent HTML markup.
\TeX2page uses the same input
file syntax, calling conventions, and  error-recovery
mechanisms as \TeX.  Thus, \TeX2page demands no additional
expertise of a user already familiar with \TeX.
\TeX2page runs on Common Lisp and modern Schemes.
%However, for the user who wants more, \TeX2page
%provides Scheme as an extension language.

There are several advantages to keeping the document
source in \TeX\ and leaving the task of converting to
HTML to \TeX2page:  There is no need to write and
maintain two separate documents, one for paper and the
other for the screen.  Indeed, there is no need to
learn a {\em new} input format, as \TeX2page reuses a
format already in wide and stable use for printed
documents~\cite{tug,ctan}.  Creating \TeX\
source requires no special-purpose software; any text
editor will do.  Furthermore, an ecology of powerful and
reliable tools such as \BibTeX~\cite{bibtex},
MakeIndex~\cite{makeindex}, and
MetaPost~\cite{metapost,mfbook} has developed around \TeX, and
its benefits can be enjoyed by \TeX2page too.

Finally, \TeX, unlike HTML, is a {\em programming}
language, which lets the composer of the document
exercise a fine control over its structure and
presentation.  A converter such as \TeX2page that can
convert \TeX\ macro definitions in addition to basic \TeX\
markup enables the format converted to to also benefit
from \TeX’s extensibility.  For the cases where
\TeX2page’s implementation of the \TeX\ macro system is
not manipulable enough, the document writer can use the
\TeX2page {\em extension language}, which is full Common Lisp or
Scheme
augmented with all the \TeX2page procedure definitions.

The rest of this manual is organized as follows:

\medskip

\xrdef{ToC}
\tableofcontents

\beginchapter 1 Running \TeX2page

\xrdef{usage}
\index{running \TeX2page!from system command-line}
%
\TeX2page is invoked in much the same way as \TeX.\f{Hereafter,
we will use “\TeX” to mean
any format of \TeX, and “plain \TeX” when we
specifically mean the “plain” format. We will use “Lisp” to refer
to the implementation language of the \TeX2page script under
discussion, although this can be either Common Lisp or Scheme,
with near-identical behavior. For the minor differences, see
Appendix A (p.~\ref{scheme}).}
For instance, given a plain-\TeX\ document file
\p{|meta[wherever-it-is/jobname].|meta[ext]}, which can
be either a full pathname or a pathname relative to either the
working directory or some directory in `TEXINPUTS`, where
\p{|meta[jobname]} is the {\em basename} of the file
and \p{.|meta[ext]} is its extension, you type

\begintt
tex |meta[wherever-it-is/jobname].|meta[ext]
\endtt
%
at the operating-system command line.\f{The executable `tex` expects
its input file to be marked up in plain \TeX.  For a \LaTeX\ document, the
executable to use is `latex`. Modern \TeX\ engines such as
Lua\TeX~\cite{luatex}, \XeTeX~\cite{xetex}, and pdf\TeX\ have
executables named `luatex`, `xetex`, `pdftex` for the plain
format, and `lualatex`, `xelatex`, and `pdflatex` for \LaTeX.}  You do not need to mention the extension
\p{.|meta[ext]} if it is `.tex`.  This creates the output DVI file,
\p{|meta[jobname].dvi}, in the working directory.\f{The modern \TeX s
Lua\TeX, \XeTeX, and
pdf\TeX\ produce PDF rather than DVI.  In the rest of this manual,
whenever we refer to the output DVI file, the reader using the PDF versions
of \TeX\ should read PDF for DVI.}

\index{tex2page (c@`tex2page` (command)}

\TeX2page is called analogously.  To create the HTML
version of the same file
\p{|meta[wherever-it-is/jobname].|meta[ext]}, type

\begintt
tex2page |meta[wherever-it-is/jobname].|meta[ext]
\endtt
%
Again, the \p{.|meta[ext]} is optional if it is `.tex`.  This
creates \p{|meta[jobname].html} in the working directory.

\index{story.tex@`story.tex`}

To try this out, call \TeX2page on the example file
\urlh{texample.html}{`story.tex`}
provided in all \TeX\ distributions:

\begintt
tex2page story
\endtt
%
\index{log file}
%
\TeX2page will get cracking\f{\TeX2page, like \TeX, will find the
file `story.tex` from your distribution as it is in your default `TEXINPUTS`.
If it’s too confusing operating on a file that you don’t see in
your immediate space, copy the file manually to your working
directory. You can find its location with `kpsewhich story`.} on `story.tex`, providing
the following commentary, or {\em log}, on your console:

\medbreak
\verbatiminput story.hlog
\medbreak

\n \TeX2page is now done, and the result of its labors
is the HTML file
\urlh{story.html}{`story.html`}\ifx\shipout\UnDeFiNeD\ (click
to see)\fi.

\index{bye@`\bye`}
\index{end@`\end`}
\index{hlog@`.hlog`|see{log file}}
\index{log file}

The {\em log file} `story.hlog`
contains a copy of the above log, and is useful
if you didn’t or couldn’t keep track of the console
(perhaps because the log was too long).
The log says that `story.tex` lacked a
document-ending command such as `\end` (or `\bye`)
and that \TeX2page assumed one anyway.  Also, only
{\em one} HTML page was created, and its name is
`story.html`.  \TeX2page could in some cases produce
auxiliary HTML pages in addition to
the main HTML page \p{|meta[jobname].html} (especially
for larger documents).  The auxiliary HTML pages
are reachable from \p{|meta[jobname].html}
by navigation links (p.~\ref{eject}).  As  each
auxiliary HTML page is completed, the log will show the
bracketed numbers `[1]`, `[2]`, etc.  The `[0]`
in this log refers to the only HTML file created, viz.,
`story.html`.

All this is of course almost exactly analogous to the
way you type `tex story` (or `luatex story` or `xetex story` or `pdftex story`) to get
`story.dvi` (or `story.pdf`)
from `story.tex`, with the log going into
`story.log`.

\medbreak
\verbatiminput story.log
\medbreak

\n The only real difference is
that \TeX\ will not add the missing `\end` on its
own, but instead waits for the user to supply it
explicitly from the console.\f{The file `story.tex`
lacks an `\end` only to demonstrate some interactive
capabilities of \TeX, which are not relevant for
\TeX2page.}  Note that the bracketed numbers now refer
to the pages as numbered in the printed document.

Thus, from one \TeX\ source file, you can get both a printable `.dvi` and a
browsable `.html` document, using the same calling
conventions.\iffalse \f{Quite a few documents profit from
being available additionally as plain text, either as a man page, or as
tagged text on a general-purpose text editor, instead of requiring an HTML
browser.  The scripts `t2p2man`,
`t2p2txt`, and `t2p2info`, included in the \TeX2page distribution,
help accomplish this.
Each of these scripts takes as argument the main HTML
file \p{|meta[jobname].html} created by \TeX2page, and generate the
corresponding man page \p{|meta[jobname].1},
the Vim help file \p{|meta[jobname].txt}, and the
Info file
\p{|meta[jobname].info}
respectively.  While the man page is always a single page, the Info and
Vim-help output is composed of multiple files if the HTML document contains
pagebreaks.}\fi

%can be used to create such “low-tech” but
%easy-access hypertext that is readable on any
%tags-capable text editor.

\index{kpathsea@`kpathsea`}
\index{TEXINPUTS@`TEXINPUTS` (environment variable)}
\index{TEX2PAGEINPUTS@`TEX2PAGEINPUTS` (environment variable)}

When \TeX\ encounters a filename \p{|meta[f]}, it
searches for it
in a standard list of
directories, which can be modified by the user via the
environment variable `TEXINPUTS`.
The filename \p{|meta[f].tex} is tried before
\p{|meta[f]} itself is tried.  In most modern \TeX s, the
search is performed using the `kpathsea` library.

\TeX2page also looks for files using the same `kpathsea`
mechanism as \TeX.  However, it first looks at a
different list of search directories given in the environment
variable `TEX2PAGEINPUTS`.
It may be useful to have
files in `TEX2PAGEINPUTS` shadow files from
`TEXINPUTS`, because the latter are not really
HTML-specific, and can thus be unsuitable for
HTML-minded parsing by \TeX2page.

In \TeX s without the `kpathsea` library,
`TEX2PAGEINPUTS` is the only way to get \TeX2page to
automatically access files outside the working
directory.  Note that `TEX2PAGEINPUTS` should be a
simple list of directory names, colon-separated in Unix
and semicolon-separated in Windows.  It cannot use the
enhanced syntax (viz., `*` and `//`) that is
typically permitted for `TEXINPUTS`.

Error recovery in \TeX2page is also exactly analogous to
\TeX, but we will postpone that discussion to
p.~\ref{recovery}.

\beginsection Non-file arguments

\index{help@`--help` (command-line option)}
%
\index{version@`--version` (command-line option)}
%
Like most recent versions of \TeX, \TeX2page also
supports the standard self-identification
arguments `--help` and `--version`.  These
arguments elicit help only if there isn’t an input file
(e.g., `--help.tex`) that could match them.

\TeX2page called without an argument displays a help
message and exits.  Unlike \TeX, \TeX2page will not try
to conjure up an input document based purely on console
chitchat with an increasingly befuddled user.

In all these cases, the help displayed on the console
is also saved in the specially named log file
`texput.hlog`.

\beginsection Calling \TeX2page from Lisp

\index{running \TeX2page!from Common Lisp}
\index{tex2page:tex2page (Common Lisp f)@\q{tex2page:tex2page} (Common
Lisp function)}
%
If, for any reason, it is not possible to call `tex2page`
from your operating-system command line, you may load the
file `tex2page` into your Lisp
and call the
{\em procedure} \q{tex2page:tex2page} with the name of the \TeX\ file
as argument:

\begintts
(load "tex2page") ;use appropriate pathname

(tex2page:tex2page |meta[filename])
\endtt
You can call the procedure
\q{tex2page:tex2page} several times from the same Lisp
session, on the same file or on different files.

Note that we’ve used a package-qualified name, as the Common
Lisp \TeX2page is provided as a Common Lisp package \q{tex2page}
whose one exported symbol is \q{tex2page}. (But see Appendix A if
using the Scheme version of \TeX2page.)

\beginsection Specifying a target directory
%\label{hdir}

\index{hdir file@`.hdir` file}
\index{tex2page.hdir@`.tex2page.hdir` file}
%
By default, \TeX2page generates the output HTML files
and other auxiliary files (p.~\ref{auxfile}) in the
current working directory.  You can tell \TeX2page
to place its output and auxiliary files in a different
directory and thus avoid cluttering up your working
directory.

The files used for specifying the target directory are:
\p{|meta[jobname].hdir} in the working directory,
`.tex2page.hdir` in the working directory, and
`.tex2page.hdir` in the user’s `HOME` directory.
The first line of the first of these files that exists
is taken to be the name of the target directory.
If none of the files exists, the current working
directory is the target directory.

For example, if `story.hdir` contains the filename
`story` as its first line, the HTML and aux files are
created in a subdirectory `story` of the
current directory.

\index{jobname@`\jobname`}

The filename may contain the \TeX\ control sequence
`\jobname`, which expands to the basename of
the \TeX\ document.  To always use an auxiliary
subdirectory with the same name as the basename of the
\TeX\ document, have `~/.tex2page.hdir` contain the
line “`\jobname`” (without quotes).

\iffalse
beginsection Info files

If a \TeX2page-generated set of HTML files is largely text, it can be
read using text-based browsers such as Lynx~\cite{lynx}.  However, many
people would rather view it as an Info~\cite{texinfo} document. Info files can be
browsed very rapidly in a text editor or a lightweight console browser;
allow convenient regex search across the entire document; and can
be read as plain text as they have much less markup than the
corresponding HTML.

The \TeX2page distribution includes a script `t2p2info` for converting
\TeX2page-generated HTML into Info.  `t2p2info` takes as argument the
filename of the main HTML file generated by \TeX2page, e.g.,

\begintt
t2p2info jobname.html
\endtt
The result is one or more Info files, the first of them named
`jobname.info`.
\fi

\iffalse
Split following into two chapters, “\TeX\ commands”, about
commands that \TeX2page doesn’t recognize,
and
“\TeX2page commands”, about commands that \TeX\ doesn’t
recognize, without help, i.e.  (The latter may simply be
because the command is from a different format.  \TeX2page
recognizes both formats, but one format may not recognize
the commands of the other.  Esp., plain \TeX\ won’t understand
\LaTeX\ cmds.

Perhaps “Paper and Screen” chapter can be rolled into these
two chapters.  Can probably eliminate or at least
drastically shorten the chapters about
Sections, Verbatim, Cross-references, Color.

Readers of this manual and users of this program will
already know (La)TeX.  It is not this manual’s job to
introduce them to what’s possible in (La)TeX.
\fi

\beginchapter 2  \TeX\ commands
%\label{texcmds}

\index{LaTeX@\LaTeX} \index{plain TeX@plain \TeX}
%
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 {\em markup
commands} within the text.  When
the program \TeX\ is called on a \TeX\
document, it uses the markup commands in the document
to create an appropriately typeset version of the
document in a {\em DVI} file, which can then be
printed.  The \TeX\ program, which
recognizes a list of primitive commands, is invariably
called with a {\em format}, which is essentially a
preloaded set of definitions of some additional
commands.  The two most popular formats
are plain \TeX~\cite{texbook} and
\LaTeX~\cite{latex,latex-companion}.

%\index{texi2p.tex@`texi2p.tex` (\TeX2page macro file)}

\TeX2page understands many of the commands of
plain \TeX,
\LaTeX, Eplain~\cite{eplain}, OPmac~\cite{opmac}, and
`manmac`~\cite[app.~E]{texbook}.\f{%
%
\index{footnote@`\footnote`}
\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 (e.g., `\footnote`) is used in both
formats but with differing 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.}
%
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.
In addition to the usual smörgåsbord of sectioning, itemization and
enumeration macros,
\TeX2page also recognizes some commonly used commands
that are not part of the formats but
are loaded from \LaTeX\ packages (e.g.,
`color.sty`, `epsfig.sty`, `graphicx.sty`, `luamplib.sty`,
`path.sty`,
`verbatim.sty`)
or other external macro
files (e.g., `btxmac.tex`, `eplain.tex`, `opmac.tex`,
`epsf.tex`).

%With the aid of a macro file `texi2p.tex`, \TeX2page
%can also process Texinfo documents~\cite{texinfo}.

While \TeX2page recognizes many commonly used commands,
there are plenty of commands in both the format proper
and the vast arena of macro files and packages that
\TeX2page does not know.  If in math mode (assuming
math is translated as text and not image
(p.~\ref{mathflag})), \TeX2page
simply types the command’s name without the leading
escape character.  This is sometimes a good choice, as
in the following text (where `\sin` and `\cos` are not
explicitly recognized by \TeX2page):
\let\TZPmathtext=1

\begintt
$$\sin^2 x + \cos^2 x = 1$$
\endtt
%
This becomes

$$\sin^2 x + \cos^2 x = 1$$
%
\let\TZPmathtext=0
which is clear enough.

If in non-math mode, \TeX2page simply ignores commands
it doesn’t understand.  This is also usually a good
thing, as commands like `\leavevmode`, `\/`, and
`\-` are best translated into HTML as nothing at all.

\TeX2page ignores calls to include external \LaTeX\
packages: These are files with extension `.sty` and
are loaded with `\usepackage` or `\input`.  If the
commands offered by these packages are not already
recognized by \TeX2page, they will be ignored too, and
often this is not a problem.  E.g., you can use a
package 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.

\index{Unicode}
Modern \TeX s, e.g., \XeTeX~\cite{xetex}, allow the use of
Unicode~\cite{unicode,haralambous:fonts,korpela:unicode,unicode4} fonts,
thereby permitting a vast cornucopia of characters
\ifx\shipout\UnDeFiNeD such as
\char"950 , \char"101, \char"222e\ and \char"2388\
\fi
to be entered verbatim (i.e.,
without the aid of \TeX\ commands) in the source document.  \TeX2page
follows modern practice in typesetting Unicode characters as themselves
(provided of course they haven’t been deliberately `\catcode`’d to
mean something special).

\index{char@`\char`}
In particular, \TeX2page, like \TeX,
recognizes the `\char` command, followed by a \TeX\ number $n$, as a
directive to output the character $n$ in the current font — but
\TeX2page assumes a Unicode font is meant.
You may need to use conditionals
to ensure that the same glyphs are typeset in both the HTML and the
DVI, if your \TeX\ does not use a Unicode font.

\beginsection Defining \TeX-only and HTML-only text regions

\xrdef{htmlonly}
\TeX2page will attempt gamely to process any \TeX\
definitions that you use in your document or in
external macro files without the extension `.sty`,
but it may be a good idea to have them explicitly
ignored, if these
macros that are print-specific, or if
having \TeX2page try to parse them will cause error.  A way
to have \TeX2page ignore such fragments in your document
is  to use
\TeX\ conditionals, and indeed to exploit the
fact that \TeX2page does not know certain \TeX\ commands
such as `\shipout`:\f{%
\index{ifdefined@`\ifdefined`}
Here, `\UnDeFiNeD` is chosen because it is
a control sequence that is (presumably) undefined. If perchance
you defined it, replace it with something else, e.g.,
`\forHTMLonly`, `\ForTheWeb`. If using a modern PDF-producing
\TeX, you can use `\ifdefined`, and thus avoid having to come up
with arbitrary undefined control sequences. Note that with
`\ifdefined\shipout` it’s the else-branch that’s HTML-only.}

\index{ifx@`\ifx`}
\index{shipout@`\shipout`}
\index{else@`\else`}
\index{fi@`\fi`}
\begintt
\ifx\shipout\UnDeFiNeD
  ... |meta[for HTML only] ...
\else
  ... |meta[for DVI only] ...
\fi
\endtt
For example, let’s say you want to have  your document load the macro file
`manmac.tex`, but in a way that \TeX2page will ignore
it.  Use:

\index{input@`\input`}
\begintt
\ifx\shipout\UnDeFiNeD
\else
  \input manmac
\fi
\endtt
However, there will also be many  commands that
you do not want ignored in the HTML.  In such
cases, while you may not be able to use the print-specific
definition, you should nevertheless furnish a definition that \TeX2page
can handle.  For instance, although it may be acceptable
to ignore the print-specific macros of `manmac`, the
`\bull` macro defined in `manmac` should be
translated by \TeX2page.  The following is a possible
definition for \TeX2page:

\index{def@`\def`}
\begintt
\def\bull{{\bf *}}
\endtt
Of course, we want this definition to be seen only
by \TeX2page, as we don’t want to override the
original, more sophisticated `\vrule`-based definition as seen
by \TeX.
We therefore make our
definition HTML-only
using a conditional:

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
  \def\bull{{\bf *}}
\fi
\endtt

\index{rawhtml@`\rawhtml`}
\index{endrawhtml@`\endrawhtml`}
Note that the HTML-only text continues to use \TeX\ syntax.
To specify some of this text as {\em raw} HTML, enclose it
in `\rawhtml` `...` `\endrawhtml`.   With
`\rawhtml`, we can
spruce up the
HTML-only definition of `\bull`:

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
  \def\bull{{\bf
  \rawhtml<span style="color: hsl(0,100%,30%)">&spades;</span>\endrawhtml
  }}
\fi
\endtt

\index{texi2p.tex@`texi2p.tex`}
\index{Texinfo}
One can put HTML-only definitions in separate files
that are loaded just like regular \TeX\ macro files.
Indeed, one such external file, `texi2p.tex`, is used
by \TeX2page to process Texinfo
documents.  Texinfo~\cite{texinfo} is another \TeX\
format, and files using this format `\input texinfo`
as the first thing they do.  \TeX2page takes that as a
cue to
load `texi2p.tex`, which provides \TeX2page-suitable
definitions for the Texinfo commands.  `texi2p.tex`
is included in the \TeX2page distribution.

\beginsection Paper and screen

One could use HTML-only and DVI-only regions to cordon off
any text at all, not just macro definitions.  E.g.,

\begintt
The paper book is
\ifx\shipout\UnDeFiNeD % HTML only
an antiquated
\else % DVI only
a time-tested
\fi
technology.
\endtt
Use of these directives may seem to miss the point of
\TeX2page.  `\ifx\shipout\UnDeFiNeD` violates the
principle of avoiding  writing {\em two} texts, one
for HTML, the other for DVI.  `\rawhtml` violates the
principle of avoiding writing raw HTML at all.
`\rawhtml` in particular is dangerous because it voids
the guarantee that the output pages will be valid HTML.
Nevertheless, these directives are often useful, especially when the
text will profit from exploiting the presentational differences between
HTML and DVI.

\beginsection The {.t2p} file

\xrdef{t2p-file}
\index{t2p file@`.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`, {\em 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.

Note that the definitions in the `.t2p` file
are processed {\em before} the main file.  But it often
makes sense to activate these definitions sometime
later.  E.g., activating the `.t2p` definitions {\em
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:

\index{let@`\let`}
\index{document@`\document`}
%
\begintt
\let\PRIMdocument\document

\def\document{
  ... |meta[HTML-specific definitions] ...
  \PRIMdocument}
\endtt
%
This code, which goes in the `.t2p` file,
redefines the `\document` command to include a
hook that loads some {\em 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.

\beginchapter  3  \TeX2page commands
%\label{texcmds}

The previous chapter explained how a document that is
acceptable to \TeX\ may contain several commands that
\TeX2page does not inherently
understand and for which suitable HTML-only definitions
must be provided.  The reverse problem also obtains: A
document that is processed successfully by \TeX2page
may contain commands that plain \TeX\ and \LaTeX\ may not
recognize.

As we have seen, \TeX2page recognizes a mix of plain-\TeX\ and \LaTeX\
commands, and commands from external macro files besides.
Thus,
a plain \TeX\ document could very well use \LaTeX\
commands and pass through \TeX2page without hitch.  When
running plain \TeX\ on the document, of course, the \LaTeX\
commands will fail, unless \TeX-only definitions for the
missing commands are provided.  Examples of common \LaTeX\
commands recognized by \TeX2page include the commands for
title, chapters and sections, footnotes,  labels for
cross-referencing, table of contents,  verbatim text,
itemizations, enumerations,
index, and bibliography.

It is also possible that the
document uses commands from external macro files
without actually loading said files.  \TeX2page will be
indulgent, but plain \TeX\ and \LaTeX\ won’t.
In this case,
simply loading the macro files should be
enough.    Thus, a plain \TeX\ document using the `\cite`
command should load `btxmac.tex`, and   a \LaTeX\ document that uses
the `\color` and `\definecolor` commands should load the package
`color.sty`.

\xrdef{miniltx}
\index{miniltx.tex@`miniltx.tex`}
%
A plain \TeX\ document using macros  provided by a \LaTeX\
package may also be able to load the package in some cases, with
the aid of the `miniltx.tex` macro file.  To load
`color.sty`, for instance:

\index{expandafter@`\expandafter`}
\index{csname@`\csname`}
\index{endcsname@`\endcsname`}
\begintt
\expandafter\def\csname Gin@driver\endcsname{pdftex.def}
% The above may not be needed in newer \TeX\ distributions,
% which will load the appropriate driver automatically.
% Replace pdftex.def with dvips.def if output print format
% is PostScript rather than PDF.

\input miniltx
\input color.sty
\resetatcatcode
\endtt

Although the above is only meant for \TeX,
it is not necessary (but not incorrect either) to wrap it inside
`\ifx\shipout\UnDeFiNeD\else` `...` `\fi`, as
\TeX2page knows enough to skip such loads.

Other useful \LaTeX\ packages that can be loaded into plain
\TeX\ using `miniltx` are `graphicx.sty` and
`url.sty`.  (Unfortunately, one has to say
`\expandafter\def\expandafter\+\expandafter{\+}`
before `\input`ting `url.sty`.)

It is possible to `\input`
several `.sty` files between the calls to `\input` `miniltx` and
`\resetatcatcode`.  However, `miniltx` is a bit of a compromise, and it
causes each `.sty` file to re-evaluate the supposedly per-document commands
in the driver file
(e.g., `pdftex.def`), which can cause infinite loops.  This is avoided by
preceding the loading of the second and subsequent `.sty`
files with `\let\color\@ldc@l@r`.  E.g.,

\begintt
\input miniltx
\input color.sty
  \let\color\@ldc@l@r
\input graphicx.sty
  \let\color\@ldc@l@r
  \expandafter\def\expandafter\+\expandafter{\+}
\input url.sty
\resetatcatcode
\endtt

The \LaTeX\ package `path.sty` can be
loaded into plain \TeX\ directly, without `miniltx`.

\beginsection tex2page.tex and tex2page.sty

\index{tex2page.tex@`tex2page.tex`}
\index{tex2page.sty@`tex2page.sty`}
%
A collection of workable \TeX\ definitions for \TeX2page commands is
provided in the macro file `tex2page.tex` in the
\TeX2page distribution.  These allow your document to be
processed by \TeX, even if they do not (and sometimes
should not) have the same effect in the DVI output as
they do in the HTML output.  It
can be included in your \TeX\ document as

\begintt
\input tex2page
\endtt
%
The file is also available
under the \LaTeX-friendlier name `tex2page.sty`, and can be
loaded into \LaTeX\ with:

\begintt
\usepackage{tex2page} % if document is in |LaTeX
\endtt

The macros in `tex2page.tex` are just sample
definitions of the \TeX2page commands missing in \TeX.
You can either choose not to use these commands or to
override their definitions with your own, better,
definitions.

\index{tex2page.tex@`tex2page.tex`!not using}

Note that \TeX2page itself does not {\em need} the file
`tex2page.tex`.  Rather, plain \TeX\ and \LaTeX\ need the
`tex2page.tex` macros in order to process files
written using the extra commands supported by \TeX2page.
If your document does not use these extra
commands, then you can do without `tex2page.tex`.

\beginchapter   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.

\beginsection  Multiple pages

\xrdef{eject}
\index{page breaks, forcing good}
\index{eject@`\eject`}
\index{vfill@`\vfill`}
\index{chapter@`\chapter`}
%
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.~\ref{singlepage}).

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

\index{navigation bar}
By default, \TeX2page will generate a {\em navigation
bar} at the top and at the bottom of each HTML page, with
links to the {\em first}, {\em
previous}, and {\em 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.~\ref{texlayout}).

\beginsection Table of contents

\index{table of contents}
\index{tableofcontents@`\tableofcontents`}
\index{readtocfile@`\readtocfile`}
\index{tocdepth@`\tocdepth`}
%
\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`.

\index{writenumberedtocline@`\writenumberedtocline`}
\index{addcontentsline@`\addcontentsline`}
%
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`.

\beginsection Footnotes

\index{footnotes}
\index{footnote@`\footnote`}
\index{vfootnote@`\vfootnote`}
\index{numberedfootnote@`\numberedfootnote`}
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.\f{Footnotes are separated from the body of
the page by a horizontal rule.}

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

\begintt
\newcount\footnotenumber

\def\numberedfootnote{%
  \global\advance\footnotenumber by 1
  \footnote{$^{\the\footnotenumber}$}}
\endtt
%
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:

\index{newcount@`\newcount`}
\index{def@`\def`}
\index{ifcase@`\ifcase`}
\index{or@`\or`}
\index{fi@`\fi`}
\index{global@`\global`}
\index{advance@`\advance`}
\index{ifnum@`\ifnum`}
\index{the@`\the`}
\begintt
\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}}}
\endtt

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

\beginsection Bibliographies

\index{cite@`\cite`}
\index{BibTeX@\BibTeX}
\index{bibliographies}
%
\TeX2page
can use the external program \BibTeX~\cite{latex,latex-companion,bibtex} 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.

\index{thebibliography@`thebibliography`}
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~\cite{latex,latex-companion}.

\beginsection Index generation

\index{index@`\index`}
\index{MakeIndex}
\index{indices}
%
\TeX2page can use the external program
MakeIndex~\cite{ind,makeindex} to generate indices.
\TeX2page’s index-generation feature follows the same
conventions as traditionally used with \TeX\ and its
derived packages~\cite{latex,latex-companion}.

\index{printindex@`\printindex`}
\index{inputindex@`\inputindex`}
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.

\index{ii@`\ii`}
\index{iid@`\iid`}
\index{iis@`\iis`}
\index{makeindex@`\makeindex`}
%
\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.

\beginsection Internal cross-references

\index{label@`\label`}
\index{ref@`\ref`}
\index{pageref@`\pageref`}
\index{cross-references!internal}
\LaTeX’s `\label` and `\ref` produce internal
cross-references in the HTML.  The `\label` {\em 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.

\index{xrtag@`\xrtag`}
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.

\begintt
\xrtag{|meta[alabel]}{|meta[alabelvalue]}
\endtt
%
A reference to this tag, i.e.,
\p{\ref{|meta[alabel]}}, will typeset as
\p{|meta[alabelvalue]}, which will link to the location
identified by the `\xrtag`.\f{%
%
Eplain offers a version of `\xrtag` which it calls
`\definexref`.  \TeX2page recognizes Eplain’s `\refn` and
`\xrefn` as synonyms for the `\ref` described
above.  Eplain also has a `\ref` macro, but it
behaves differently than a \LaTeX-like `\ref`.}

\beginsection
{\color[HTML]{8601AF}C}{\color{blue}o}{\color{green}l}{\color{yellow}o}{\color[HTML]{FFA500}r}{\color{red}s}

\xrdef{color}
\index{color@`\color`}
\index{colorbox@`\colorbox`}
\index{definecolor@`\definecolor`}
\index{color.sty@`color.sty`}
\index{xcolor.sty@`xcolor.sty`}
\TeX2page recognizes the macros `\color`, `\colorbox`, and
`\definecolor`~\cite{grfguide} provided by the \LaTeX\ package
`color.sty`. It also recognizes the {\em 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`.

\begintt
{\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}.
\endtt
produces

\quote
{\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}.
\endquote
%
\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.,

\begintt
\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}.
\endtt
produces

\definecolor{dodgerblue}{Hsl}{210, 1, .56}
\definecolor{orangered}{Hsl}{16, 1, .5}
\definecolor{thistle}{Hsl}{288, 1, .71}
\quote
Poor Mr Norrell could only watch on helplessly as the gentleman
with the {\color{thistle}thistle hair} seized his
copies of \colorbox{dodgerblue}{\color{white} The \TeX book} and
\colorbox{orangered}{\color{white} The \MF book}.
\endquote

\iffalse
\index{x11rgb.tex@`x11rgb.tex`}
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.
\fi

\index{dvipsnam.def@`dvipsnam.def` (\LaTeX\ file)}

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

\beginchapter 5 Referring to external documents

\index{urlhd@`\urlhd`}
\index{cross-references!external}
\index{URLs}
%
The command

\begintt
\urlhd{|meta[URL]}{|meta[HTML text]}{|meta[DVI text]}
\endtt
%
lets
you link to arbitrary URLs, not just to labels within
your document (although it can do that too).  In the
HTML output, a hyperlink to ‘\p{|meta[URL]}’ is created, with
the link text being ‘\p{|meta[HTML text]}’.  In the DVI
output, the part ‘\p{|meta[DVI text]}’ is output.  Example:

\begintt
For more details, consult
\urlhd{http://www.ithaka.org/odyssey.html}{the Odyssey}{the
{\it Odyssey\/} document in the Ithaka repository}.
\endtt
%
In the DVI output, this becomes

\quote
For more details, consult the {\it Odyssey\/} document in the
Ithaka repository.
\endquote
In the HTML output, it would be

\quote
For more details, consult {\em the Odyssey}.
\endquote
where
“{\em the Odyssey}” is an HTML link to the site
\path|http://www.ithaka.org/odyssey.html|.

`\urlhd` is named to be mnemonic for its
argument sequence, viz., the {\em URL}, followed by
the {\em H}tml text, followed by the {\em D}vi
text.

Note that you can use `\urlhd` for cross-referencing
within the document also.  The URL in such cases will
be a label as specified by a `\label` or a
`\xrtag` command, but should add a ‘`#`’ prefix.  E.g.,

\begintt
See \urlhd{#hairy}{below}{section~\ref{hairy}}
for further details.
\endtt
%
where the further details are described in a section
annotated with `\label{hairy}`.  Assume this
section is numbered 21.  Then, the reference typesets
as “See section 21 \dots” in the DVI output and “See
{\em below} \dots” in the HTML output (with {\em below}
being a link).  In contrast, if we had written

\begintt
See section~\ref{hairy} for further details.
\endtt
%
we would have had “See section 21 \dots” in both
DVI and HTML.   `\urlhd` is thus more flexible
than `\ref`.

Because of page breaks in the HTML output
(p.~\ref{eject}), it is possible that a label’s
definition and the references to it do not ultimately
sit on the same {\em physical} HTML page.
Nevertheless, your \TeX\ source can use `#tag`-style
URLs to refer to anchors anywhere within it.  \TeX2page
will automatically convert a `#tag`-style URL to its
correct fully qualified equivalent.

\beginsection Common hyperlink abbreviations

\index{href@`\href`}
In some cases, `\urlhd`’s second and third arguments may be mere repetitions
of a preceding argument.  For such cases, \TeX2page
recognizes some convenient abbreviations, viz.,
`\urlh`, `\urlp`, and `\url`.  (A version of
`\urlh` is provided under the name `\href` by the \LaTeX\ package
`hyperref.sty`, and `\url` is provided by the
\LaTeX\ package `url.sty`.  `\url.sty` is loadable in
plain \TeX\ with `miniltx`.)

\index{urlh@`\urlh`}
`\urlh` takes {\em two} arguments.  The first argument is the
URL, and the second is the descriptive text that is used in
{\em both} the HTML and the DVI outputs.  For example:

\begintt
\TeX\ is available at
\urlh{http://www.tug.org}{the TUG website}.
\endtt
%
produces

\quote
\TeX\ is available at the TUG website.
\endquote
In the HTML output, “the TUG website” is a hyperlink to
\path|http://www.tug.org|.

\index{\\@`\\`!in `\urlh`}
An optional `\\` may be used inside `\urlh`’s second argument.  The
text before the `\\` is used in both the HTML and the DVI
outputs.  The text after the `\\` is used only in
the DVI output.  This helps you to specify extra information
for the DVI output, which may be necessary because the DVI
output lacks the information implicit in the hyperlink.  For example:

\begintt
\TeX\ is available at
\urlh{http://www.tug.org}{TUG\\ (\path!tug.org!)}.
\endtt
%
produces, in the DVI output.

\quote
\TeX\ is available at TUG (\path!tug.org!).
\endquote
The HTML output will not mention the parenthesized domain
name, since the word “TUG” already hyperlinks to it.

`\\` is useful for internal cross-references too.  For
example (assuming the label `callcc` refers to section 2.3):

\begintt
More complicated forms of program control are possible
using \urlh{#callcc}{{\tt callcc}\\ (section~\ref{callcc})}.
\endtt
%
produces

\quote
More complicated forms of program control are possible using
{\tt callcc} (section~2.3).
\endquote
in the DVI output.  In the HTML output, the parenthesized
section reference will be dropped as redundant, as
the word “{\tt callcc}” hyperlinks to the relevant section.

An optional `\1` may be used after `\\` to refer to
`\urlh`’s first argument, i.e.,
the URL.
Example:

\begintt
\TeX\ is available at
\urlh{http://www.tug.org}{TUG\\ (\1)}.
\endtt
%
produces

\quote
\TeX\ is available at TUG (\path|http://www.tug.org|).
\endquote
in the DVI output.  In the HTML output, the parenthesized
URL is dropped as redundant, as the word “TUG”
hyperlinks to it.

Finally, the combination of `\xrtag` and
`\urlh` is useful for inserting
internal cross-references in the HTML document
without affecting the print document.  For example,
the following text

\begintt
\xrtag{ex1}{ignore}
\urlh{#ans1}{\bf Exercise 1.} Statement of a problem ...

... lots of intervening stuff ...

\xrtag{ans1}{ignore}
\urlh{#ex1}{\bf Answer 1.} Answer to exercise 1 ...
\endtt
%
prints as

\quote
{\bf Exercise 1.} Statement of a problem \dots

\dots\ lots of intervening stuff \dots

\n {\bf Answer 1.} Answer to exercise 1 \dots
\endquote
in both the DVI and the HTML.  However, in the
HTML, the proclamations “{\bf Exercise 1.}”\ and
“{\bf Answer 1.}”\ are also helpful hyperlinks to each other.

\index{url@`\url`}
`\url` takes just one argument, the URL.  For the
descriptive text, both the HTML and the DVI outputs simply
use the URL itself.   Example:

\begintt
\TeX\ is available at \url{http://www.tug.org}.
\endtt

\index{urlp@`\urlp`}
`\urlp` takes two arguments.  In the HTML output,
the first argument is the link text and the second is
the URL.  In the DVI output, the first argument is
typeset followed by a space followed by the URL in
parentheses.  \p{\urlp{|meta[text]}{|meta[URL]}} abbreviates
\p{\urlh{|meta[URL]}{|meta[text]\\ (\path+|meta[URL]+)}}.

\beginchapter      6 Flags

\index{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 `\def`s for a boolean flag, only the
first character in the `\def`-body is significant.)

\beginsection External title

\index{TZPtitle@`\TZPtitle`}
\index{title@`\title`}
\index{maketitle@`\maketitle`}
%
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.,

\begintt
\def\TZPtitle{The Odyssey}
\endtt
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`.

\beginsection Language

\index{TZPlang@`\TZPlang`}
%
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.,

\begintt
\def\TZPlang{de} % German
\endtt

\beginsection 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.

\index{TZPcolophonlastpage@`\TZPcolophonlastpage`}
(i) To put the colophon on the last rather than the first page,

\begintt
\let\TZPcolophonlastpage=1
\endtt

% If this request is to have meaning, it should be made in the document
% before the text for the second HTML page starts.  Otherwise, the default
% first-page placement of the colophon will have already taken effect.

\index{TZPcolophondisabletimestamp@`\TZPcolophondisabletimestamp`}
(ii) To avoid mentioning the timestamp of the document in the
colophon,

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

\index{TZPcolophondisablecredit@`\TZPcolophondisablecredit`}
(iii) To avoid crediting \TeX2page in the colophon,

\begintt
\let\TZPcolophondisablecredit=1
\endtt

\index{TZPcolophondisableweblink@`\TZPcolophondisableweblink`}
(iv) To avoid linking to the \TeX2page website in the colophon,

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

\beginsection Math image flag

\xrdef{mathflag}
\index{TZPmathtext@`\TZPmathtext`}
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

\begintt
\let\TZPmathtext=1
\endtt
%
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.

\beginsection Image conversion flags

\xrdef{imageconv}
\index{image!conversion}
\index{Ghostscript}
\index{Dvips}
\index{NetPBM}
\index{ImageMagick}
\index{image!format}
\index{gif@`gif` (image format)}
\index{jpeg@`jpeg` (image format)}
\index{png@`png` (image format)}
%
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~\cite{dvips} to create a PostScript version of the
graphic, and then Ghostscript~\cite{gs} and either (i) the
NetPBM library~\cite{netpbm}, or (ii) the ImageMagick
library~\cite{imagemagick}, to convert the PS into the
HTML-suitable image.

\index{TZPimageconverter@`\TZPimageconverter`}
\index{TZPimageformat@`\TZPimageformat`}
The defaults are: NetPBM
to convert, and PNG to convert to.
You may set the flags `\TZPimageconverter` and `\TZPimageformat` to
change this, e.g,

\begintt
\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)
\endtt

\beginsection \TeX\ executable used for image generation

\index{TZPtexprogname@`\TZPtexprogname`}
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.,

\begintt
\def\TZPtexprogname{xetex}
\endtt
%
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.~\ref{imgpreamble}) you use match the
document’s format.)

\beginsection Flag for Lisp code comments

\xrdef{slatexlikecomments}
\index{TZPslatexcomments@`\TZPslatexcomments`}
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

\begintt
\let\TZPslatexcomments=1
\endtt
%
This is the style favored by S\LaTeX.
\ifx\shipout\UnDeFiNeD
With `\TZPslatexcomments` set, the text

\begintt
\scm{
(open-input-string ; in Scsh, use \scm{string->input-port}
  s)
}
\endtt
%
produces
\let\TZPslatexcomments 1

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

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

\beginsection Flags for page and paragraph layout

\index{TZPtexlayout@`\TZPtexlayout`}
\xrdef{texlayout}
%
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

\begintt
\let\TZPtexlayout=1
\endtt

\index{hsize@`\hsize`}
\index{hoffset@`\hoffset`}
\index{voffset@`\voffset`}
\index{parskip@`\parskip`}
\index{parindent@`\parindent`}
\index{headline@`\headline`}
\index{footline@`\footline`}
%
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

\index{folio@`\folio`}
%
\begintt
\ifx\shipout\UnDeFiNeD
  \hsize=36em
  \headline={\folio, ~~ \urlh{#ToC}{ToC}, ~~ \urlh{#Index}{Index}}
  \footline={\the\headline}  % i.e., footline same as headline
\fi
\endtt
%
 where the tags `ToC` and `Index` are set near
the ToC and Index respectively.

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

\index{TZPhsize@`\TZPhsize`}
%
(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

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

\index{TZPautomargin@`\TZPautomargin`}
%
(iii) To keep the body of the page horizontally centered, i.e.,
with equal left and right margins, use

\begintt
\let\TZPautomargin=1
\endtt
%
Note this centers the body as a block, {\em 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.

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

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

\index{TZPtextext@`\TZPtextext`}
%
(v) Finally, \TeX\ uses pseudo-ligatures to convert
occurrences of \p{`}, `'`, \p{``}, \p{''}, `--`, 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 \XeTeX\ 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,

\begintt
\let\TZPtextext=0
\endtt
%
In this case, you also have to ensure that the fonts you use in
\XeTeX\ do not have `mapping=tex-text`.

\beginsection Making a slideshow

\index{TZPslides@`\TZPslides`}
\index{t2pslides.tex@`t2pslides.tex`}
\index{presentations}
%
To produce a Web presentation,
set the flag `\TZPslides`:
\begintt
\let\TZPslides=1
\endtt
%
This causes \TeX2page to use the style sheet `slidy.css` and JavaScript file
`slidy.js`
from Slidy~\cite{slidy} 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.

\beginsection Page redirection

\index{TZPredirect@`\TZPredirect`}
\index{TZPredirectseconds@`\TZPredirectseconds`}
(i) If you wish your HTML output to immediately redirect elsewhere,
set the flag `\TZPredirect` to contain the target URL.

\begintt
\def\TZPredirect{http://newhome.com/path/samedoc.html}
\endtt
%
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 `\eject`s 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.,

\begintt
\def\TZPredirectseconds{10}
\endtt

\beginsection Single output file

\index{TZPsinglepage@`\TZPsinglepage`}
\xrdef{singlepage}
%
Sometimes it is desirable to generate just a single output HTML file, i.e., to
not generate a page break as described on p.~\ref{eject}, and to have all the
images embedded as data URIs within the document. To do this, set the
`\TZPsinglepage` flag:

\begintt
\let\TZPsinglepage=1
\endtt

\beginsection OPmac

The flag `\TZPopmac` can be set to 1 to inform \TeX2page that
you’re using OPmac macros~\cite{opmac} 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 `[]`.

\beginsection Common Lisp or Scheme?

\index{TZPcommonlisp@`\TZPcommonlisp`}
The flag `\TZPcommonlisp` can be used to decide whether calls to
`\eval` (p.~\ref{eval}) 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 {\em
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.

\beginchapter  7 Style

\xrdef{css}
\index{inputcss@`\inputcss`}
\index{cascading style sheet}
\index{style sheet}
%
You can use the \TeX2page command `\inputcss` to have your HTML output use {\em style
sheets}~\cite{w3c:css,lb:css}.  E.g.,

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
  \inputcss basic.css
\fi
\endtt
%
in your \TeX\ source will cause the HTML output to
use the presentation advice contained in the
style sheet `basic.css`.

In the style sheet, you can have rules for the various
HTML elements to change the appearance of your
document.  E.g., if you do not want your HTML page
width to increase beyond a certain point (regardless of
how the wide the reader makes their browser window),
you could put the following in your style sheet:

\begintt
body {
  max-width: 36em;
}
\endtt
As another example, here’s a way to convert itemized lists (aka
“bulleted” or unordered or unnumbered lists) to
enumerations\f{It’s easier for people to discuss an item
explicitly marked ‘vii’ (or ‘7’, or ‘g’, or ‘$\eta$’) rather than
having all of them count up to the seventh bullet. If you’re using
more than three bullets per list, you’re shooting yourself in the
foot.}:

\begintt
ul {
  list-style-type: lower-roman;
}
\endtt

You can get finer control on the look of your document
by defining rules for some classes that are peculiar to
\TeX2page.  These special classes
are discussed in this manual alongside the commands
that they govern (p.~\ref{verb-style}).
%also \ref{syntax-hilite}

You can have as many `\inputcss`’s in your
document as you wish.  They will be combined in
the sequence in which they appear.  It is perhaps
necessary to add that style sheets are completely
optional.

\index{cssblock@`\cssblock`}
\index{endcssblock@`\endcsslblock`}

You can also {\em embed} style sheet information
in the \TeX\ source between the control sequences
`\cssblock` and `\endcssblock`.  E.g.,

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
\cssblock
body {
  max-width: 36em;
}

ul {
  list-style-type: lower-roman;
}
\endcssblock
\fi
\endtt
%
You can
have multiple `\cssblock`s in the document; they
are all evaluated in sequence.

\TeX2page generates a very basic default style
that
does little beyond setting some margins.  You
can augment or override the default style by supplying your
own style info via `\cssblock` or by loading
style sheets with `\inputcss`.   Some general-purpose
style sheets available on the Web are the W3C Core
Styles~\cite{w3ccorestyles} and Google Fonts~\cite{googlefonts}.
Here are two examples of using the latter:

(i) To use Libre Baskerville for your body text:

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
\inputcss https://fonts.googleapis.com/css?family=Libre+Baskerville&display=swap

\cssblock
body {
  font-family: 'libre baskerville', serif;
}
\endcssblock
\fi
\endtt

\index{oldstyle@`\oldstyle`}
(ii) \TeX2page has a CSS class `.oldstyle` in place for translating
\TeX’s `\oldstyle` macro. However, for this to actually show up
as something meaningful in your HTML, e.g.,

\quote
`{\oldstyle 2{\rm.}718281828}` as {\oldstyle 2{\rm.}718281828}
\endquote
you need to add a suitable CSS definition for `.oldstyle`.
One way is to go trawling through Google Fonts for
a font that has oldstyle numerals:

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
\inputcss https://fonts.googleapis.com/css?family=Linden+Hill&display=swap

\cssblock
.oldstyle {
  font-family: 'linden hill';
  font-size: 110%;
}
\endcssblock
\fi
\endtt

\beginchapter  8 Verbatim text
%\label{verbatim}

\index{verb@`\verb`}
%
\TeX2page recognizes a slightly enhanced version of
\LaTeX’s `\verb` command.
Recall that \LaTeX’s `\verb`’s argument is enclosed
within a pair of identical characters (not whitespace
or `*`), and this argument is printed verbatim.  This
is useful for typesetting things like fragments of computer code.
E.g.,

\p$
A \verb|cons|-cell has two components: a \verb+car+ and
a \verb&cdr&.
$

\n is converted to

\quote
A \verb|cons|-cell has two components: a \verb+car+ and
a \verb&cdr&.
\endquote
The \TeX2page version of `\verb` adds a couple more features:

(i)
You can use
matching braces to enclose its
argument, provided the latter does not contain unmatched
braces.  E.g.,

\begintt
The command \verb{\section{Imagining a Conscious Robot}}
typesets ‘\verb{Imagining a Conscious Robot}’ as a section
title.
\endtt
%
is converted to

\quote
The command \verb{\section{Imagining a Conscious Robot}}
typesets ‘\verb{Imagining a Conscious Robot}’ as a section
title.
\endquote

(ii) If `\verb`’s argument commences with a newline, it is
set as a display.  E.g.,

\begintt
\verb{
(define compose
  (lambda (f g)
    (lambda aa
      (f (apply g aa)))))
}
\endtt
%
produces

\begintt
(define compose
  (lambda (f g)
    (lambda aa
      (f (apply g aa)))))
\endtt
%
%stopzone
%
Note that such displays faithfully typeset all the
whitespace of the text, including linebreaks and
indentation.

\index{verb*@`\verb*`}
\index{*@`*`!for visible verbatim space}

As in \LaTeX, if a `*` immediately follows `\verb`, any spaces in
`\verb`’s argument text are highlighted as something
that is visible.  This allows you to easily count
spaces or tell if there is trailing space on a line.

\begintt
\verb*{three   spaces}
\endtt
%
produces

\quote
\verb*{three   spaces}
\endquote

\beginsection Commands within verbatim

\xrdef{verbesc}
\index{-@\p+"|+}
%
Often you want to use \TeX\ commands in special spots within
verbatim text, especially displayed verbatim material.  For
this reason, the character ‘`|`’ is allowed as an escape
character {\em if the verbatim text is enclosed within
braces}.

\index{def@`\def`}

As an example, let’s say you’ve defined an `\evalsto`
macro to use in cases where you want to say a program
expression {\em evaluates to} a result.  A possible
definition is:

\begintt
\def\evalsto{::==}
\endtt
%
\def\evalstoI{::==}
%
You could use `\evalsto` inside a verbatim
display as follows:

\p+
\verb{
(cons 1 2) |evalsto (1 . 2)
}
+

\n This will produce

\begintt
(cons 1 2) |evalstoI (1 . 2)
\endtt
%
Some standard commands that can be used inside braced
verbatim are: \p+||+ to insert the escape character itself; and
\p+|{+ and \p+|}+ to insert the occasional non-matching brace.

%fmrly subsubsec
\beginsection Changing the verbatim escape character

\index{verbatimescapechar@`\verbatimescapechar`}
%
You can use the Eplain and \TeX2page macro `\verbatimescapechar` to
postulate a character other than ‘\p+|+’ as the
verbatim escape.  E.g.,

\begintt
\verbatimescapechar\@
\endtt
%
makes ‘`@`’ the verbatim escape.

\beginsection Other common verbatim macros

\index{verbatim@`{verbatim}`}
\index{path@`\path`}
\index{activettchar@`\activettchar`}
\index{DefineShortVerb@`\DefineShortVerb`}
%
\TeX2page also understands \LaTeX’s `{verbatim}`
and `{verbatim*}`
environments, Eplain’s `\verbatim`, the `\path` macro from `path.sty`,
and the `{Verbatim}` and `{Verbatim*}` environments from
`fancyvrb.sty`.

It recognizes  `fancyvrb`’s `\DefineShortVerb` and OPmac’s
`\activettchar`.
Setting \verb{\DefineShortVerb{\`}} or
\verb{\activettchar`} lets you write
\verb+\verb`\c@de_fr&gm%#t$`+
as simply
\verb+`\c@de_fr&gm%#t$`+,
as in AsciiDoc. Setting
\verb+\DefineShortVerb{\|}+ or
\verb+\activettchar|+ lets you write
\verb+|\c@de_fr&gm%#t$|+,
as in `manmac`.

\index{begintt@`\begintt`}
\index{endtt@`\endtt`}
\index{tthook@`\tthook`}
%
It also recognizes `manmac`’s `\begintt` `...` `\endtt`, but note
that by
default, \TeX2page’s `\begintt` sets {\em everything} within it verbatim. If you
want it to be truly `manmac`-like, i.e., with `|` as the escape
character and `\]` producing visible space, you should set
`\tthook` to something suitable:

\p+
\def\tthook{\catcode`\|=0
  \def\|{char`\|}%
  \def\ {·}}
+
If you also have \p{\activettchar`}, then set `\tthook` {\em before} you set `\activettchar`.

\beginsection Inserting files verbatim

\index{verbatim.sty@`verbatim.sty`}
\index{verbatiminput@`\verbatiminput`}
\index{listing@`\listing`}
%
You can insert files verbatim with the command
`\verbatiminput` (from \LaTeX’s `verbatim.sty`) or with Eplain’s
`\listing`.  Usage:

\begintt
\verbatiminput{program.lisp}
\endtt

\beginsection Writing to files

\xrdef{verbwritefile}
\index{verbwrite@`\verbwrite`}
%
The command `\verbwrite`, used like `\verb`, does
not typeset its enclosed text but outputs it verbatim
into a text file.  The text file has by default the
same basename as the document, but with extension
`.txt`.

\index{verbwritefile@`\verbwritefile`}

To specify another text file, use `\verbwritefile`.
E.g.,

\begintt
\verbwritefile notes-to-myself.txt    % or
\verbwritefile{notes-to-myself.txt}
\endtt
%
This will cause subsequent calls to
`\verbwrite` upto the next `\verbwritefile` or end
of document (whichever comes first) to send text into
the file `notes-to-myself.txt`.  `\verbwritefile`
deletes any pre-existing contents of its argument file.

\index{write@`\write`}
%
\TeX2page also recognizes the \TeX\ command
`\write`, which takes two arguments: an {\em output
stream number} and a \TeX\ expression to be output.
Recall that \TeX\ allows only the numbers 0–15 for
output streams that can be associated with files;
numbers outside this range are deemed to represent
standard output.

\xrdef{write18}
\index{write@`\write`!to stream 18}
%
However: \TeX2page follows modern
\TeX\ implementation practice in treating the output
stream 18 specially.  \p{\write18{|meta[oscommand]}},
instead of writing \p{|meta[oscommand]} to standard
output, will execute it as an operating-system command!
This is not standard \TeX\ behavior, but most modern \TeX s
enable this feature with a command-line option that is
either `-shell-escape` or
`--enable-write18` (use `--help` on your \TeX\ executable(s) to find
out).

\beginsection Verbatim style

\xrdef{verb-style}
The verbatim commands (`\verb`, `\path`
and `\verbatiminput`, etc.)\ introduced above use a style class
called `verbatim`.  You can affect the appearance
of your verbatim text by defining a style for
`verbatim` in a style sheet (p.~\ref{css}).  E.g.,

\begintt
.verbatim        {color: hsl(205,100%,16%)}
\endtt
%
sets {\color[Hsl]{205,1,.16} `all verbatim text
in Prussian blue`}.

\beginsection Syntax-highlighting of program code

\xrdef{syntax-hilite}
\index{syntax highlighting}
\index{scm@`\scm`}
\index{scminput@`\scminput`}
%
The commands `\scm` and `\scminput` are variants
of `\verb` and `\verbatiminput`.  They are
useful for producing syntax-highlighted Lisp
code in the HTML file.  E.g.,

\begintt
\scm{
(defun factorial (n)
  (when *debug*
    (format t "Calling factorial ~a~%" n))
  (if (= n 0) 1 ;the base case
      (* n (factorial (1- n)))))
}
\endtt
\ifx\shipout\UnDeFiNeD % since the colors won’t show on the DVI
produces

\begintts
(defun factorial (n)
  (when *debug*
    (format t "Calling factorial ~a~%" n))
  (if (= n 0) 1 ;the base case
      (* n (factorial (1- n)))))
\endtt
(Your browser needs to support style sheets for the
syntax-highlighting to show.)
\fi

Seven categories of code text are distinguished:

(i) background punctuation;

(ii) self-evaluating atoms (numbers, booleans, characters, strings);

(iii) syntactic keywords;

(iv) builtin variables;

(v) global or special variables, viz., identifiers that begin and end with an asterisk;

(vi) other variables; and

(vii) comments.

To distinguish between the categories of Lisp code
text, \TeX2page uses a style class called `scheme`
with six subclasses, viz., `selfeval`,
`keyword`, `builtin`, `global`, `variable`, and
`comment`.  You can set the `color` property (and
other properties like `font-weight` and
`font-style`) of these classes in a style
sheet (p.~\ref{css}).  The default settings are:

\begintt
.scheme             {color: hsl(280,33%,30%)} /* background punctuation */
.scheme  .selfeval  {color: hsl(120,100%,20%); font-style: normal}
.scheme  .keyword   {color: hsl(0,100%,20%);   font-style: normal; font-weight: bold}
.scheme  .builtin   {color: hsl(0,100%,20%);   font-style: normal}
.scheme  .global    {color: hsl(300,100%,20%); font-style: normal}
.scheme  .variable  {color: hsl(240,100%,20%); font-style: normal}
.scheme  .comment   {color: hsl(180,100%,20%); font-style: oblique}
\endtt
%
\index{scmkeyword@`\scmkeyword`}
\index{scmbuiltin@`\scmbuiltin`}
\index{scmvariable@`\scmvariable`}
%
\TeX2page initially only recognizes some well-known
syntactic keywords, global variables, and
self-evaluators.  It does not recognize builtins as
apart from the general run of variables.  Users who
want builtins distinguished can use
`\scmbuiltin`, e.g.,

\begintt
\scmbuiltin{cons car cdr}
\endtt

Users who do not want to distinguish Common Lisp–style
global (“special”) variables as a separate category from
other variables should give the style class `.global` the
same properties as `.variable`, e.g.,

\begintt
.scheme .global {color: hsl(240,100%,20%}
\endtt

Users can add their own keywords with `\scmkeyword`.
E.g.,

\begintt
\scmkeyword{define-class unwind-protect}
\endtt

By default, tokens that don’t fall in any of the
other categories are set as variables.  However,
`\scmvariable` can be used to explicitly identify as
variables those tokens that are currently treated as
non-variables (e.g., keywords or self-evaluators).  E.g.,

\begintt
\scmvariable{and 42 +i}
\endtt

%fmrly subsub
\beginsection Using S\LaTeX\ commands

\index{scheme@`\scheme`}
\index{schemedisplay@`{schemedisplay}`}
%
\TeX2page also syntax-highlights Lisp code introduced
using the S\LaTeX\ commands, chiefly
`\scheme` and `{schemedisplay}`.  S\LaTeX\ users know
that these commands typeset code in the DVI output
using fonts (rather than color) for highlighting.
For the HTML, \TeX2page will use color.

A minor point is that S\LaTeX’s commands allow \TeX\
commands inside Lisp comments.  This is useful
if you want to highlight mentions of Lisp code inside
Lisp comments.  To get the same effect with \TeX2page,
use the `\TZPslatexcomments` flag (p.~\ref{slatexlikecomments}).

\beginsection Documenting your code

\index{scmdribble@`\scmdribble`}
\index{literate programming}
%
You can use \TeX2page to do a form of {\em literate
programming}, i.e., combining your documentation with
your code.  The command `\scmdribble`, which is used
like `\scm`, will not only display the enclosed code,
but also send it to the external file named by
the most recent `\verbwritefile`.

To specify code that should go into the external file but
should not be displayed, simply use
`\verbwrite` instead of `\scmdribble`.

\beginchapter  9 Images
%\label{images}

\index{mathematics}
\index{pictures}
\index{picture@`picture` (\LaTeX\ environment)}
\index{diagrams}
\index{image}
\index{image!file}
\index{digital camera}
%
Some portions of your \TeX\ source may be explicitly
images, or text that is particularly resistant to
conversion to HTML.  Examples are JPEGs from digital cameras, encapsulated
PostScript inserts, mathematics, and the \LaTeX\
`{picture}` environment.   \TeX2page embeds these as images in the HTML
output.

\beginsection Mathematics

\index{$$@{\tt\$\$}} %$$
%
Math is typically text between `$...$` (in-text
math) and `$$...$$` (displayed math).  Here are some
samples of mathematics with \TeX:

\begintt
$$ F = G {m_1 m_2 \over r^2 } $$

$$ \int_0^\infty { t - ib \over t^2 + b^2} e^{iat}\,dt =
e^{ab} E_1(ab), \qquad a, b > 0 $$

$$ A =
\left(
\matrix{ x - \lambda & 1           & 0           \cr
         0           & x - \lambda & 1           \cr
         0           & 0           & x - \lambda \cr}
\right) $$
\endtt
%
These produce, respectively:

$$ F = G {m_1 m_2 \over r^2 } $$

$$ \int_0^\infty { t - ib \over t^2 + b^2} e^{iat}\,dt =
e^{ab} E_1(ab), \qquad a, b > 0 $$

$$ A =
\left(
\matrix{ x - \lambda & 1           & 0           \cr
         0           & x - \lambda & 1           \cr
         0           & 0           & x - \lambda \cr}
\right)
$$

\index{$@{\tt\$}}
%stopzone

In-text mathematics is also available.  E.g.,

\begintt
The Euclidean distance between two points is
$\sqrt{ (\Delta x)^2 + (\Delta y)^2 }$.
\endtt
%
produces

\quote
The Euclidean distance between two points is
$\sqrt{ (\Delta x)^2 + (\Delta y)^2 }$.
\endquote

You can control whether your math displays should
be specified as image or text with the
flag `\TZPmathtext`
(p.~\ref{mathflag}).
\ifx\shipout\UnDeFiNeD
With `\let\TZPmathtext=1`,
the three examples above
look as follows:

\let\TZPmathtext=1
$$ F = G {m_1 m_2 \over r^2 } $$

$$ \int_0^\infty { t - ib \over t^2 + b^2} e^{iat}\,dt =
e^{ab} E_1(ab), \qquad a, b > 0 $$

$$ A =
\left(
\matrix{ x - \lambda & 1           & 0           \cr
         0           & x - \lambda & 1           \cr
         0           & 0           & x - \lambda \cr}
\right)
$$
\let\TZPmathtext=0
\fi

\iffalse
\index{romannumeral@`\romannumeral`}
\index{Romannumeral@`\Romannumeral`}

If you do all your mathematics in roman numbers, you
can avoid math-related images completely.  \TeX2page
recognizes the \TeX\ command `\romannumeral`, which
produces the roman equivalent of the following arabic
number (`\romannumeral 1986` = \romannumeral 1986).
`\romannumeral` produces lower-case letters —
`tex2page.tex` includes `\Romannumeral`, whose
result is all-upper-case  (`\Romannumeral 1986` =
\Romannumeral 1986).
\fi

\beginsection Graphics inclusions
%\label{includegraphics}

\index{encapsulated PostScript}
\index{MetaPost}
%\index{METAFONT@\MF}
\index{Xfig}
\index{GIMP}
\index{Inkscape}
%\index{MFpic}
%
Encapsulated PostScript files (EPS) are a convenient
and popular way to insert pictures (graphics) into \TeX\
documents~\cite{latex-graphics-companion}.
Users create EPS files with their favorite external
programs, which can be GUI tools such as
Inkscape~\cite{inkscape,kirsanov:inkscape,bah:inkscape},
GIMP~\cite{gimp,gimpbook},
and Xfig~\cite{xfig},
or algebraic
ones like MetaPost~\cite{metapost,mfbook}.
\iffalse
It is also
possible to write a picture’s specification in
the document, while still relying on an external
program to make sense of it.  An example is
MFpic~\cite{mfpic}, whose \TeX\ macros transform
a picture specification inside the document into
an external \MF~\cite{mfbook} or MetaPost file.
\fi

\index{epsfbox@`\epsfbox`}
\index{includegraphics@`\includegraphics`}

However it is created, an EPS file is typically
inserted as a \TeX\ box into a \TeX\ document with calls
like

\begintt
\epsfbox{|meta[eps-file]}
\includegraphics{|meta[eps-file]}
\endtt
%
\index{epsf.tex@`epsf.tex`}
\index{epsfig.sty@`epsfig.sty`}
%
These are commands defined external to plain \TeX\ or \LaTeX.
Plain \TeX\
documents using `\epsfbox` must load the standard
macro file called `epsf.tex`.
\LaTeX\ documents using `\epsfbox` can do the
same, or they can load the `epsfig.sty` package.

\index{DeclareGraphicsRule@`\DeclareGraphicsRule`}

`\includegraphics` is a generic graphics includer that tackles more than
EPS files, based on file extension.  Thus, if your file has a
nonstandard extension, you
will have to inform `\includegraphics` of this using directives like the
following:

\begintt
\DeclareGraphicsRule{.1}{mps}{*}{}
\endtt
%
This states that files with extension `.1` are to be treated as EPS
files generated by MetaPost.

\index{graphicx.sty@`graphicx.sty`}
\index{miniltx.tex@`miniltx.tex`}

`\includegraphics` is defined in the \LaTeX\ package `graphicx.sty`,
which can also be loaded by
plain-\TeX\ documents with the help of `miniltx.tex`, as we saw
with `color.sty` on p.~\ref{color}.\f{It is possible to `\input`
several `.sty` files between the calls to `\input` `miniltx` and
`\resetatcatcode`.  However, `miniltx` is a bit of a compromise, and it
causes each `.sty` file to re-evaluate the supposedly per-document commands
in the driver file
(e.g., `pdftex.def`), which can cause infinite loops.  This is avoided by
preceding the loading of the second and subsequent `.sty`
files with `\let\color\@ldc@l@r`.}

\begintt
\input miniltx
\input graphicx.sty
\resetatcatcode
\endtt
%
\index{epsfxsize@`\epsfxsize`}
\index{epsfysize@`\epsfysize`}
%
For `\epsfbox`, you can specify the desired image
width and height by assigning to the dimen
registers `\epsfxsize` and `\epsfysize`
(specifying only one of them will cause the other to
change as well, maintaining the image’s aspect ratio).
\TeX2page will respect such sizes, equating one browser
pixel to one point (= 1/72.27 inch).  Thus,

\begintt
\epsfxsize=1.5in
\endtt
%
sets the width of an immediately following `\epsfbox`ed image to
$1.5 \times 72.27 \approx 108$
pixels.
`\epsfxsize` and
`\epsfysize` are cleared after each
`\epsfbox`.

\index{convertMPtoPDF@`\convertMPtoPDF`}
\index{supp-pdf.tex@`supp-pdf.tex`}

If you use pdf\TeX\ or Lua\TeX\ (which produce PDF
instead of DVI output), you can insert
MetaPost-created EPS files with the
`\convertMPtoPDF` command:

\begintt
\convertMPtoPDF{|meta[eps-file]}{1}{1}
\endtt
%
`\convertMPtoPDF` is defined in the macro file
`supp-pdf.tex` of the \ConTeXt\ package,
which is included in most modern distributions of \TeX.
Caveat: `\convertMPtoPDF` doesn’t work for EPS files
that weren’t made using MetaPost!

\index{pdfximage@`\pdfximage`}

pdf\TeX\ can import common graphics formats
such PNG and JPEG: Either use `\includegraphics`, or a primitive call
such as

\begintt
\pdfximage height 1.5in {pic.png}\pdfrefximage\pdflastxmimage
\endtt

\TeX2page recognizes the scaling information supplied with `\pdfximage`
and `\includegraphics`,  with one browser pixel
equated to one point.  Unlike EPS files, PNG and JPEG images are directly
supported by HTML, so \TeX2page does not need to convert them.

\index{XeTeXpdffile@`\XeTeXpdffile`}
\index{XeTeXpicfile@`\XeTeXpicfile`}
\index{epstopdf@`epstopdf`}

\XeTeX\ has its own duo of graphics-insertion commands:
`\XeTeXpdffile` for PDF images, and `\XeTeXpicfile` for
JPEG and GIF images. E.g.,

\begintt
\centerline{\XeTeXpicfile tbdek.jpg width 3in \relax}
\endtt
for

\ifx\XeTeXversion\UnDeFiNeD
\centerline{\includegraphics[width=3in]{tbdek.jpg}}\else
\centerline{\hbox{\XeTeXpicfile tbdek.jpg width 3in \relax}}
\fi

There are two ways to load a graphic specified in MetaPost:

(i) You can have MetaPost convert the spec to EPS, and
then use a utility like `epstopdf` to convert the EPS to PDF.
Let’s start with a MetaPost file
\urlh{mpexample.html}{`lambda.mp`}. At the OS shell, type:

\begintt
mpost lambda.mp
epstopdf lambda-1.eps
\endtt

\write18{if test ! -f lambda-1.pdf -a -f lambda.mp; then mpost lambda.mp; epstopdf lambda-1.eps; fi}
This creates a PDF file `lambda-1.pdf`, which is inserted in
the source document via

\begintt
\centerline{\XeTeXpdffile lambda-1.pdf }
\endtt
to obtain\f{%
\index{scrollmode@`\scrollmode`}
\index{notstopmode@`\nonstopmode`}
\index{batchmode@`\batchmode`}
\index{errorstopmode@`\errorstopmode`}
%
The file
`lambda.mp` was actually written out from this document’s
source using `\verbwrite` (p.~\ref{verbwritefile}),
so the files `lambda-1.eps` and `lambda-1.pdf` aren’t immediately available
on the first run. \TeX\ will signal a file-not-found error and go
into a debug loop, even though the MetaPost file needed to create
the missing file can only be created if \TeX\ successfully
finishes processing the source document! To force \TeX\ to finish
processing the source file regardless of missing files, you need
to run it in
`\scrollmode`, or its even more reckless cousins
`\nonstopmode` and `\batchmode`.  One way to get into
these modes is to type `s`, `r`, or `q`,
respectively, at the \TeX\ debug prompt.  By default, \TeX\
runs in `\errorstopmode`, which is why it stops on
the missing-file error. A different approach is to use “shell
escape” to call `mpost` and `epstopdf` from within your
source file. See p.~\ref{write18}.}

\index{centerline@`\centerline`}

\ifx\directlua\UnDeFiNeD
\ifx\XeTeXversion\UnDeFiNeD
\centerline{\includegraphics{lambda-1.pdf}}
\else
\centerline{\XeTeXpdffile lambda-1.pdf }
\fi
\else
\centerline{%
  \mplibcode
  input lambda.mp;
  \endmplibcode
  }%
\fi

(ii) Alternatively, you can have MetaPost directly convert
the spec to
PNG. In `lambda.mp`, change the `outputformat` setting to `png`,
i.e.,

\begintt
outputformat := "png";
\endtt
Metapost will directly produce the file `lambda-1.png`, which
can be inserted with

\begintt
\XeTeXpicfile lambda-1.png
\endtt

\index{mplibcode@`\mplibcode`}
\index{endmplibcode@`\endmplibcode`}
\index{luamplib.sty@`\luamplib.sty`}
%
Lua\TeX\ is perhaps the easiest format when it comes to MetaPost:
input the style file `luamplib.sty`, and insert your MetaPost
code inside `\mplibcode ... \endmplibcode`. (In Lua\LaTeX\ use
the `{mplibcode}` environment.) There is no need to save to any
MetaPost file or call MetaPost specifically.

\beginsection Other image inserts

\index{makehtmlimage@`\makehtmlimage`}
%\index{endhtmlimg@`\endhtmlimg`}
%
%Any \TeX\ fragment enclosed between the control sequences
%`\htmlimg ... \endhtmlimg` is converted into an
%image.  Some \TeX\ fragments are automatically converted
%to images without the need for an explicit
%`\htmlimg`.  Such fragments are mathematics, calls to
%the LaTeX `picture` environment, and
%MFpic~\cite{mfpic} diagrams.\f{MFpic diagrams are
%enclosed between `\mfpic ... \endmfpic`.  The MFpic
%macros translate picture specifications into
%METAFONT~\cite{mfbook} or MetaPost~\cite{metapost}
%programs.  Both METAFONT and MetaPost are included in
%modern \TeX\ distributions, which makes MFpic an
%attractive option for picture-drawing in TeX.  Please
%see the MFpic distribution~\cite{mfpic} for more
%details.} External Encapsulated PostScript files that
%are loaded by \TeX\ are likewise converted into
%images.
%
You may explicitly request any part at all of your \TeX\
document — not just its math or EPS inserts —
to be converted into images for your HTML output.  The
fragment of the document to be converted to image is
given as an `\makehtmlimage` argument.
Here’s an example \TeX-based diagram from {\em
The \TeX book}~\cite[p.~389]{texbook}:

\verbatiminput ursa-major.tex

\n This produces the  image:

%\quote
\smallskip
\input ursa-major
\smallskip
%\endquote

\n `\makehtmlimage`’s argument is a group containing
no unmatched braces.

\beginsection Image preamble

\xrdef{imgpreamble}
\index{imgpreamble@`\imgpreamble`}
\index{endimgpreamble@`\endimgpreamble`}
\index{image!preamble}
%
When converting math, EPS, and other implicit or
explicit `\htmlimage`s into images for HTML, \TeX2page
extracts the small fragment of the \TeX\ document
containing the would-be image into a separate, smaller
\TeX\ file.  The content of this auxiliary \TeX\ file is
then cajoled by a bevy of external programs into
an image file suitable for HTML (p.~\ref{imageconv}).  This demands that
all the \TeX\ code within the auxiliary \TeX\ file be
self-sufficient.  However, it is quite possible that
such \TeX\ fragments contain references to macros
defined elsewhere in the larger document.
\TeX2page therefore provides the `\imgpreamble`
`...` `\endimgpreamble` environment, into which
are placed all the definitions that are necessary for
the HTML images.   For example, the “image preamble”

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
  \imgpreamble
    \input some-pic-macs
    \let\gO\Omega
    \def\I#1#2{\int_{#1}^#2}
  \endimgpreamble
\fi
\endtt
%
allows the use of the control sequences `\gO`,
`\I`, and those in `some-pic-macs.tex` in the
\TeX\ fragments destined for imagehood.

The commands inside `\imgpreamble` are visible only
to \TeX2page, so a form of them should also be
specified outside the `\imgpreamble` for use by \TeX\
when it processes the entire document for DVI.

Note that if you use encapsulated PostScript inserts,
it is not necessary (though it doesn’t hurt) to
specify an image preamble for loading the `epsf.tex`
macro file or `graphicx.sty` package.  \TeX2page will
automatically load them when processing the EPS files.
You still need to load these files outside the image
preamble for your document to be processable by \TeX\
though.

\beginsection Image magnification

\index{magnification@`\magnification`}
\index{image!magnification@`\magnification`}
%
In general, the magnification of the image
inserts, whether math or picture, may not match that
of the rest of the text in the HTML output.  The DVI
output has no such problem, because the math and
the picture-macros use the same magnification as the
surrounding text.  In the HTML output, however, the
regular text is rendered at the default magnification
of your browser, while the images have come via \TeX,
and the twain may not meet.  Typically, the image is
too small.

The solution is to adjust the magnification of  just
the image inserts.  In plain \TeX, this can be
done by a call to the `\magnification` command {\em
inside} the image preamble.  E.g.,

\begintt
\ifx\shipout\UnDeFiNeD
  \imgpreamble
    \magnification\magstep1
    ...
  \endimgpreamble
\fi
\endtt
%
The above will magnify the HTML math and pictures.
Note that it will {\em not} affect the magnification
of these same items in the DVI output.  Indeed,
you can specify an alternate `\magnification`
outside `\imgpreamble`, and that will affect
overall size of the entire DVI output, inclusive of
math and pictures, as advertised in {\em The \TeX book}
\cite{texbook}.

In sum: `\magnification`, when called {\em
outside} the `\imgpreamble`, magnifies the
entire DVI document.  When called {\em inside}
the `\imgpreamble`, it will magnify  just the
images in the HTML document.  These two uses
of `\magnification` will not interfere.

\LaTeX\ users can use the following%
\iffalse, but there
must be a better way\fi:

\begintt
\ifx\shipout\UnDeFiNeD
  \imgpreamble
    \let\LaTeXdocument\document
    \def\document{\LaTeXdocument\Large}
  \endimgpreamble
\fi
\endtt
This tacks a hook on to the `\document` command.
(This modified `\document` will only operate
on the image.)

\beginsection Reusing image files

\xrdef{imgreuse}
\index{image!reuse}
\index{def@`\def`}
\index{imgdef@`\imgdef`}
%
`\def`initions that use math (such as the following
one for `\um`) work as expected in the
HTML output.

\begintt
\def\um{$\mu$m}

The human eye can see electromagnetic wavelengths from 0.39 \um\
to 0.78 \um.
\endtt
%
produces

\quote
The human eye can see electromagnetic wavelengths from 0.39 \um\
to 0.78 \um.
\endquote

\index{imgdef@`\imgdef`}

\n This could\f{This is a cooked-up example. In actuality, \TeX2page
is pretty good at aggressively avoiding math images in the first
place. But you can imagine a more complicated `\imgdef` that
happens to be repeated throughout your document.} force every occurrence
of `\um` in the document to generate a brand new
image file.  To advise \TeX2page to {\em reuse}
the same image for these multiple occurrences, use
`\imgdef` for the HTML:

\begintt
\ifx\shipout\UnDeFiNeD % HTML only
  \imgdef\um{$\mu$m}
\else
  \def\um{$\mu$m}
\fi
\endtt

\beginsection Recycling image files

\index{image!recycling}
%
The conversion of \TeX\ fragments into images can
consume a lot of time.  \TeX2page will therefore
{\em recycle} existing image files from
a previous run, instead of generating them anew.
To {\em force} generation of new image files, delete
the old image files.

\beginchapter  10 Extending \TeX\ with Lisp

\xrdef{eval}
\index{eval@`\eval`}
\index{dirty tricks}
%
The command `\eval` allows you to use arbitrary
Lisp
expressions, as opposed to just \TeX\ macros, to
guide the course of the typesetter.

The text written
to standard output by the Lisp code is substituted
for the `\eval` statement.  E.g., consider the
following complete document, `root2.tex`:

\begintt
\input tex2page

The square root of 2 is
\eval{
\endtt
\begintts
(princ (sqrt 2))
\endtt
\begintt
}.

\bye
\endtt
Running \TeX2page on `root2.tex` produces
the following HTML output:

\quote
The square root of 2 is
\eval{
(if 'nil
    (display (sqrt 2))
    (princ (sqrt 2)))
}.
\endquote
In effect, \TeX2page processes the `\eval` call
using Lisp, producing some output in an auxiliary
\TeX\ file, which is then re-inserted into the document at the location of
the `\eval`.

A definition for `\eval` that \TeX\ can use
is provided in the macro file `eval4tex.tex`.
`tex2page.tex` will automatically load `eval4tex.tex` if it finds it in
`TEXINPUTS`.
Thus, running \TeX\ on
`root2.tex` produces a DVI file whose
content matches the HTML version.

% \f{Actually, getting `tex root2` to
% produce the required DVI output involves a couple of extra steps.  `tex root2`
% produces a Scheme file called `root2.eval4tex`, which must be evaluated
% in Scheme to produce the auxiliary \TeX\ file that is slurped back into the
% document.  However, this auxiliary file is identical to the one created by
% running \TeX2page on the same document.  \TeX2page, being written in Scheme,
% saves the user the trouble of having to call Scheme explicitly to create
% the aux \TeX\ files.}

It is clear that Lisp code via `\eval` can serve as
a very powerful {\em second extension language} for
\TeX, and that its benefits are available to both the
DVI and the HTML outputs.  As we have seen, \TeX2page
implements a subset of the \TeX\ macro language, and for
those cases where this macro language isn’t enough,
Lisp can be used to fill the breach.  More generally,
Lisp may be preferable to the \TeX\ macro language even
for just DVI, where no HTML version of the document is
contemplated.  We’ll explore both of these
aspects of `\eval`.

`\eval`’s argument is a balanced-brace
expression.  At the top-level, i.e., not within the body of a macro,
`\eval`’s argument is sent verbatim to Lisp, except that the pipe character
(‘\p+|+’) functions as the \TeX\ escape.  Use \p+||+ to represent a single
pipe in the Lisp code.  If you need to include an unmatched brace, simply
put a bogus matching brace inside a Lisp comment.

Inside a macro body, it is too late for `\eval` to set the catcodes
to make verbatim any character within its argument.  Either define or
use control sequences to represent special characters, or use
Lisp
workarounds (e.g., \q{code-char}) to construct those characters.

Let us first look at a simple example where
`\eval` lets you define an HTML version of an already
existing \TeX\ macro that is either impossible or at
least prohibitively difficult  to process using
\TeX2page’s  mimicry of \TeX.  Consider a hypothetical
`\proto` macro, used to introduce the description of
a Lisp operator by presenting a {\em prototypical}
use of it.
Typical calls to `\proto` are:

\begintt
\proto{cons}{a d}{procedure}
\proto{car}{c}{procedure}
\proto{cdr}{c}{procedure}
\endtt
%
which typeset as follows:

\quote
\proto{cons}{a d}{procedure}
\proto{car}{c}{procedure}
\proto{cdr}{c}{procedure}
\endquote
The macro `\proto` takes three arguments: the
operator name; the metavariables for its operands;
and the operator kind.  In particular, it typesets
the operator and the operands in different fonts,
surrounding the call in parens.  Note the
intervening space between operator and operands.

In the case where there are no operands, the intervening
space should not.  Thus,

\begintt
\proto{gentemp}{}{procedure}
\endtt
%
should not produce

\quote
\proto{gentemp}{\ }{procedure}
\endquote
but rather

\quote
\proto{gentemp}{}{procedure}
\endquote
(I.e., no space between `gentemp` and the
closing paren.)

\index{def@`\def`}

The `\proto` macro can be written
in \TeX\ as follows:

\begintt
\def\proto#1#2#3{\noindent
  \hbox{{\tt(#1}\spaceifnotempty{#2}{\it#2}{\tt)}%
    \qquad ;#3}\par}
\endtt
%
where `\spaceifnotempty` is a helper macro
that expands to a space only if its argument is
not empty.  \TeX2page can expand this definition
for `\proto`, provided it knows how to deal
with the `\spaceifnotempty`.

One way to write `\spaceifnotempty` in \TeX\
is:

\begintt
\newdimen\templen
\newbox\tempbox

\def\spaceifnotempty#1{%
  \setbox\tempbox\hbox{#1}%
  \templen\wd\tempbox
  \ifdim\templen>0pt{\ }\fi}
\endtt
%
This piece of box-measuring contortion is
too much for \TeX2page’s mimicry of the \TeX\ macro
system.  However, it’s easy enough to  achieve the
same effect using the string-processing capabilities
of Lisp:

\begintt
\ifx\shipout\UnDeFiNeD
\eval{
\endtt
\begintts
(defun all-blanks-p (s)
  (every (lambda (c) (or (char= c #\space) (char= c #\tab)
                          (not (graphic-char-p c))))
        s))
\endtt
\begintt
}

\def\spaceifnotempty{\eval{
\endtt
\begintts
(let ((x (ungroup (get-token))))
  (unless (all-blanks-p x)
    (princ (code-char 92))
    (princ "space")))
\endtt
\begintt
}}
\fi
\endtt
Note that we had to use \q{(code-char 92)} to refer to the
backslash character, as the `\eval` is inside a macro body and ‘`\`’
is not and cannot be made a letter.
(Otherwise we could have simply written \q{(princ "\\space")}.)

Later `\eval`s can
use definitions introduced in previous `\eval`s,
as with \q{all-blanks-p} in our example.

If being processed by \TeX2page only (as in our example),
the code inside `\eval` is allowed to use not just general Lisp
but also procedures like
\q{ungroup} and \q{get-token}, which are defined by
\TeX2page. (There is no need to package-qualify their names, as `\eval`
code is evaluated inside the `tex2page` package.)

\beginsection {eval} without regard to HTML

\xrdef{eval-for-just-tex}
%
The key thing to remember is that
an `\eval`-call is replaced by whatever text the
Lisp code in that `\eval`-call writes to its
standard output.  This approach will work whether the
document is being processed by \TeX2page to produce HTML
or by \TeX\ to produce DVI.

For those \TeX\ documents that are not intended for HTML conversion, but
nevertheless use `\eval`, this macro is available in the macro file
`eval4tex.tex`.  Run \TeX\ (or \LaTeX) on such a document, say
\p{|meta[jobname].tex}, and then evaluate
the resultant \p{|meta[jobname]-Z-E.lisp} in Lisp, to create the
necessary aux \TeX\ files.  Running \TeX\ on the master document a {\em second}
time will
insert these aux \TeX\ files at the location of the corresponding `\eval`
calls.  This is quite analogous to how \TeX2page would have processed the
`\eval`s, except that \TeX\ requires you to explicitly call Lisp to
create the aux files which it can use on its second run, whereas
\TeX2page, being written in Lisp, creates and loads the aux files
immediately.

For complete details on using `\eval` with
\TeX, please consult the companion manual,
{\em An `\eval` for
\TeX}~\cite{eval4tex}.

% There are however some concerns with the use of `\eval` as a
% mainstream \TeX\ command.  The way we have described it,
% `\eval` inserts text generated by the Scheme code
% of \TeX2page, so a document containing `\eval`
% must not only `\input tex2page.tex` but also be
% processable by \TeX2page.  This would be too stringent a
% requirement if `\eval` is to be usable in \TeX\
% documents that are not intended for HTML at all, and
% that may fail to be processable by \TeX2page for reasons
% unrelated to `\eval`.  Fortunately, this requirement
% isn’t necessary: Generic \TeX\ documents that cannot be
% converted by \TeX2page can still make use of the
% `\eval` feature.  For the use of `\eval` in its
% full generality, please see the companion manual,
% \urlh{eval4tex-doc.html}{\em An `\eval` for
% TeX}.

\beginchapter  11 Recovery from errors

\xrdef{recovery}
\index{error recovery}
\index{log file}
\index{recovery from errors}
\index{debugging}
%
If \TeX2page reports an error on your document, you may
be able to deduce the cause from the diagnostic
information that \TeX2page displays  on standard
output.  If you failed to look at this information as
it was being displayed, you can always retrieve it from
the {\em log file} \p{|meta[jobname].hlog}.  This is
exactly analogous to \TeX\ generating diagnostic
information on standard output and keeping a copy
thereof in the file \p{|meta[jobname].log}.

\index{errorcontextlines@`\errorcontextlines`}

The  error message typically displays an {\em error
context}, viz., a few consecutive lines from the source
document that contain the likely cause of the error.
The number of context lines so displayed is governed by
the count register `\errorcontextlines`, which has a default
value of 5.  Thus, setting `\errorcontextlines=7` will display
seven lines.  Note that error contexts are often
only approximate — be prepared to look a little above
or below the reported context.

\index{TEXEDIT@`TEXEDIT` (environment variable)}
\index{EDITOR@`EDITOR` (environment variable)}

Like \TeX, \TeX2page also gives you the option of immediately
editing the file containing the error,
{\em at} the location of the error.  It does so with the
following prompt:

\begintt
Type E to edit your file, X to quit.
?
\endtt
%
When you type `e` at this prompt, a text editor
is fired up.  What the editor is depends on the
environment variables `TEXEDIT` (which is also used
by \TeX) and `EDITOR`.

If `TEXEDIT` is set, its string value (e.g.,
“`vim +%d %s`”)
is chosen as
the entire editor call, with `%s` replaced by the offending
file’s name, and `%d` replaced by the number of the line
containing the error.
If `TEXEDIT` is not set, or if
it is mis-set, i.e., without `%s` or `%d`, then the
editor specified in the environment variable `EDITOR`
is chosen.  If `EDITOR` is also not set, then
the editor name is assumed to be `vi`.
When using `EDITOR` or `vi`, the file and line number are
tacked on as arguments to the editor,
with a `+` preceding the
line number.  This argument style works for all `vi`
and `emacs` clones.\f{\TeX\ itself uses just `TEXEDIT`.
In the scenarios I've tried, it does not appear to check `EDITOR` if
`TEXEDIT` is not set, going directly to a system default
editor, typically `vi` (or whatever `vi` is linked to).  But most Unix programs that
reach for an editor do tend to use `EDITOR`, and failing that,
`vi`, so \TeX2page does the same.}

\beginsection Tracing more information

\index{tracingcommands@`\tracingcommands`}
\index{tracingmacros@`\tracingmacros`}
%
Sometimes, the diagnostic information in an error
message may not be enough to track
down the error.
\TeX\ provides various commands for generating more diagnostics —
\TeX2page recognizes the same commands to provide its own diagnostics.
For instance,
setting the count registers
`\tracingcommands` and `\tracingmacros` to a positive integer causes
more log information.

(i) Setting  `\tracingcommands=1` tells \TeX2page to log all calls
to atomic commands.

(ii) Setting  `\tracingmacros=1` tells
\TeX2page to log all macro expansions.

You may turn on
these traces at any point in your document.  You may
subsequently turn them off by setting `\tracingcommands=0`
and `\tracingmacros=0` respectively.

\index{tracingall@`\tracingall`}

(iii) The command `\tracingall` turns {\em on} both
`\tracingcommands` and `\tracingmacros`.

\index{errmessage@`\errmessage`}

(iv) The command `\errmessage` can be used to generate
meaningful error messages.  \TeX2page, like \TeX, ceases
processing the document on encountering
`\errmessage`.

\index{message@`\message`}

(v) The command `\message`
can be used to print helpful information at selected
points in the document.   \LaTeX\ users may
prefer `\typeout`, which does the same thing.

All of these commands display their information
on both standard output and in the log file.
Judicious use of these commands
should help pinpoint any error.

\beginchapter A Also in Scheme

\xrdef{scheme}
The \TeX2page distribution comes with two scripts,
`tex2page.lisp` and `tex2page.rkt`. Each works without any
further configuration, the first in Common Lisp, the second in
Scheme, specifically Racket.
You should be able to run either script on any document, and for
the most part you will get identical results. We will now mention
the few situations where the Scheme script differs from the
Common Lisp version.

See Appendix C (p.~\ref{configure}) for details on how to obtain a script that works
on Schemes other than Racket.

When you get the script of your choice configured, you may copy or link it to
`tex2page` and put it in your `PATH`.

\beginsection Calling \TeX2page from Scheme

\index{running \TeX2page!from Scheme}
\index{tex2page (Scheme p)@\q{tex2page} (Scheme procedure)}
\index{tex2page (Scheme f)@`tex2page` (Scheme file)}
%
As with the CL version, you can load the Scheme script into your
Scheme and call the \q{tex2page} procedure. The difference is
that there is no package qualification to refer to the procedure
name, e.g.,

\begintts
(load "tex2page") ;use appropriate pathname

(tex2page |meta[filename])
\endtt

\beginsection  eval

`\eval` works for Scheme versions of \TeX2page too. The
difference of course is that the `\eval`-enclosed code must be in
Scheme rather than Common Lisp. (You can also use the
Scheme names (procedures and other, global values) added by the
script, and for the most part these names are identical across
Scheme and Common Lisp.)

E.g., the \q{all-blanks-p} procedure
defined in Chapter 10 would look like this in the Scheme
situation:

\begintts
(define all-blanks?
  (lambda (s)
    (let loop ((L (string->list s)))
      (if (null? L) #t
          (let ((c (car L)))
            (if (char-whitespace? c) (loop (cdr L))
                #f))))))
\endtt

It is of course possible to keep your TeX document
language-proof by using a conditional on the flag
`\TZPcommonlisp`. This is set to 1 in Common Lisp and 0 in Scheme:
Use `\ifx` to create two branches, e.g.,

\begintt
\ifx\TZPcommonlisp 1
\eval{
  ... |meta[Common Lisp code] ...
}\else
\eval{
  ... |meta[Scheme version of the same code] ...
}\fi
\endtt
That is what this manual did to keep it processable in both versions
of \TeX2page.

\beginchapter  B Bibliography

%\ifx\shipout\UnDeFiNeD\else\vskip-\lastskip\fi

\bibliographystyle{plain}
\bibliography{tex2page}

\beginchapter  C Configuring \TeX2page

\xrdef{download}
\index{installing \TeX2page}
%
\TeX2page is available on
\urlp{GitHub}{https://github.com/ds26gte/tex2page}.

\begintt
git clone https://github.com/ds26gte/tex2page
\endtt
%
produces a directory
called `tex2page`, which contains, among other files:
the Racket file `tex2page.rkt`, the Common Lisp file `tex2page.lisp`, the plain \TeX\ file
`tex2page.tex`, and the \LaTeX\ package
`tex2page.sty`.

Put copies of (or links to) the files
`tex2page.tex` and `tex2page.sty`  in a directory
that is mentioned in your `TEXINPUTS` environment
variable.

\beginsection \TeX2page out of the box (Common Lisp)

If you run a Common Lisp on a Unix, you can use the supplied script
`tex2page.lisp` after setting the environment variable `LISP` to the
name of your Lisp implementation.  Put `tex2page.lisp` in your
`PATH`. You may rename it to
`tex2page`.

Set `LISP` to
`abcl` for ABCL~\cite{abcl},
`allegro` for Allegro~\cite{allegro},
`clasp` for Clasp~\cite{clasp},
`clisp` for CLISP~\cite{clisp},
`clozure` for Clozure~\cite{clozure},
`cmucl` for CMUCL~\cite{cmucl},
`ecl` for ECL~\cite{ecl},
`mkcl` for MKCL~\cite{mkcl},
and `sbcl` for SBCL~\cite{sbcl}.

The top few lines in `tex2page.lisp` contain the lines
that invoke Lisp —  if they don’t already address your
particular Lisp
implementation, you may need to add a line based on your
Lisp’s command line options.

\beginsection \TeX2page out of the box (Racket)

\index{Racket}
%
If you run Racket~\cite{racket} on a Unix (including Mac OS X and
Cygwin~\cite{cygwin}), setup is minimal.  Simply put a copy of (or link to) the Scheme
file `tex2page.rkt` in a directory in your `PATH` environment
variable. You may rename it to `tex2page`.

If you run Racket on Windows,
copy the supplied batchfile `tex2page.bat`
to your `PATH`, and edit its contents so it contains
the correct pathnames to your Racket executable and
`tex2page.rkt` file.

%Note also that the Racket distribution (as also its
%superset DrScheme) already bundle a
%pre-configured `tex2page` script.

\beginsection When explicit configuration is needed

\xrdef{configure}
In general, you need to {\em
configure}
\TeX2page so it runs on your system.  Even in cases where the supplied
script runs “out of the box” for your setup, it may still be a good
idea to do an explicit configuration.

%fmrly subsub
%\subsection{Using \p{./configure --dialect=|meta[D]}}
\beginsection Using {./configure}

This method may not always work but is so easy that
it’s worth a try.  It should work for most
dialects on Unix.

(i) Type `./configure --help` at your OS command line
to get the list of dialects supported.
If your dialect \p{|meta[D]} is one of them,

(ii) Type  \p{./configure --dialect=|meta[D]}

\n If all goes well, this will create
`tex2page`, a version of \TeX2page that’s suited to \p{|meta[D]}.
Put it in your `PATH`.

\TeX2page is known to configure for the Scheme dialects
Chez~\cite{chez},
Chicken~\cite{chicken},
Gambit~\cite{gambit},
Gauche~\cite{gauche},
Guile~\cite{guile},
and Racket~\cite{racket}; and the Common Lisp
implementations ABCL, Allegro, Clasp, CLISP, Clozure, CMUCL, ECL, and SBCL.
\iffalse how about bigloo mitscheme pocketscheme s48 scm scsh
stklos sxm \fi

%fmrly subsub
\beginsection  Using Scmxlate directly

\index{Scmxlate}
The \p{./configure --dialect=|meta[D]} approach above
essentially takes care to call Scmxlate (if needed) as described in
this section, but unfortunately it may not work for
some dialects or operating systems.  In such cases, you
can manually call Scmxlate, which isn’t really all that
tedious.

First ensure that
\urlp{Scmxlate}{https://github.com/ds26gte/scmxlate}
is installed on your system.  Note down the pathname of
the file `scmxlate.scm` in the unpacked `scmxlate`
directory.

Optionally, edit the file `scmxlate-tex2page.rkt` in the
`tex2page` directory. (Leaving it as is is just fine.)
Possible insertions are:

\begintts
(scmxlate-compile #t)

(define *ghostscript* "pathname-of-your-ghostscript-program")
\endtt
%
The first produces a compiled version of
\TeX2page.   The second lets you supply the
correct pathname for the Ghostscript executable.
(\TeX2page will guess the Ghostscript pathname,
but there is a possibility it guesses wrong on
Windows.)

Start your Scheme (or Common Lisp) in the
`tex2page` directory.   Load the file
`scmxlate.scm` from the
`scmxlate` distribution, using the correct relative
or full pathname of `scmxlate.scm`.  For example,

\begintts
(load "/home/dorai/share/scmxlate/scmxlate.scm")
\endtt
%
(assuming you unpacked Scmxlate in
`/home/dorai/share`).  You will be asked a couple
of questions about your setup.  A choice of answers
will be provided, so you don’t need to be too creative.
When Scmxlate finishes, you will be left with a
`tex2page` that is tailormade for your system.

On Windows, a batch file called `tex2page.bat`
is also created.  Move it to a directory in your
`PATH`.  Edit the contents of `tex2page.bat` so
that the pathnames it refers to are correct.

\iffalse
\beginsection Can’t create or don’t want a {tex2page
script?}

If the configuration process cannot create an
appropriate script file for you to put in your
`PATH`, or if you prefer working within Scheme
anyway instead of at the OS command-line,
you can still use \TeX2page.  Simply load
your `tex2page` Scheme file
(whether the given script or your configured version)
directly into
your Scheme, and then call the Scheme
procedure \q{tex2page} on your source document.  E.g.,

\begintts
(load "tex2page")
(tex2page "filename.tex")
\endtt
Once loaded, the procedure \q{tex2page} can be called several times from
the same Scheme session, on the same file (to resolve cross-references)
or on different files.

If using the Common Lisp of \TeX2page, the \q{load}ing process is the same, but note that
the Common Lisp version of \TeX2page encloses all \TeX2page-related code
inside a Lisp package named \q{tex2page}.  Thus, you should call the
function \q{tex2page} by its package-qualified name, \q{tex2page:tex2page}:

\begintts
(tex2page:tex2page "tex2page-doc")
\endtt

%\section{Editor-friendly hypertext}
%\label{hisfir}
%
%\input hisfir
\fi

\beginchapter D Details for the curious

\xrdef{auxfile}
\index{auxiliary files}
%
Running \TeX2page creates in your working directory  a bunch of files
with the infix `-Z-`.
Here’s the whole story on what they are for:

Given an input \TeX\ document whose main file is
`jobname.tex`, the
command

\begintt
tex2page jobname
\endtt
%
typically produces at least one
output HTML file `jobname.html`, and possibly some
additional HTML files, which are named
`jobname-Z-H-1.html`, `jobname-Z-H-2.html`, and
so on.  Additional HTML files are created whenever the
input document has commands requesting page
breaks in the HTML output.

This is about all you need to know.  However, \TeX2page
does manipulate many other little auxiliary files in order to
communicate information both to external programs and
across successive runs of itself.  The following
briefly describes the functions of these auxiliary
files, should you ever need to look at them more
closely, either out of curiosity or for debugging your
document.

\TeX2page displays on standard output the log of
its progress with `jobname.tex`.  A copy of this
log is kept in the log
file `jobname.hlog`.

\TeX2page generates a style sheet in
`jobname-Z-S.css`.  This contains some default style
information that \TeX2page generates for every document,
plus any style info supplied by the user via
`\cssblock` statements in the document.

\index{BibTeX@\BibTeX}

If `jobname.tex` uses the external program \BibTeX\ for
its bibliography, \TeX2page sends information to \BibTeX\
in the file `jobname-Z-B.aux` and receives information
from \BibTeX\ in the file `jobname-Z-B.bbl`.

\index{MakeIndex}

If `jobname.tex` contains `\index` commands, \TeX2page
will dump the unsorted index into `jobname-Z-I.idx` and
get from MakeIndex the sorted index `jobname-Z-I.ind`.

\TeX2page uses the auxiliary files `jobname-Z-L.lisp` and
`jobname-Z-A.lisp` to keep track of labels and other
internal cross-references.  Each run of \TeX2page loads
the `jobname-Z-L.lisp` and `jobname-Z-A.lisp`
created by the previous run.  If `jobname.tex` contains
{\em forward} cross-references, \TeX2page must be rerun
at least once.

For the image portions of `jobname.tex`, \TeX2page creates the auxiliary \TeX\
files `jobname-Z-G-1.tex`, etc, and uses external programs (as described on
p.~\ref{imageconv}) to convert them to the corresponding image files
`jobname-Z-G-1.png`, etc.  (This assumes you are using the default PNG format for
images.  If you had requested the GIF or JPEG format for images, the
extensions of these aux files would be correspondingly different.)

The above are “single-use” images.
`jobname.tex` may reuse some image files within itself.
Such image files have slightly different names and are
numbered separately: `jobname-Z-G-D-1.png`, etc.

\index{eval@`\eval`}

Occurrences of `\eval` in `jobname.tex` don’t create auxiliary
files when processed by \TeX2page. However, if the document is
processed by \TeX, they’re accumulated in an auxiliary Lisp file
called `jobname-Z-E.lisp`. This file is loadable in either Common
Lisp or Scheme, thanks to another aux file called
`jobname-Z-E-D.lisp`. When loaded in Lisp, `jobname-Z-E.lisp`
will create a series of aux \TeX\ files `jobname-Z-E-1.tex`,
etc., which are inserted back into `jobmame.tex` on a
subsequent run of \TeX.
% (As a convenience, running \TeX2page on
% `jobname.tex` will also process any `jobname-Z-E.lisp` if it
% exists, although the `jobname-Z-E-*.tex` aren’t needed by
% \TeX2page itself.)

\index{hdir file@`.hdir` file}

By default, all these files are created in the working
directory.  To avoid cluttering up
your working directory, you can specify a different target directory
using one of the following three files:

(i) \p{|meta[jobname].hdir} in the working directory, i.e.,
a file with the same basename as the input document but with
extension `.hdir`.  For `jobname.tex`, this would
be `jobname.hdir`.

(ii) `.tex2page.hdir` in the working directory.

(iii) `.tex2page.hdir` in the user’s `HOME` directory.

\n The first line of the first of these files that exists
is taken to be the name of the target directory.  If none of
these files exist, the current working directory is the target
directory.

The `.hdir` file may contain the \TeX\ control
sequence `\jobname`, which expands to the basename of
the input \TeX\ document.

\beginchapter  E Extremely tiny index

\xrdef{Index}

\beginmulticols2

\inputindex

\endmulticols

%\beginchapter U Undocumented features

\bye