18.2 Format with texi2dvi or texi2pdf ¶

The texi2dvi program takes care of all the steps for producing a TeX DVI file from a Texinfo document. Similarly, texi2pdf produces a PDF file⁹.

To run texi2dvi or texi2pdf on an input file foo.texi, do this (where ‘prompt$ ’ is your shell prompt):

prompt$ texi2dvi foo.texi
prompt$ texi2pdf foo.texi

As shown in this example, the file names given to texi2dvi and texi2pdf must include any extension, such as ‘.texi’.

For a list of all the options, run ‘texi2dvi --help’. Some of the options are discussed below.

With the --pdf option, texi2dvi produces PDF output instead of DVI, by running pdftex instead of tex. Alternatively, the command texi2pdf is an abbreviation for running ‘texi2dvi --pdf’. The command pdftexi2dvi is also provided as a convenience for AUC-TeX (see AUC-TeX), as it prefers to merely prepend ‘pdf’ to DVI producing tools to have PDF producing tools.

With the --dvipdf option, texi2dvi produces PDF output by running TeX and then a DVI-to-PDF program: if the DVIPDF environment variable is set, that value is used, else the first program extant among dvipdfmx, dvipdfm, dvipdf, dvi2pdf, dvitopdf. This method generally supports CJK typesetting better than pdftex.

With the --ps option, texi2dvi produces PostScript instead of DVI, by running tex and then dvips (see Dvips). (Or the value of the DVIPS environment variable, if set.)

texi2dvi can also be used to process LaTeX files. Normally texi2dvi is able to guess the input file language by its contents and file name extension; however, if it guesses wrong you can explicitly specify the input language using --language=lang command line option, where lang is either ‘latex’ or ‘texinfo’.

One useful option to texi2dvi is ‘--command=cmd’. This inserts cmd on a line by itself at the start of the file in a temporary copy of the input file, before running TeX. With this, you can specify different printing formats, such as @smallbook (see @smallbook: Printing “Small” Books), @afourpaper (see Printing on A4 Paper), or @pagesizes (see @pagesizes [width][, height]: Custom Page Sizes), without actually changing the document source. (You can also do this on a site-wide basis with texinfo.cnf; see Preparing for TeX).

The option -E (equivalently, -e and --expand) does Texinfo macro expansion using texi2any instead of the TeX implementation (see Macro Details and Caveats). Each implementation has its own limitations and advantages.

texi2dvi takes the --build=mode option to specify where the TeX compilation takes place, and, as a consequence, how auxiliary files are treated. The build mode can also be set using the environment variable TEXI2DVI_BUILD_MODE. The valid values for mode are:

‘local’

Compile in the current directory, leaving all the auxiliary files around. This is the traditional TeX use.

‘tidy’

Compile in a local *.t2d directory, where the auxiliary files are left. Output files are copied back to the original file.

Using the ‘tidy’ mode brings several advantages:

• the current directory is not cluttered with plethora of temporary files.
• clutter can be even further reduced using --build-dir=dir: all the *.t2d directories are stored there.
• clutter can be reduced to zero using, e.g., --build-dir=/tmp/\$USER.t2d or --build-dir=\$HOME/.t2d.
• the output file is updated after every successful TeX run, for sake of concurrent visualization of the output. In a ‘local’ build the viewer stops during the whole TeX run.
• if the compilation fails, the previous state of the output file is preserved.
• PDF and DVI compilation are kept in separate subdirectories preventing any possibility of auxiliary file incompatibility.

On the other hand, because ‘tidy’ compilation takes place in another directory, occasionally TeX won’t be able to find some files (e.g., when using \graphicspath): in that case, use -I to specify the additional directories to consider.

‘clean’

Same as ‘tidy’, but remove the auxiliary directory afterwards. Every compilation therefore requires the full cycle.

texi2dvi will use etex if it is available, because it runs faster in some cases, and provides additional tracing information when debugging texinfo.tex. Nevertheless, this extended version of TeX is not required, and the DVI output is identical.

texi2dvi attempts to detect auxiliary files output by TeX, either by using the -recorder option, or by scanning for ‘\openout’ in the log file that a run of TeX produces. You may control how texi2dvi does this with the TEXI2DVI_USE_RECORDER environment variable. Valid values are:

‘yes’

use the -recorder option, no checks.

‘no’

scan for ‘\openout’ in the log file, no checks.

‘yesmaybe’

check whether -recorder option is supported, and if yes use it, otherwise check for tracing ‘\openout’ in the log file is supported, and if yes use it, else it is an error.

‘nomaybe’

same as ‘yesmaybe’, except that the ‘\openout’ trace in log file is checked first.

The default is ‘nomaybe’. This environment variable is provided for troubleshooting purposes, and may change or disappear in the future.