<!--
__COPYRIGHT__

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->
<tool name="dvi">
<summary>
Attaches the &b-DVI; builder to the
construction environment.
</summary>
<sets>
</sets>
<uses>
</uses>
</tool>

<builder name="DVI">
<summary>
Builds a <filename>.dvi</filename> file
from a <filename>.tex</filename>,
<filename>.ltx</filename> or <filename>.latex</filename> input file.
If the source file suffix is <filename>.tex</filename>,
&scons;
will examine the contents of the file;
if the string
<literal>\documentclass</literal>
or
<literal>\documentstyle</literal>
is found, the file is assumed to be a LaTeX file and
the target is built by invoking the &cv-link-LATEXCOM; command line;
otherwise, the &cv-link-TEXCOM; command line is used.
If the file is a LaTeX file,
the
&b-DVI;
builder method will also examine the contents
of the
<filename>.aux</filename>
file and invoke the &cv-link-BIBTEX; command line
if the string
<literal>bibdata</literal>
is found,
start &cv-link-MAKEINDEX; to generate an index if a
<filename>.ind</filename>
file is found
and will examine the contents
<filename>.log</filename>
file and re-run the &cv-link-LATEXCOM; command
if the log file says it is necessary.

The suffix <filename>.dvi</filename>
(hard-coded within TeX itself)
is automatically added to the target
if it is not already present.
Examples:

<example>
# builds from aaa.tex
env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
# builds bbb.dvi
env.DVI(target = 'bbb', source = 'bbb.ltx')
# builds from ccc.latex
env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
</example>
</summary>
</builder>