% teTeX main documentation file. Thomas Esser, 1999, 2003. public domain.

\documentclass[11pt,a4paper]{article}

\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
% \usepackage{pslatex}
\usepackage{palatcm}
\usepackage{ifpdf}

\usepackage{geometry,mflogo,xspace,texnames,path,booktabs,bm}
\newcommand{\psext}{ps}
\newcommand{\pdfext}{pdf}
\newcommand{\dviext}{dvi}

\ifpdf
\usepackage[bookmarksopen=true, hypertexnames=false, linktocpage, pdfpagelabels, colorlinks, bookmarks]{hyperref}
\hypersetup{
  pdfauthor={Thomas Esser},
  pdftitle={The teTeX Manual}
}
\usepackage{thumbpdf}
\let\docext=\pdfext
\else
\let\docext=\dviext
\usepackage[bookmarks,hypertex]{hyperref}
\fi

\newcommand{\dlink}[3]{%
  \ifpdf
    \ifx\pdfext#3
      \href{#1/#2.#3}{\texttt{texdoc #2}}%
    \else
      \texttt{texdoc #2}%
    \fi
  \else
     \href{#1/#2.#3}{\mbox{\texttt{texdoc #2}}}%
  \fi}

\newcommand{\teTeX}{\textrm{te}\TeX\xspace}
\newcommand{\Linux}{\textrm{Linu}\textsf{X}\xspace}
% \newcommand{\MF}{\textlogo{Metafont}\xspace}
\newcommand{\smiley}{\texttt{ :-)}\xspace}

\title{\teTeX{} Manual}
\author{\href{mailto:te@dbs.uni-hannover.de}{Thomas Esser}}
\date{February 2003}

% \geometry{scale={0.637,0.637}, top=0.121\paperheight, nohead}
\usepackage{typearea}

\begin{document}

\maketitle

\begin{abstract}
  
  \teTeX{} is a distribution of \TeX{} and related programs: pdf\TeX,
  e-\TeX, Omega, \LaTeX, Con\TeX{}t, \MF, \MP{}, \texttt{dvips},
  \texttt{xdvi}, \texttt{dvipdfm}, \BibTeX{}, \texttt{makeindex} etc.
  
  \teTeX{} aims to make using and maintaining a \TeX{} system as easy
  as possible. The programs are built around the
  \href{http://tug.org/web2c/}{Web2c} distribution by Karl Berry
  and Olaf Weber. A common part of many programs is \texttt{kpathsea},
  a library that provides efficient access by name to files stored
  hierarchically.
  
  This document describes how to use and set up the \teTeX{} system.
  It does not attempt to be a comprehensive guide, instead it tries to
  give an overview about what software and documentation is contained
  in the distribution.
\end{abstract}

\newpage
\tableofcontents

\newpage

\section{The Components of \teTeX}

This document cannot describe all the programs which are part of
\teTeX{} in detail, but it tries to give you an overview. This section
describes the packages which form the main components of \teTeX{}. At
several places, the ``main texmf tree'' and the ``documentation tree''
are mentioned. These are the directory trees below the directories
whose names are given by the commands
\verb+kpsewhich -expand-var='$TEXMFMAIN'+ and
\verb+kpsewhich -expand-var='$TEXMFMAIN'/doc+, respectively.

\subsection{Web2c}
\href{http://tug.org/web2c/}{Web2c} is a \TeX{} implementation,
originally for Unix, but also running under Windows, Macintosh,
DOS, Amiga, and other operating systems. It includes \TeX{} itself and
the following programs:
  \begin{itemize}
  \item \MF: a font compiler intended to produce typefaces of high
    quality~\cite{Knuth:1984:M}.
  \item \MP: a program similar to \MF, modified to output Postscript
    code instead of bitmaps. Documentation for \MP{} is available
    via the command: \dlink{../metapost/base}{mpman}{\psext}.
  \item \BibTeX: a preprocessor to make bibliographies for
    \LaTeX. For documentation, see \dlink{../bibtex/base}{btxdoc}{\dviext} and
    Appendix~B of \cite{Lamport:1994:LDP}.
  \item utilities for converting between different font metric and
    bitmap formats: \texttt{gftopk}, \texttt{gftodvi},
    \texttt{gftype}, \texttt{pktogf}, \texttt{pktype},
    \texttt{pltotf}, \texttt{tftopl}, \texttt{vftovp}, \texttt{vptovf}.
  \item DVI utilities: \texttt{dvicopy, dvitomp, dvitype}.
  \item other tools: \texttt{patgen}, \texttt{pooltype},
    \texttt{tangle}, \texttt{weave}.
  \end{itemize}
  
  Note that some default settings of ``\texttt{tex}, the Web2C
  implementation of \TeX'' have changed.  We determined that some
  extensions were in fact in conflict with the strict definition of
  TeX as laid down by Knuth.

  The most notable change is that parsing of \verb+%&+ constructs in the
  first line of an input file is now disabled by default -- it can be
  enabled in \texttt{texmf.cnf} if you desire this.  In that case, tex will
  announce itself as ``TeXk'' and print an additional banner line saying
  that \verb+%&+-line parsing is enabled.
  
  We may encounter more places where the default behaviour is not what
  it should be, and proceed to make this optional (and by default off)
  in future versions of Web2C.

  The main documentation for \href{http://tug.org/web2c/}{Web2c} is
  the ``Web2c manual'' and the ``kpathsea manual''. These can be
  accessed via \dlink{../programs}{web2c}{\docext} and
  \dlink{../programs}{kpathsea}{\docext} respectively.

\subsection{\TeX{} extensions: pdf\TeX, e-\TeX{} and Omega}
Besides the standard \TeX{} program, the
  following extensions to \TeX{} are included in \teTeX:
\begin{description}
\item [pdf\TeX] This can optionally write Acrobat PDF format instead
  of DVI. The user manual can be accessed by the command
  \dlink{../pdftex/base}{pdftexman}{\pdfext}. The \LaTeX{} hyperref
  package (\dlink{../latex/hyperref}{manual}{\pdfext}) has an option
  ``pdftex'', which turns on all the program features. pdf\TeX{}
  supports graphics inclusion for the following graphic formats:
  \begin{itemize}
  \item PNG (portable network graphics)
  \item PDF (portable document format),
  \item JPG (jpeg)
  \item MPS (metapost output)
  \end{itemize}
  It does not support EPS (encapsulated postscript), but if you have
  recent versions of \texttt{ghostscript} (version 5.10 or later) and
  \texttt{perl} (version 5 or later) installed, you can use the tool
  \texttt{epstopdf} to convert EPS graphics into PDF. When including a
  PDF file, pdf\TeX{} is able to access parts of a multi-page file: a
  complete page or a clipped part of a page. This feature extends
  pdf\TeX{} beyond its typesetting capabilities into a versatile tool
  for handling arbitrary generated PDF files.

\item [e-\TeX] adds a small but powerful set of new primitives, and an
  extension for right to left typesetting. In default mode, e-\TeX{}
  is 100\,\% compatible with ordinary \TeX.  See
  \dlink{../etex/base}{etex-man}{\docext} for details.
\item [Omega ($\bm \Omega$)] Omega works internally with 16-bit
  Unicode characters; this allows it to work directly with
  almost all the world's scripts simultaneously. It also supports
  dynamically loaded ``$\Omega$ Translation Processes'' (OTPs), which
  allow the user to define complex transformations to be performed on
  arbitrary streams of input. Documentation:
  \dlink{../omega/base}{doc-1.12}{ps}.
\end{description}


\subsection{DVI drivers: dvips, dvilj, xdvi, dvipdfm}
For printing and previewing DVI files, you need to use one of the DVI
drivers that are available:
\begin{description}
\item [dvips] This driver converts DVI files into Postscript.
  Postscript is a page description language that many laser printers
  directly support. With the help of the utility \texttt{ghostscript},
  it is possible to view Postscript documents on screen and to print
  Postscript documents on non-Postscript printers. This version of
  \texttt{dvips} supports hypertex and partial font downloading.  In
  this release, the search path for config files have been changed:
  the current directory is no longer searched by default.
  Additionally, secure mode has been turned on by default. For
  details, consult the documentation:
  \dlink{../programs}{dvips}{\dviext}.
\item [dvilj] This is a family of drivers to support HP LaserJet (and
  compatible) printers: \texttt{dvilj, dvilj2p, dvilj4, dvilj4l,
    dvilj6}. These drivers are faster than the \texttt{dvips} +
  \texttt{ghostscript} alternative (which can also be used to print
  DVI files on HP LaserJet printers), but they lack a few features
  like support for virtual fonts, rotated or scaled graphics, etc.
\item [xdvi] This is a previewer for DVI files under the X~Window
  System. It has support for Postscript specials through Display
  Postscript, NeWS and \texttt{ghostscript}. Hypertex support was also
  added for this version of \texttt{xdvi}. A link can be followed by
  clicking with Button-1 or Button-2 (open link in a new window) on
  it. With the help of source specials, xdvi can interact with most
  editors in some way. For details, visit the
  \href{http://xdvi.sourceforge.net/inverse-search.html}{project
    page}.
\item [dvipdfm] This program can convert dvi files into pdf format,
  while supporting a rich set of features (via TeX's
  \textbackslash special scheme): hyperlinks, bookmarks, thumbnails,
  image inclusion etc. For details consult the documentation
  \dlink{../programs}{dvipdfm}{\docext} and the
  \href{http://gaspra.kettering.edu/dvipdfm/}{web page}.
\end{description}


\subsection{Makeindex}
\texttt{makeindex} is a general purpose hierarchical index generator;
it accepts one or more input files (often produced by a text formatter
such as \TeX{} or \texttt{troff}), sorts the entries, and produces an
output file which can be formatted.  The formats of the input and
output files are specified in a style file; by default, input is
assumed to be an \texttt{idx} file, as generated by \LaTeX.
Documentation: \dlink{../makeindex}{makeindex}{\dviext}

\subsection{Texinfo}
\texttt{texinfo} is a documentation system. It produces online or
printed output from a single source. It uses \TeX{} to typeset
documents for printing (\dlink{../programs}{texinfo}{\dviext}).


\subsection{UNIX Scripts / Tools}

If you are using \teTeX{} under UNIX, you can use the following
scripts. More documentation for a specific tool can either be obtained
from its UNIX manual page or by running the program with the option
\texttt{--help}. 
\begin{description}
\item[texdoc] allows you to easily access documentation included with
  \teTeX. You only have to remember the file name of the document that
  you want to access, without the directory part. If you do not
  specify a file name extension (such as \texttt{.dvi})
  \texttt{texdoc} will try a few default extensions. After searching
  the file, \texttt{texdoc} starts an appropriate viewer.  The command
  \texttt{texdoc~--help} gives you a list of available command line
  options. While \texttt{texdoc} is a fast and efficient tool if you
  exactly know what you are searching for, it is of limited use if you
  don't know the exact name of the documentation file.
\item [texdoctk] This \texttt{perl/tk} based tool allows you to browse
  through the available documentation by some topics and to search for
  keywords. It uses a simple database file for its configuration
  (named \texttt{texdoctk.dat}), which you can customize and extend
  easily.
\item[texconfig] allows you to carry out the most common configuration
  tasks in \teTeX. The program can be used in command mode or in
  interactive mode. For the interactive mode (which is invoked by
  calling \texttt{texconfig} without arguments), a curses based
  utility is used for user interaction (menus, check boxes, \ldots).
  The command \texttt{texconfig --help} shows you a list of available
  command line options (command mode).
  
  \verb+texconfig+ can be used to set up \TeX{} format files and their
  hyphenation patterns, to set up printers (for \verb+dvips+), to set
  preferences for automatic font generation, to set up the default
  resolution for previewing (for \verb+xdvi+) and for a few other
  things.  It manipulates configuration files to store the
  configuration changes.
\item[updmap] Some tools in \teTeX{} support Postscript Type~1
  fonts: \texttt{dvips}, \texttt{pdf\TeX}, \texttt{xdvi},
  \texttt{dvipdfm} and \texttt{gsftopk}, \texttt{ps2pk}. The last two
  in this list just convert outline fonts into a bitmap format which
  is helpful for applications that don't directly support outline
  fonts. In an ideal world, all of these programs would share a common
  configuration file to set up their outline fonts. The reality is
  different, however, and each tool needs its own configuration. The
  \texttt{updmap} utility was developed to generate these
  configuration files from a central repository. Adding font
  definitions for all supported applications from a map file
  \texttt{foo.map} can be as easy as %
  \verb+updmap --enable Map foo.map+. For details, please consult the
  manual page of \texttt{updmap}.
\item[dvired] This script can be used to print documents formatted for
  A4 paper 2-up (i.e.\@ two logical pages to one physical page of
  paper) by scaling the pages to 70.7\,\% of their original size.
  \texttt{dvired} can just be used in the same way as \texttt{dvips}
  (same command line options).
\item[dvi2fax] This script converts DVI files into FAX G3 format. It
  uses \texttt{ghostscript} (see:
  \url{http://www.cs.wisc.edu/~ghost/}) which is not part of \teTeX{}.
  The DVI file is first converted to Postscript ($204\times 196$\,dpi
  or $204\times 98$\,dpi) and then to FAX G3 using
  \texttt{ghostscript} (\texttt{faxg3} device).
\item[allcm, allec, allneeded] \teTeX's DVI drivers generate missing
  bitmap fonts on demand (the first time they are needed). If you
  start with a fresh installation, you don't have any bitmap fonts and
  the delay caused by font generation might be too annoying for you.
  In that case, the three scripts \texttt{allcm, allec and allneeded}
  can help you. \texttt{allcm} and \texttt{allec} create a few DVI
  files (using \LaTeX) which use lots of fonts at various sizes and run
  these DVI files through \texttt{dvips}. This triggers the generation
  of the most commonly used Computer Modern (\texttt{allcm}) and
  European Computer Modern (\texttt{allec}) fonts respectively. You
  might already have DVI files and want to generate just the bitmap
  fonts needed by these documents. This can be done by the
  \texttt{allneeded} script.  This script will search a given set of
  directories for DVI files and run them through \texttt{dvips}. All
  these scripts just trigger font generation. \LaTeX{} and DVI files
  generated by \texttt{allcm}/\texttt{allec} are removed when the
  program terminates. Postscript output that is generated by
  \texttt{dvips} is sent to \texttt{/dev/null}.
  
  These programs accept the command line option ``\texttt{-r}'' (must
  be the first option) to generate files for the magnification $707 /
  1000$ which is used by \texttt{dvired}. \texttt{allneeded} passes
  options which correspond to existing file or directory names to
  \texttt{find} (for locating DVI files). All other options given to
  any of these three utilities are passed to \texttt{dvips}. So, by
  passing \texttt{-D \textit{NNN} -mfmode \textit{some-mode}} or
  \texttt{-P \textit{some-printer}}, you can generate fonts for a
  specific resolution (\texttt{\textit{NNN}}) and mode
  (\texttt{\textit{some-mode}}) or for a specific printer
  (\texttt{\textit{printer}}).
\item[fontimport] This script can be used to import TFM (\TeX{} Font
  Metric) and PK (Packed Bitmap) files to their proper location in
  \teTeX's font tree.
\end{description}


\section{Concepts and configuration}

\subsection{The \TeX{} Directory Structure (TDS)}
\teTeX{}'s support tree with fonts, macros, documentation and other
files (from now on called the ``main texmf tree'') follows a certain
structure: the \TeX{} Directory Structure (TDS). This is a standard
developed by a \TeX{} Working Group of TUG. The TDS is defined in a
way so that can be used by different implementations of \TeX{} on
different platforms.  Today, several \TeX{} distributions follow this
standard: \teTeX, \TeX{} Live, fp\TeX{} and miktex, only to mention
some.  You need to understand this structure if you want to build your
own texmf tree (e.g.,\@ with all your local additions) or add files
into an existing texmf tree.  The list of all texmf trees (optionally
using some notation called ``brace expansion'' and \verb+!!+
modifiers; the kpathsea manual
explains this in detail) can be obtained by:\\
\null\qquad\verb+kpsewhich -expand-var='$TEXMF'+


\def\replaceable#1{{\rmfamily $\langle$\textit{#1}$\rangle$}} Table
\ref{tab:tds} gives a short overview of the TDS. It shows the proper
location inside the TDS tree for several kind of files. The complete
documentation for TDS can be accessed by
\dlink{../help}{tds}{\dviext}. If you want to see some examples, just
look at the main texmf tree of \teTeX. It has several thousand
files.\bigskip

\begin{table}[htbp]
  \begin{center}
    \begin{tabular}{cl}
      \toprule
      \TeX{} macros & tex/\replaceable{format}/\replaceable{package}/\\
      font files &  
fonts/\replaceable{type}/\replaceable{supplier}/\replaceable{typeface}/ \\
      \MF{} files & metafont/\replaceable{package}/ \\
      documentation & doc/\replaceable{package}/ \\
      sources & source/\replaceable{package}/\\
      \BibTeX{} files & bibtex/\{bst,bib\}/\replaceable{package}/\\
      \bottomrule
    \end{tabular}
    \caption{TDS: an overview}
    \label{tab:tds}
  \end{center}
\end{table}

The replaceable parts in this table mean:
\begin{description}
\item[\replaceable{format}] The name of the \TeX{} format, e.g.,\@
  \texttt{latex} or \texttt{amstex}.
\item[\replaceable{package}] The name of the package to which the file
  belongs, e.g.,\@ \texttt{babel} or \texttt{seminar}.
\item[\replaceable{type}] The name of the type of a font file, e.g.,\@
  \texttt{pk} (packed bitmap), \texttt{tfm} (tex font metric),
  \texttt{afm} (adobe font metric), \texttt{vf} (virtual font),
  or \texttt{source} (\MF{} source).
\item[\replaceable{supplier}] The name of the font supplier (to whom
  the font file belongs), e.g.,\@ \texttt{adobe} or \texttt{urw}.
\item[\replaceable{typeface}] The name of the typeface name (for this
  font file), e.g.,\@ \texttt{times} or \texttt{cm} (for Computer
  Modern).
\end{description}

It is important to know that the default search paths in \teTeX{} rely
on this directory structure. So, if you add a file to the wrong
directory tree, e.g.,\@ a TeX macro somewhere in the \texttt{fonts}
subtree, that file will not be found correctly.

\subsection{The file name database (ls-R)}
texmf trees can get very large and to speed up searching in such a
tree, a file name database is used. A file name database exists in the
root of each texmf tree and has the name \verb+ls-R+. It should list
each file in the texmf tree. The command \verb+texhash+ can be used to
build an up-to-date file name database for each texmf tree. It should
be used after files have been added to a texmf tree. However, you
don't need to run \verb+texhash+ for files added by the automatic font
generation or the \texttt{texconfig} utility.


\subsection{Runtime configuration (texmf.cnf file)}
\label{ss:texmfcnf}
Search paths and other definitions (e.g.,\@ the static sizes of some
arrays in \TeX{} or other programs) can be set up in configuration
files named \texttt{texmf.cnf}. By changing the definitions in these
configuration files (\teTeX's main \texttt{texmf.cnf} is
\path|web2c/texmf.cnf| in the main texmf tree), the behavior of
programs can be changed without recompiling them. Chapters 3 and 4 of
the kpathsea manual (\dlink{../programs}{kpathsea}{\docext}) describe
the path searching configuration in detail. Section 2.5 of the Web2c
manual (\dlink{../programs}{web2c}{\docext}) describes some
interesting runtime parameters that you might want to change.

Some changes to the array sizes require you to rebuild the dump files
that the program uses. Run the command \verb+texconfig init+ to
rebuild all dump files after you have changed one of the array sizes.

This implementation of \TeX{} can read and write files (as can every
implementation of \TeX) and it can also call external commands (via
the \verb+\write18+ stream). Some variables in the \verb+texmf.cnf+
file control access to these features. The possibility to call
external commands can be turned on or off (default is off). Access to
file beginning ``\verb+.+'' is disallowed in restricted mode (default
for reading files). In paranoid mode, file access is even more
restricted and you cannot access files outside the current directory
tree (default for writing files). If the first line of a document starts with \verb+%&+,
it can be used to pass the name of the format file and/or a TCX file.
Parsing the first line, is an extension that can be turned on or off
(default is off) in the \verb+texmf.cnf+ file.

\subsection{Using Postscript type 1 fonts}
For every font you use with \TeX, a TFM (\TeX{} font metric) file is
needed. Type~1 fonts usually do not have the same encoding that is
used by \TeX{}, so additional metrics that do some re-encoding (virtual
font files) are often needed. For a lot of font families, these font
metric files and additional map files that you need (see below) can be
found on CTAN servers in the directory \path|fonts|. If
support for your fonts cannot be found there, you can use the
\verb+fontinst+ utility (documentation:
\dlink{../fontinst/base}{fontinst}{\dviext}) to create these.

Postscript type 1 fonts can be used by \texttt{dvips}, \texttt{dvipdfm}, \texttt{xdvi},
\texttt{gsftopk}, \texttt{ps2pk} and pdf\TeX. All of these programs
require that you set up map files for these fonts. To ease the process
of adding map file entries to the configuration files that are used by
these tools, you should follow the following steps:
\begin{itemize}
\item if your fonts already come with a map file, put that
  file into the \path|dvips/misc| directory in the main texmf tree.
\item otherwise, you will need to create a map file yourself,
  using the syntax as described in the dvips manual
  (\dlink{../programs}{dvips}{\dviext}); make sure to set up these fonts
  as ``download fonts'', not as ``built in'' fonts.
\item run the command \verb+texhash+ and then make the map file known
  to \verb+updmap+ by running the command %
  \verb+updmap --enable Map file.map+ (where %
  \verb+file.map+ denotes the filename of your map
  file)
\end{itemize}

The programs \verb+gsftopk+ and \verb+ps2pk+ convert Postscript type 1
fonts into bitmap fonts and make these fonts accessible to DVI drivers 
that do not directly support Postscript type 1 fonts. This
conversion is automatically invoked by the \verb+mktexpk+
script. That script calls \verb+gsftopk+ by default. If you do not
have installed the \verb+ghostscript+ program (which \verb+gsftopk+
needs), or if you want to use \verb+ps2pk+ for other reasons (e.g.,
because it is usually faster) you just need to define the variable
\verb+ps_to_pk+ to \verb+ps2pk+. This variable can be set in your
environment or in the \verb+mktex.cnf+ file (see below).

\subsection{Configuration files maintained by texconfig}
The \texttt{texconfig} utility is a user interface for changing the
configuration of the \teTeX{} system. The configuration is stored in
several files. This section documents the names of the configuration
files, their location in the texmf tree and their content. This
explains how \texttt{texconfig} works and enables you to manually
configure parameters which are not supported by \texttt{texconfig}.

If the variable \verb|$VARTEXMF| is set (in a \path|texmf.cnf| file or
in the environment), its value is used as the name for a directory
which holds the files that \texttt{texconfig} generates.
\texttt{texconfig} also checks for the existence of each of the
configuration files in the \verb|$VARTEXMF| tree and copies missing
files from the main texmf tree. When a \verb|$VARTEXMF| tree is used,
only the configuration files in that texmf tree are modified; those in
the main tree remain unchanged.

\begin{itemize}
\item \path|tex/generic/config/language.dat|,
  \path|tex/context/config/cont-usr.tex|,
  \path|etex/plain/config/language.def| are files which are used to
  set up the hyphenation tables for format files. The
  \path|language.dat| file is read by all format files which use the
  babel package to set up their hyphenation, \path|language.def| is
  used by e-\TeX's \texttt{etex} format and \path|cont-usr.tex| is
  used by the Con\TeX t formats. After changing one of these three
  files, you need to rebuild the format files by using the command
  \verb+fmtutil --all+
\item \path|dvips/config/config.ps| stores configuration information for
  \texttt{dvips}. The default values are: 600\,dpi resolution; ljfour
  \MF{} mode; A4 paper; offset for printing: 0pt,0pt; output goes to
  \texttt{lpr} command.
\item \path|dvipdfm/config| defines the defaults for \verb+dvipdfm+,
  e.g.\@ the default paper size, the command to convert encapsulated
  postscript graphics into PDF etc.
\item \path|pdftex/config/pdftex.cfg| This file defines the defaults
  for pdf\TeX{}, e.g.\@ the default paper size, compression level etc.
\item \path|web2c/updmap.cfg| controls how \verb+updmap+ generates map
  files for all supported tools. Besides some general parameters, all
  active map files are listed here.
\item \path|xdvi/XDvi| This file sets some defaults for \verb+xdvi+.
  It is read via the app-default mechanism of X11. You can override
  these app-defaults as usual (i.e.\@ via a file \verb+~/.Xdefaults+ or
  with resources managed by \verb+xrdb+). The file sets the following
  defaults: 600\,dpi resolution; ljfour \MF{} mode; A4 paper; initial
  shrink factor of 8; Netscape as the web browser; ``thorough'' handling
  of overstrike characters. The manual page \verb+xdvi(1)+ explains all
  of these and other parameters that can be set.
\item \path|web2c/fmtutil.cnf| This file defines which format files
  are built (and how) and which file can be used to customize the
  hyphenation patterns that are loaded into these formats. The
  programs \verb+fmtutil+ and \verb+texlinks+ (which are automatically
  called if the formats are set up via \verb+texconfig+) operate on
  this file. \verb+fmtutil+ can be used to create the format files
  according to the ``rules'' defined in \verb+fmtutil.cnf+ (for a
  brief description, just call \verb+fmtutil --help+). If you define a
  new format file, you usually also need a symbolic link with the name
  for the format to the appropriate \TeX{} engine (e.g.,
  \verb+latex+~$\to$~\verb+tex+). To create these links, just call the
  \verb+texlinks+ script.
\item \path|web2c/mktex.cnf| This file is used by the scripts for
  automatic font generation. It sets some defaults for \verb+mktextfm+
  and \verb+mktexpk+: 600\,dpi resolution; ljfour \MF{} mode and it
  defines which of the following ``features'' are used:
  \begin{description}
  \item [appendonlydir] Set the sticky bit on directories that have to
    be created. The sticky bit has the effect that a file in such a
    directory can only be removed by the owner of that directory or by
    the owner of that file.
  \item [dosnames] Use 8.3 compatible names for font files,
    e.g., \verb+dpi600/cmr10.pk+ instead of \verb+cmr10.600pk+.
  \item [fontmaps] Instead of deriving the location of a font in the
    destination tree from the location of the sources, the aliases and
    directory names from the Fontname distribution are used.
  \item [nomfdrivers] Let \verb+mktexpk+ and \verb+mktextfm+ create
    \MF{} driver files in a temporary directory.  These will be used
    for just one \MF{} run and not installed permanently.
  \item [nomode] Omit the directory level for the mode name; this is
    fine as long as you generate fonts for only one mode.
  \item [stripsupplier] Omit the font supplier name directory level.
  \item [striptypeface] Omit the font typeface name directory level.
  \item [varfonts] When this option is enabled, fonts that would
    otherwise be written in the system texmf tree go to the
    \verb+VARTEXFONTS+ tree instead.  The default value is in
    \path|/var/tmp/texfonts|.  The ``Linux File System Standard''
    recommends \path|/var/tex/fonts|.

    The \verb+varfonts+ setting in \verb+MT_FEATURES+ is overridden by
    the environment variable \verb+USE_VARTEXFONTS+: if set to 1, the
    feature is enabled, and if set to 0, the feature is disabled.

    If you use the \verb+varfonts+ feature, you can forbid public
    write access to the fonts subdirectory in the main texmf tree by
    removing write permissions for ``world''. This can be done by the
    command \verb+texconfig fonts ro+

  \end{description}
\end{itemize}


\subsection{TCX files}
TCX (\TeX{} character translation) files help \TeX{} support direct
input of 8-bit international characters if fonts containing those
characters are being used.  Specifically, they map an input (keyboard)
character code to the internal \TeX{} character code (a superset of
ASCII).

\teTeX{} has the TCX files \verb+il1-t1.tcx+ and \verb+il2-t1.tcx+
which support ISO Latin 1 and ISO Latin 2, respectively, with
Cork-encoded fonts (a.k.a.: the T1 encoding).  TCX files for Czech,
Polish, and Slovak are also provided.

All TCX files that are distributed as part of \teTeX{} can be found in
the web2c subdirectory of the main texmf tree; their file name
extension is \verb+.tcx+.

You can specify a TCX file to be used for a particular \TeX{} run by
specifying the command-line option
\hbox{\texttt{-translate-file=\textsl{tcxfile}}} or (preferably)
specifying it explicitly in the first line of the main document
\hbox{\texttt{\%\& -translate-file=\textsl{tcxfile}}}. Note, however,
that parsing the first line of an input file in an extension that is
disabled by default and has to be turned on via command line switch
(\verb+-parse-first-line+) or in the \verb+texmf.cnf+ file (see
section \ref{ss:texmfcnf}).

When using TCX files, you usually must not use \LaTeX's
\verb+inputenc+ package. The TCX file \verb+cp8bit.tcx+ is an
exception to this rule.  The map defined in that file is the identity,
i.e.\@ the characters are all mapped to their original position. The
purpose of this TCX file is not the mapping it describes, but the
side-effect that all characters (even those with positions above 127)
are considered to be printable and can be written to the terminal and
into log files.


\subsection{Creating PDF files}
If you want to create PDF documents with the help of \TeX, there are
at least three different ways to do this
\begin{enumerate}
\item translate your \TeX{} sources directly into PDF by using pdf\TeX.
\item translate DVI files generated by \TeX{} into PDF by using the
  \texttt{dvipdfm} program (now included in \teTeX).
\item translate a Postscript file generated by \TeX{} and
  \texttt{dvips} into PDF by using Adobe Acrobat or
  the \texttt{ps2pdf} utility included in ghostscript. 
\end{enumerate}
When using \texttt{ps2pdf}, you should make sure to use at least
version 6.50 of ghostscript. Earlier versions are known to have
serious restrictions on creating PDF output.

No matter which approach you use, there is one common rule when
creating quality PDF files: you should avoid bitmap fonts. They just
display very poorly when used in PDF documents.

Using only the fonts provided by \teTeX, you have more choices for
which fonts to use.  The following typeface families are included in
Postscript type~1 format:
\begin{itemize}
\item Computer Modern and the AMS fonts (extended versions with
  polish, czech and slovak and russian letters are available, too)
\item the full set of the 35 basic ``LaserWriter fonts'' (see psnfss
  documentation, supporting other fonts are pazo, tx/px fonts)
\item Bitstream Charter
\end{itemize}

The EC fonts are not freely available in type 1 format. But, if you
have a \LaTeX{} document that uses EC fonts, you usually have three
ways to get around this problem. The first is to stop using
EC fonts---which normally means a switch back to Computer Modern. Usually, the
EC fonts are activated by \verb+\usepackage[T1]{fontenc}+ or
\verb+\usepackage{t1enc}+ and you just have to remove that code from
your file. The second is to use the AE fonts, which are a set of
virtual fonts that map from the Computer Modern fonts to (nearly) all
characters of the EC fonts. This can be done by adding
\verb+\usepackage{ae}+ to your document.  The third is to use the CM-SUPER
Type~1 fonts, not included in \teTeX,
but available on CTAN servers in the directory
\path|fonts/ps-type1/cm-super|. This package is pretty huge, but it
contains all EC fonts in outline format and much more.

\section{Resources}

This section describes where you can find further (or more up-to-date)
material and support in the world of \TeX.


\subsection{Helpindex file for the documentation tree}
The file \path+newhelpindex.html+ in the root of \teTeX's
documentation tree is a guide for the documentation that is included
in \teTeX. It is a good point to start when you want to browse through
the documentation or search for the solution of a specific problem.

\subsection{Internet Newsgroups}
If you encounter a problem which might not be \teTeX{} specific, but
rather a general problem with \TeX{} or \LaTeX{} (e.g.,\@ ``How can I
format a section heading in a different way?''), you should not raise
your question on one of the mailing lists for \teTeX. In the following
newsgroups, \TeX-related matters are discussed:
\begin{description}
\item [comp.text.tex] General things about \TeX{}.
\item [news.answers] FAQs (also \TeX-related FAQs).
\item [comp.answers] FAQs (also \TeX-related FAQs).
\item [de.comp.text.tex] General things about \TeX{} (German).
\item [fr.comp.text.tex] General things about \TeX{} (French).
\item [comp.fonts] Font matters.
\item [comp.programming.literate] Literate programming.
\end{description}

\subsection{\TeX{} User Groups}
If you enjoy \TeX{}, you can join a \TeX{} user group to get support
and software and help the \TeX{} community by your membership. The web
site of the \TeX{} User Group (TUG), \path|http://tug.org/| has the
necessary contact information for several \TeX{} user groups.


\subsection{Mailing Lists}
All \teTeX{} mailing lists are hosted on the same server which is
managed by Majordomo software. Administrative requests,
e.g.,\@ to (un)subscribe or to get an archive of a list are handled by
the address: \path|majordomo@dbs.uni-hannover.de| To get a list
of available commands that the Majordomo server understands, just send the
message ``help'' to the server (in the body of a message, not in the
header). The lists are:
\begin{description}
\item[tetex] General discussions + bug reports about \teTeX. General
  \TeX{} matters that are not \teTeX-specific are not discussed.
  Especially general questions about \TeX{} should \emph{not} be
  directed to this list; use a newsgroup instead.
\item[tetex-announce] This (moderated, low traffic) list is used for
  important announcements about \teTeX, such as new releases or important
  updates.
\item[tetex-pretest] This is used to discuss beta versions of \teTeX{}
  and to report bugs in these versions. Bug reports about official
  (non-beta) releases should not be send here, but to the \texttt{tetex}
  list.
\end{description}

Some of the packages which are contained in \teTeX{} (e.g.,\@ Omega
and pdf\TeX) have special mailing lists or web resources on their own.
The web site of TUG, \path+http://tug.org/+ has links to many of them.


\subsection{Comprehensive TeX Archive Network (CTAN)}
To aid the archiving and retrieval of \TeX{}-related files, a TUG
(TeX User Group) working group developed the Comprehensive \TeX{}
Archive Network (CTAN).  Each CTAN site has identical material, and
maintains authoritative versions of its material.  These collections
are extensive; in particular, almost everything mentioned in this
article is archived at the CTAN sites, even if its location isn't
explicitly stated.

The CTAN sites are currently \verb|dante.ctan.org|,
\verb|cam.ctan.org| and \verb|tug.ctan.org|.  The organization of
\TeX{} files on all these sites is identical and starts at
\path|/tex-archive|.  To reduce network load, please use the CTAN site
or mirror closest to you.  A complete and current list of CTAN sites
and known mirrors can be obtained by using the \verb|finger| utility
on `user' \verb|ctan@cam.ctan.org| (it also works with the other CTAN
hosts); it is also available as file \path|help/ctan/CTAN.sites| in
\teTeX's documentation tree.


\subsection{The \TeX{} Catalogue}

This catalogue lists many \TeX, \LaTeX, and related packages and
tools.  Most are available worldwide online from CTAN, the
Comprehensive TeX Archive Network. Links are provided in this
catalogue to available sources and documentation. The \teTeX{}
documentation tree contains a version of this catalogue in
\path|help/Catalogue|. The most recent online version is available at
\begin{center}
\url{http://datamining.csiro.au/tex/catalogue.html}
\end{center}

\subsection{Frequently Asked Questions (FAQs)}
Documents which list frequently asked questions and their answers (in
short: FAQs) are collections of solutions to many common problems. The
documentation tree of \teTeX{} contains the \teTeX{} FAQ in the
directory \path|tetex| and several other FAQs in the directory
\path|help/faq|:
\begin{description}
\item[UKTUG \TeX FAQ] This FAQ is maintained by the UK \TeX{} Users
  Group.
\item[\TeX{} FAQ] This is an old and currently unmaintained FAQ about
  \TeX.
\item[DANTE \TeX{} FAQ] This is a German FAQ maintained by members of
  the German \TeX{} users group (DANTE).
\item[LaTeX-FAQ-francaise] This is a French FAQ about \LaTeX.
\end{description}
The \teTeX{} FAQ can be read by the command \verb+texconfig faq+.

\bibliographystyle{plain}
\bibliography{TETEXDOC}

\end{document}
\endinput
% LocalWords:  teTeX Esser pdf dvips xdvi dvipdfm makeindex kpathsea texmf DVI
% LocalWords:  Amiga typefaces mpman btxdoc gftopk gftodvi gftype pktogf pktype
% LocalWords:  pltotf tftopl vftovp vptovf dvicopy dvitomp dvitype patgen tex
% LocalWords:  pooltype cnf TeXk behaviour pdftexman hyperref pdftex PNG JPG ps
% LocalWords:  jpeg MPS metapost EPS ghostscript perl epstopdf etex Unicode doc
% LocalWords:  OTPs dvilj hypertex config LaserJet dvi bookmarks thumbnails idx
% LocalWords:  Texinfo texinfo texdoc texdoctk tk dat texconfig updmap gsftopk
% LocalWords:  pk foo dvired dpi faxg allcm allec allneeded NNN mfmode TFM TDS
% LocalWords:  fontimport fp miktex tds metafont bibtex bst amstex babel tfm vf
% LocalWords:  afm urw ls TCX CTAN fontinst misc def cont usr ljfour pt lpr app
% LocalWords:  XDvi appendonlydir dosnames fontmaps Fontname nomfdrivers nomode
% LocalWords:  stripsupplier striptypeface varfonts Slovak tcxfile czech slovak
% LocalWords:  russian LaserWriter psnfss pazo tx px Bitstream EC AE Ppdf html
% LocalWords:  preconfigured Helpindex newhelpindex comp Majordomo un tetex faq
% LocalWords:  Catalogue catalogue UKTUG UK francaise TETEXDOC
