SCons/Tool/dvi.xml

   1 <?xml version="1.0"?>
   2 <!--
   3 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   4 SPDX-License-Identifier: MIT
   5 SPDX-FileType: DOCUMENTATION
   6
   7 This file is processed by the bin/SConsDoc.py module.
   8 -->
   9
  10 <!DOCTYPE sconsdoc [
  11 <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
  12 %scons;
  13 <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
  14 %builders-mod;
  15 <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
  16 %functions-mod;
  17 <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
  18 %tools-mod;
  19 <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
  20 %variables-mod;
  21 ]>
  22
  23 <sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
  24           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  25           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  26
  27 <tool name="dvi">
  28 <summary>
  29 <para>
  30 Attaches the &b-link-DVI; builder to the
  31 construction environment.
  32 </para>
  33 </summary>
  34 <sets>
  35 </sets>
  36 <uses>
  37 </uses>
  38 </tool>
  39
  40 <builder name="DVI">
  41 <summary>
  42 <para>
  43 Builds a <filename>.dvi</filename> file
  44 from a <filename>.tex</filename>,
  45 <filename>.ltx</filename> or <filename>.latex</filename> input file.
  46 If the source file suffix is <filename>.tex</filename>,
  47 &scons;
  48 will examine the contents of the file;
  49 if the string
  50 <literal>\documentclass</literal>
  51 or
  52 <literal>\documentstyle</literal>
  53 is found, the file is assumed to be a LaTeX file and
  54 the target is built by invoking the &cv-link-LATEXCOM; command line;
  55 otherwise, the &cv-link-TEXCOM; command line is used.
  56 If the file is a LaTeX file,
  57 the
  58 &b-DVI;
  59 builder method will also examine the contents
  60 of the
  61 <filename>.aux</filename>
  62 file and invoke the &cv-link-BIBTEX; command line
  63 if the string
  64 <literal>bibdata</literal>
  65 is found,
  66 start &cv-link-MAKEINDEX; to generate an index if a
  67 <filename>.ind</filename>
  68 file is found
  69 and will examine the contents
  70 <filename>.log</filename>
  71 file and re-run the &cv-link-LATEXCOM; command
  72 if the log file says it is necessary.
  73 </para>
  74
  75 <para>
  76 The suffix <filename>.dvi</filename>
  77 (hard-coded within TeX itself)
  78 is automatically added to the target
  79 if it is not already present.
  80 Examples:
  81 </para>
  82
  83 <example_commands>
  84 # builds from aaa.tex
  85 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
  86 # builds bbb.dvi
  87 env.DVI(target = 'bbb', source = 'bbb.ltx')
  88 # builds from ccc.latex
  89 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
  90 </example_commands>
  91 </summary>
  92 </builder>
  93
  94
  95 </sconsdoc>