1  Running TeX2page

TeX2page is invoked in much the same way as plain TeX or LaTeX.* For instance, given a plain-TeX document 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

tex 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 20130325 (Racket 5.3.6, :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 (p. 4). 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 pdftex story) to get story.dvi (or story.pdf) from story.tex, with the log going into story.log.

This is pdfTeX, Version 3.1415926-2.4-1.40.13 (TeX Live 2012) (format=pdftex 2013.1.29)  2 FEB 2013 12:03
entering extended mode
 restricted \write18 enabled.
 %&-line parsing enabled.
**story
(./story.tex [1{/usr/local/texlive/2012/texmf-var/fonts/map/pdftex/updmap/pdfte
x.map}])
*\bye
</usr/local/texlive/2012/texmf-dist/fonts/type1/public/amsfonts/cm/cmbx10.pfb><
/usr/local/texlive/2012/texmf-dist/fonts/type1/public/amsfonts/cm/cmr10.pfb></u
sr/local/texlive/2012/texmf-dist/fonts/type1/public/amsfonts/cm/cmsl10.pfb>
Output written on story.pdf (1 page, 36185 bytes).
PDF statistics:
 20 PDF objects out of 1000 (max. 8388607)
 13 compressed objects within 1 object stream
 0 named destinations out of 1000 (max. 500000)
 1 words of extra memory for PDF output out of 10000 (max. 10000000)

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

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 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 TeXs 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. 11.

Non-file arguments

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.

Calling TeX2page from Scheme or Common Lisp

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.

If using the Common Lisp version of TeX2page, the same method applies, but note that the Common Lisp TeX2page is provided as a Lisp package texp2age whose one exported symbol is tex2page. Thus, the function to call has the qualified name tex2page:tex2page.

(tex2page:tex2page filename)

Specifying a target directory

By default, TeX2page generates the output HTML files and other auxiliary files (p. 12) 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).


* Hereafter, we will use TeX to mean any format of TeX, and plain TeX when we specifically mean the ‘‘plain’’ format.

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 pdfTeX, XƎTeX [41], and luaTeX [27] 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.

§ The file story.tex lacks an \end only to demonstrate some interactive capabilities of TeX, which are not relevant for TeX2page.