### 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 file8.

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. If this option is used, no line in the source file may begin with the string `@c _texi2dvi` or the string `@c (_texi2dvi)`.

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

#### Footnotes

##### (8)

PDF stands for ‘Portable Document Format’. It was invented by Adobe Systems for document interchange, based on their PostScript language.