TeX2page is invoked in much the same way as TeX.1
For instance, given a plain-TeX document file
wherever-it-is/jobname.ext, which can
be either a full pathname or a pathname relative to either the
working directory or some directory in
jobname is the basename of the file
.ext is its extension, you type
tex wherever-it-is/jobname. ext
TeX2page is called analogously. To create the HTML
version of the same file
tex2page wherever-it-is/jobname. ext
.ext is optional if it is
jobname.html in the working directory.
To try this out, call TeX2page on the example file
provided in all TeX distributions:
TeX2page will get cracking4 on
the following commentary, or log, on your console:
This is TeX2page, Version 20170129 (ECL 16.1.3 Linux) Sun, Jan 29, 2017, 2:11 am UTC−5 (/usr/share/texlive/texmf-dist/tex/plain/knuth-lib/story.tex) ! Missing \end inserted.  Output written on story.html (1 page).
TeX2page is now done, and the result of its labors
is the HTML file
The log file
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
and that TeX2page assumed one anyway. Also, only
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
for larger documents). The auxiliary HTML pages
are reachable from
by navigation links (p. 4). As each
auxiliary HTML page is completed, the log will show the
, etc. The
in this log refers to the only HTML file created, viz.,
All this is of course almost exactly analogous to the
way you type
tex story (or
xetex story or
pdftex story) to get
story.tex, with the log going into
This is XeTeX, Version 3.14159265-2.6-0.99996 (TeX Live 2016/Debian) (preloaded format=xetex 2016.11.16) 16 NOV 2016 20:15 entering extended mode restricted \write18 enabled. %&-line parsing enabled. **story (/usr/share/texlive/texmf-dist/tex/plain/knuth-lib/story.tex ) *\end Output written on story.pdf (1 page).
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.5 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
.html document, using the same calling
When TeX encounters a filename
searches for it
in a standard list of
directories, which can be modified by the user via the
f.tex is tried before
f itself is tried. In most modern TeXs, the
search is performed using the
By default, TeX2page will look for files using the same
mechanism as TeX. However, it is possible to supply a
different list of search directories via the environment
It may be useful to have
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 TeXs without the
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.,
//) that is
typically permitted for
Error recovery in TeX2page is also exactly analogous to TeX, but we will postpone that discussion to p. 11.
Like most recent versions of TeX, TeX2page also
supports the standard self-identification
arguments elicit help only if there isn’t an input file
‑‑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
If, for any reason, it is not possible to call
from your operating-system command line, you may load the
tex2page into your Lisp
and call the
tex2page:tex2page with the name of the TeX file
(load "tex2page") ;use appropriate pathname (tex2page:tex2page filename)
You can call the procedure
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
whose one exported symbol is
tex2page. (But see Appendix A if
using the Scheme version of TeX2page.)
By default, TeX2page generates the output HTML files and other auxiliary files (p. 15) 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:
jobname.hdir in the working directory,
.tex2page.hdir in the working directory, and
.tex2page.hdir in the user’s
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
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
\jobname” (without quotes).
1 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. 12).
2 The executable
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
pdfTeX, XǝTeX , and luaTeX  have
luatex for the plain
lualatex for LaTeX.
3 The modern TeXs pdfTeX, XǝTeX, and luaTeX  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.
4 TeX2page, like TeX, will find the
story.tex from your distribution as it is in your default
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
5 The file
\end only to demonstrate some interactive
capabilities of TeX, which are not relevant for