11  Recovery from errors

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 log file jobname.hlog. This is exactly analogous to TeX​ ​generating diagnostic information on standard output and keeping a copy thereof in the file jobname.log.

The error message typically displays an 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.

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

Type E to edit your file, X to quit.
?

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

Tracing more information

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.

(iii) The command \tracingall turns on both \tracingcommands and \tracingmacros.

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

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