TeX2page is invoked in much the same way as plain TeX
or LaTeX.1 Recall how
these programs are called: Given a TeX source file
with the relative or full pathname
wherever-it-is/jobname.ext
, where
jobname
is the basename of the file
and .ext
is its extension, you type either
tex wherever-it-is/jobname.ext
or
latex wherever-it-is/jobname.ext
at the operating-system command line. You do not need
to mention the extension .ext
if it is .tex
.
This creates the output DVI file, jobname.dvi
,
in the working directory.
TeX2page is called analogously. To create the HTML
version of the same file
wherever-it-is/jobname.ext
, type
tex2page wherever-it-is/jobname.ext
Again, the .ext
is optional if it is .tex
. This
creates jobname.html
in the working directory.
To try this out, copy into your working directory the
example file story.tex
provided in all TeX
distributions.
Call TeX2page on it:
tex2page story
TeX2page will get cracking on story.tex
, providing
the following commentary, or log, on your console:
This is TeX2page, Version 2003-06-05 (MzScheme 204, unix) (story.tex) ! Missing \end inserted. [0] Output written on story.html (1 page).
TeX2page is now done, and the result of its labors
is the HTML file
story.html
(click
to see).
The 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
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 jobname.html
(especially
for larger documents). The auxiliary HTML pages
are reachable from jobname.html
by navigation links (section 3.1). 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
to get story.dvi
from story.tex
, with the log going into
story.log
.
This is TeX, Version 3.14159 (Web2C 7.3.1) (format=tex 2003.4.26) 17 MAY 2003 16:41 **story (story.tex [1]) *\bye Output written on story.dvi (1 page, 668 bytes).
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.2 Note that the bracketed numbers now refer
to physical pages.
Thus, from one TeX source file, you can get both a
printable .dvi
and a browsable .html
document,
using the same calling
conventions.3
When TeX encounters a filename 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 f.tex
is tried before
f
itself is tried. In most modern TeXs, the
search is performed using the kpathsea
library.
By default, TeX2page will look for files using the same kpathsea
mechanism as TeX. However, it is possible to supply a
different list of search directories via the environment
variable TIIPINPUTS
.
It may be useful to have
files in TIIPINPUTS
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 kpathsea
library,
TIIPINPUTS
is the only way to get TeX2page to
automatically access files outside the working
directory. Note that TIIPINPUTS
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 section 10.
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
(eg, --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
.
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 Scheme
and call the
procedure tex2page
with the name of the TeX file
as argument:
(load "tex2page") ;use appropriate pathname (tex2page filename)
You can call the procedure
tex2page
several times from the same Scheme
session, on the same file or on different files.
By default, TeX2page generates the output HTML files and other auxiliary files (section A) 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 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.
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).
1 Hereafter, we will use TeX to mean any format of TeX, and plain TeX when we specifically mean the ``plain'' format.
2 The file story.tex
lacks an \end
only to demonstrate some interactive
capabilities of TeX, which are not relevant for
TeX2page.
3 Quite a few documents profit from being available additionally in a tagged plain-text format that is accessible directly via text editors, instead of requiring an HTML browser. The TeX2page distribution includes Vim scripts that generate Info and Vim helpfile versions of the HTML files created with TeX2page.