<?xml version='1.0' encoding='ISO-8859-1'?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
          "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
 <!ENTITY % tex-refs-ent SYSTEM "tex-refs.ent" >
%tex-refs-ent;
]>

<!-- $Id: tex-refs-chapter-pdftex.xml 139 2004-08-26 16:58:10Z mw $ -->

<chapter id="pdftex" lang="en">
  <title id="pdftex-title">&pdftex;</title>
  <indexterm><primary>pdfTeX</primary></indexterm>

  <note>
    <para>The contents of this section was taken from 
      <filename>pdftex(1)</filename>.
    </para>
  </note>

  <section id="pdftex-options">
    <title id="pdftex-options-title">Options</title>
    <indexterm>
      <primary>pdfTeX</primary>
      <secondary>Options</secondary>
    </indexterm>

    <para>&pdftex; understands the following command line options.</para>

    <section id="pdftex-option-file-line-error-style">
      <title><filename role="nohyphenation">--file-line-error-style</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--file-line-error-style</tertiary>
      </indexterm>
      <para>Print error messages in the form
	<literal>file:line:error</literal>
	which is similar to the way many compilers format them.
      </para>
    </section>

    <section id="pdftex-option-fmt">
      <title><filename role="nohyphenation">--fmt format</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--fmt format</tertiary>
      </indexterm>
      <para>Use <literal>format</literal> as the name of the format 
	to be used, instead of the name by which &pdftex; was called 
	or a <literal>%&amp;</literal> line.
      </para>
    </section>

    <section id="pdftex-option-help">
      <title><filename role="nohyphenation">--help</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--help</tertiary>
      </indexterm>
      <para>Print help message and exit.</para>
    </section>

    <section id="pdftex-option-ini">
      <title><filename role="nohyphenation">--ini</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--ini</tertiary>
      </indexterm>
      <para>Be <command>pdfinitex</command>, for dumping formats; this 
	is implicitly true if the program is called as 
	<command>pdfinitex</command>.
      </para>
    </section>

    <section id="pdftex-option-interaction mode">
      <title><filename role="nohyphenation">--interaction mode</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--interaction mode</tertiary>
      </indexterm>
      <para>Sets the interaction mode. The mode can be one of
	<literal>batchmode</literal>, <literal>nonstopmode</literal>,
	<literal>scrollmode</literal>, and
	<literal>errorstopmode</literal>.
	The meaning of these modes is the same as that of the
	corresponding <literal>\commands</literal>.
      </para>
    </section>

    <section id="pdftex-option-ipc">
      <title><filename role="nohyphenation">--ipc</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--ipc</tertiary>
      </indexterm>
      <para>Send DVI or PDF output to a socket as well as the usual output
	file.  Whether this option is available is the choice of the
	installer.
      </para>
    </section>

    <section id="pdftex-option-ipc-start">
      <title><filename role="nohyphenation">--ipc-start</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--ipc-start</tertiary>
      </indexterm>
      <para>As <literal>--ipc</literal>, and starts the server at the
	other end as well. Whether this option is available is the
	choice of the installer.
      </para>
    </section>

    <section id="pdftex-option-jobname-name">
      <title><filename role="nohyphenation">--jobname name</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--jobname name</tertiary>
      </indexterm>
      <para>Use <literal>name</literal> for the job name, instead of
	deriving it from the name of the input file.
      </para>
    </section>

    <section id="pdftex-option-kpathsea-debug">
      <title><filename role="nohyphenation">--kpathsea-debug bitmask</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--kpathsea-debug bitmask</tertiary>
      </indexterm>
      <para>Sets path searching debugging flags according to the 
	<literal>bitmask</literal>. See the Kpathsea manual for details.
      </para>
    </section>

    <section id="pdftex-option-maketex">
      <title><filename role="nohyphenation">--maketex fmt</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--maketex fmt</tertiary>
      </indexterm>
      <para>Enable <command>mktexfmt</command>, where
	<literal>fmt</literal> 
	must be one of <literal>tex</literal> or <literal>tfm</literal>.
      </para>
    </section>

    <section id="pdftex-option-no-maketex">
      <title><filename role="nohyphenation">--no-maketex fmt</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--no-maketex fmt</tertiary>
      </indexterm>
      <para>Disable <command>mktexfmt</command>, where 
	<literal>fmt</literal> must be one of <literal>tex</literal>
	or <literal>tfm</literal>.
      </para>
    </section>

    <section id="pdftex-option-output-comment">
      <title><filename role="nohyphenation">--output-comment string</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--output-comment string</tertiary>
      </indexterm>
      <para>Use <literal>string</literal> for the DVI file comment
	instead of the date.
      </para>
    </section>

    <section id="pdftex-option-parse-first-line">
      <title><filename role="nohyphenation">--parse-first-line</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--parse-first-line</tertiary>
      </indexterm>
      <para>If the first line of the main input file begins with 
	<literal>%&amp;</literal> parse it
	to look for a dump name or a <literal>--translate-file</literal> option.
      </para>
    </section>

    <section id="pdftex-option-progname">
      <title><filename role="nohyphenation">--progname name</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--progname name</tertiary>
      </indexterm>
      <para>Pretend to be program <literal>name</literal>. This 
	affects both the format used and the search paths.
      </para>
    </section>

    <section id="pdftex-option-recorder">
      <title><filename role="nohyphenation">--recorder</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--recorder</tertiary>
      </indexterm>
      <para>Enable the filename recorder. This leaves a trace of the files
	opened for input and output in a file with extension 
	<literal>.fls</literal>.
      </para>
    </section>

    <section id="pdftex-option-shell-escape">
      <title><filename role="nohyphenation">--shell-escape</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--shell-escape</tertiary>
      </indexterm>
      <para>Enable the <literal>\write18{command}</literal> construct.
	The command can be any Bourne shell command. This construct
	is normally disallowed for security reasons.
      </para>
    </section>

    <section id="pdftex-option-translate-file">
      <title><filename role="nohyphenation">--translate-file tcxname</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--translate-file tcxname</tertiary>
      </indexterm>
      <para>Use the <literal>tcxname</literal> translation table.
      </para>
    </section>

    <section id="pdftex-option-version">
      <title><filename role="nohyphenation">--version</filename></title>
      <indexterm>
	<primary>pdfTeX</primary>
	<secondary>Options</secondary>
	<tertiary>--version</tertiary>
      </indexterm>
      <para>Print version information and exit.</para>
    </section>

  </section>

  <section id="pdftex-environment">
    <title>Environment</title>
    <indexterm>
      <primary>pdfTeX</primary>
      <secondary>Environment</secondary>
    </indexterm>
    <para>See the Kpathsearch library documentation (the `Path  specifications'
      node) for the details of how the environment variables are used when
      searching. The <command>kpsewhich</command> utility can be used to 
      query the values of the variables.
    </para>
    <para>One caveat: In most &pdftex; formats, you cannot use ~ in a filename you
      give directly to &pdftex;, because ~ is an active character, and hence is
      expanded,  not  taken as part of the filename.  Other programs, such as
      &metafont;, do not have this problem.
    </para>

    <para>
      <variablelist>
	<varlistentry>
	  <term><literal>TEXMFOUTPUT</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXMFOUTPUT</tertiary>
	    </indexterm>
	    <simpara>Normally, &pdftex; puts its output files in 
	      the current directory.
              If any output file cannot be opened there, it tries to open it
              in the directory specified in the environment variable 
	      <literal>TEXMFOUTPUT</literal>. There is no default value
	      for that variable. For example,
              if you say <command>pdftex  paper</command> and the
	      current directory is not writable, if 
	      <literal>TEXMFOUTPUT</literal> has the value 
	      <literal>/tmp</literal>, &pdftex; attempts to
              create <literal>/tmp/paper.log</literal> (and 
	      <literal>/tmp/paper.pdf</literal>, if any output is 
	      produced.)</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>TEXINPUTS</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXINPUTS</tertiary>
	    </indexterm>
	    <simpara>Search path for <literal>\input</literal> and 
	      <literal>\openin</literal> files.  This should probably
              start with ``.'', so that user files  are  found  before  system
              files.   An empty path component will be replaced with the paths
              defined in the <filename>texmf.cnf</filename> file. 
	      For example, set <literal>TEXINPUTS</literal>  to
              <literal>".:/home/usr/tex:"</literal> to prepend the 
	      current direcory and <literal>``/home/user/tex''</literal>
	      to the standard search path.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>TEXFONTS</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXFONTS</tertiary>
	    </indexterm>
	    <simpara>earch path for font metric
	      (<literal>.tfm</literal>)
	      files.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>TEXFORMATS</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXFORMATS</tertiary>
	    </indexterm>
	    <simpara>Search path for format files.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>TEXPOOL</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXPOOL</tertiary>
	    </indexterm>
	    <simpara>Search path for <command>pdfinitex</command>
	      internal strings.</simpara>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>TEXEDIT</literal></term>
	  <listitem>
	    <indexterm>
	      <primary>&pdftex;</primary>
	      <secondary>Environment</secondary>
	      <tertiary>TEXEDIT</tertiary>
	    </indexterm>
	    <simpara>Command template for switching to editor.
	      The default, usually <command>vi</command>, is set when 
	      &pdftex; is compiled.</simpara>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>
  </section>

</chapter>