\title[A \LaTeX\ Tour; part 2]{A 
\LaTeX\ Tour, part 2: the  Tools and Graphics distributions}
\author{David Carlisle}

\begin{Article}

\section{Introduction}
In the previous article in this series I started by giving a
description of the files in the `\package{base}' \LaTeX\ distribution.
In part~2, I shall cover the `\package{tools}' and
`\package{graphics}' distributions. 
These are distributed in the \File|tools| and \File|graphics|
subdirectories of the \acro{CTAN} directory
\path{macros/latex/packages}.
Although these files are not part of the minimal \package{base}
distribution they should normally be included in the \LaTeX\
installation at any site. The \LaTeX\ book assumes that at least the
\package{graphics} distribution is installed.

The primary source for \LaTeX\ is the `\acro{CTAN}'\footnote
{\texttt{ftp.tex.ac.uk} in the UK} network of archives, so
if I refer to path names of files this relates to the \acro{CTAN} file
structure. Note however that if you obtained \LaTeX\ as part of a
`pre-packaged' \TeX\ distribution, then these files may have been
moved (typically documentation files may be separated from \TeX\
source files). I hope this will not cause any confusion.

\section{The \package{Tools} Distribution}

The \package{tools} distribution consists of packages written by
individual members of the \LaTeX3 project. They are supported by the
same mechanism as the \package{base} \LaTeX\ distribution, that is, any
problems should be reported using \File|latexbug.tex| and the \LaTeX\
bug report database, as described in part~1. Note that this bug report
system should \emph{not} be used for `contributed' packages that one
may find in the \path{macros/latex/contrib} area of the \acro{CTAN}
archives.

\subsection{Packages Extending the \env{array} and \env{tabular}
Environments}

The first group of packages extend the functionality of the standard
\LaTeX\ \env{array} and \env{tabular} environments. These are all
described in Chapter~5 of \emph{The \LaTeX\ Companion}, as well of
course as in the source `\texttt{.dtx}' files which may be processed
by \LaTeX\ to produce typeset documentation, and optionally code
listings. 
\begin{filedesc}

\item[array]
        Extended versions of the \env{array},
        \env{tabular} and \env{tabular*} environments.
 The principal advantage of
        the versions provided by this package is that you can specify
typesetting instructions to apply to a whole column of the table. As
well as the usual \texttt{clr} column specifiers, one may add commands
at the beginning of each entry with \texttt{>} and at the end of each
entry with \texttt{<}. So a column specifier of \verb|>{\bfseries}c|
would produce a bold, centred column of a table.

The \package{array} package also provides a \verb|\newcolumntype|
command for defining new column specifiers, in addition to the
standard ones. This is used by some of the packages described below.

\item[dcolumn]
        Alignment on `decimal points' in tabular entries. Requires
\package{array}. This package provides a new column specifier
\texttt{D} which may be used to produce columns of numbers aligned on
a decimal point `.' or some other symbol, such as `$\cdot$' or `,'.

\item[delarray]
This package requires
the   \package{array} package. It provides a mechanism for specifying
`large delimiters' around arrays. This is most convenient for putting
brackets around arrays that are to be aligned on their top or bottom
row (when the `obvious' construction with \verb|\left| and
\verb|\right| does not work). Compare the standard
\begin{smallv}
\begin{verbatim}
\left(
\begin{array}[t]{c}a\\b\end{array}
\right)
\left(
\begin{array}{cc}a&b\end{array}
\right)
\end{verbatim}
\[
\left(\begin{array}[t]{c}a\\b\end{array}\right)
\left(\begin{array}{cc}a&b\end{array}\right)
\]
with the effect produced using the \package{dcolumn} syntax.
\begin{verbatim}
\begin{array}[t]({c})a\\b\end{array}
\begin{array}({cc})a&b\end{array}
\end{verbatim}
\[
\begin{array}[t]({c})a\\b\end{array}
\begin{array}({cc})a&b\end{array}
\]
\end{smallv}
\item[hhline]
        Finer control over horizontal rules in tables. Requires
        \package{array}. Standard \LaTeX's \verb|\hline\hline|
construction produces a double rule across a table, but the user
has no control over how this rule interacts with vertical rules. Using
the \verb|\hhline| command provided by this package, gives
`corners' where a double horizontal rule meets a double vertical rule,
and other similar effects.

Compare the first, standard construction with the following
\verb|\hhline| sample:

\begin{tabular}{||c|ccc||}
\hline\hline&&&\\\hline\hline
\end{tabular}
\qquad
\begin{tabular}{||c|ccc||}
\hhline{|t:=|===:t|}&&&\\\hhline{|b:=|===:b|}
\end{tabular}
\item[longtable]
  Standard \LaTeX\ tables (i.e., the \env{tabular} environment) produce
`boxes' that cannot be broken across a page. This has advantages in
that the table can then be positioned just like a large `character'
(say centred by the \env{center} environment), but has the
disadvantage that large tables need to be broken by hand to fit on the
page. The \env{longtable} environment is essentially the same as
\env{tabular} but produces tables that break at page boundaries, and
has some additional commands to control `head' and `foot' lines of the
table that are added to each page. If the \package{array} package is also
loaded, then the extra features may also be used in \env{longtable}
column specifications. Note that \package{longtable} can deal with
\emph{very} long tables, longer than can be stored in memory by
\TeX's primitive \verb|\halign| command.

The \package{longtable} package has a few quirks and features that
mean that it is not suitable in all cases. An alternative package
(currently maintained by Johannes Braams, but as a contributed
package, not as part of the \package{tools} distribution) is
the package \package{supertab} which provides a similar
\env{supertabular} environment.
\item[tabularx] Defines the \env{tabularx} environment which is
similar to \env{tabular*}  but modifies  column widths, not
inter-column space, to achieve a desired table width.

One common request is to combine the features of
\env{tabularx} with \env{longtable}, i.e., have a table across multiple
pages, in which the widths of the `parbox' columns are calculated
automatically. This functionality is not provided by the standard
packages in the \package{tools} distribution, but the experimental
contributed package \package{ltxtable} does provide such an
environment. (\package{ltxtable} is written by the 
same author as \package{longtable} and \package{tabularx}; however,
problems with  \package{ltxtable} should \emph{not} be addressed to
the \LaTeX\ bugs system.) An alternative to \package{ltxtable} is
Anil~Goel's  contributed package, \package{ltablex}, a similar
merger which is simpler to use than \package{ltxtable}, but not quite
as powerful.

\end{filedesc}

\subsection{Missing File Error Control Files}
Although these files (which are all generated from the same source
file, \File|fileerr.dtx|) are distributed as part of the \LaTeX\
distribution, they are possibly of more use when used with
\emph{other} formats. The primitive \TeX\ behaviour if asked to input
a non-existent file is to offer a prompt:
\begin{smallv}
\begin{verbatim}
Please type another input file name: 
\end{verbatim}
\end{smallv}
You \emph{must} type a valid file name to this prompt or \TeX\ just
repeats the request. On some systems you can use a mechanism to abort
the job (e.g., control-C or control-Z) but there is no way to tell
\TeX\ to skip the input or do any other error recovery.

To avoid this unpleasant loop, \LaTeX\ always checks that a file
exists before trying to input it (unless you use the primitive
\verb|\input filename| syntax with no \verb|{ }| around the
argument).

If you do encounter this loop using a different format, or with
\LaTeX, by mistyping the file name on the command line, then the
following \texttt{.tex} files provide valid filenames that you can
easily remember to type at the missing file prompt. The
actions that each of these \texttt{.tex} files takes is designed to
mimic the actions that are possible after a \TeX\ error.

\begin{filedesc}
\item[h] Typing \texttt{h} $\langle$\emph{return}$\rangle$ to the
missing file prompt will cause \TeX\ to input \File|h.tex|, this
produces a helpful message, and then produces the normal `error
prompt' i.e.,\ \texttt{?} so you can hit
$\langle$\emph{return}$\rangle$ to move on, or \texttt{x} to quit, or
whatever.

\item[s] Typing \texttt{s} $\langle$\emph{return}$\rangle$ inputs
\File|s.tex| which puts \TeX\ into `scroll mode'. This means that it
will scroll past future errors without stopping.

\item[x] Typing \texttt{x} $\langle$\emph{return}$\rangle$ causes the
current \TeX\ run to be aborted.

\item[e] The file \File|e.tex| is in fact the same as \File|x.tex| but
allows \texttt{e} to be given as an answer to the missing file prompt
similar to the \texttt{e} response to the error prompt (which is
supposed to start up an editor but usually is the same as \texttt{x}).

\item[\char`\ ] If the operating system allows there will also be a file
\File|.tex| which does nothing, this will mean that just hitting 
$\langle$\emph{return}$\rangle$ in response to the missing file
prompt inputs \File|.tex| and allows \TeX\ to  proceed with the
original file.
Some operating systems object to a file with only an extension and no
filename before the `\texttt{.}' so this option may not be available
to you. Most \TeX\ distributions include a file \File|null.tex| which
is also empty, so if you do not have the option of installing the file
\File|.tex| you may type \texttt{null}~$\langle$\emph{return}$\rangle$
in response to the missing file prompt, which will also allow \TeX\ to
proceed. 
\end{filedesc}


\subsection{Miscellaneous \package{Tools} Packages}
\begin{filedesc}

\item[afterpage]
  Defines an \verb|\afterpage| command that saves up its argument and
executes it after the current page (i.e., at the top of the next
page). \LaTeX's output routine was \emph{not} designed with the idea
that packages might want to play kind of trick, so this
package is particularly fragile. In fact it was only written as a kind
of private joke; I noticed the comment 
``\emph{Output routines are always protected by enclosing them
in groups, so that they do not inadvertently mess up the rest of
\TeX}'' in the \TeX{}book, and wanted to answer\footnote{%
The answer incidentally is not at the top of the next page, but rather
any of the places where the \TeX{}book uses the magic phrase
``\emph{exercises the page builder}''.} the question,
``\emph{Where do you end up if you jump out of that group with
\texttt{\string\aftergroup}?\/}'' Despite this, judging by  reactions, 
people do seem to find the package 
useful\ldots
\item[enumerate]
        Extended version of the \env{enumerate} environment. The
 environment is given an optional argument which controls how the
counter is printed. For example \verb|\begin{enumerate}[a)]| would
produce items labelled `a)' ` b)' ` c)'.

\item[ftnright]
        Place footnotes in the right hand column in two-column mode.
        Normally \LaTeX\ places footnotes at the bottom of each
        column. This package causes the footnotes for both columns of
a page to be set in the
normal text area at the end of the second column on each page.
It currently works only with the standard two column mechanism, not
with the mechanism of the \package{multicol} package.

\item[indentfirst]
        Indent the first paragraph of sections etc. This very small
package just suppresses the usual \LaTeX\ mechanism which ensures that
the first paragraph of each section is not indented.
\item[multicol]
Typeset text in columns (up to 10 columns per page), with the
length of the final columns `balanced'. \BV~uses this package to
balance the columns at the end of every article. Unlike the standard
\verb|\twocolumn| command, this package allows changing the number of
columns part way down a page. It does have some restrictions on the
use of floats which means that it is not suitable for all purposes.
Also (uniquely for the files in the core \LaTeX\ distribution) this
package has special conditions on commercial use.

\item[rawfonts]
        Preload fonts under the old internal font names of \LaTeX\,2.09.
        Not recommended for new packages, but may help when updating old
        files.

\item[somedefs]
       This package is not intended to be called directly by a
document, but may by used (via \verb|\RequirePackage|) to build a
package in which you want the default behaviour to be to execute
\emph{all} possible options, but that the user may execute just some
of the options by specifying options in the \verb|\usepackage| call.
This is used in the \package{rawfonts} package above to allow just
some of the `old' font names to be defined rather than all of them.

\item[theorem]
       Flexible definition of `theorem-like' environments. The
standard \verb|\newtheorem| command gives some control over the title
and numbering of `theorem-like' declarations, but is not very
flexible. The \package{theorem} package provides an enhanced
declaration scheme which gives control over the fonts used in the
heading and theorem body, and such details as whether the numbering is
`\textbf{Theorem~1}' or `\textbf{1~Theorem}'. Recently this package
has acquired a close cousin, the \package{amsthm} package, part of the
`AMS-\LaTeX' collection. The AMS variant has perhaps slightly simpler
user-syntax but is used in much the same way. 

\item[varioref]
Provides \verb|\vref| and related commands. \verb|\vref| is like a
combination of \verb|\ref| and \verb|\pageref| which produces
references such as `Figure~2 on page~3'. However, it omits the page
number if it is on the current page, and replaces it by phrases such as
`on the facing page' when appropriate.

\item[verbatim]
 Flexible version of \env{verbatim} environment. The standard \LaTeX\
\env{verbatim} environment can not easily be used in the definition of
other environments as typically the \verb|\end| of the newly defined
environment is not recognised as such, but is treated as verbatim
text. This package re-implements \env{verbatim} such that (with some
restrictions) it can be used in the definition of other environments
and commands. It 
also defines some such derived environments, for inputting and writing
files verbatim, and for adding line numbers, and also a \env{comment}
environment that ignores all the environment body.

\item[xr]
       The \package{xr} (e\underline{x}ternal \underline{r}eferences)
package allows one \LaTeX\ document to access the \texttt{.aux} file of
another. So if file \texttt{fileA} has a section marked with
\verb|\label{xyz}| then file \texttt{fileB} may refer to that section
using \verb|\ref{xyz}| just as if it were part of the same document. This
requires the file \File|fileA.aux| created when \texttt{fileA} was processed
to be still available when \texttt{fileB} is processed. (This package was
originally by Jean-Pierre Drucbert, but was  recoded
and adopted into the \package{tools} distribution.)

\item[xspace]
 One of the more common errors in \TeX\ documents is to use a command
 such as \verb|\TeX| within text, but forget to follow it with 
\verb*|\ | or \verb|{}|. This package defines a command
\verb|\xspace| which may be used at the end of the definition of such
a `text command'. It looks ahead  and adds a space
unless the next token is a punctuation character.
\end{filedesc}

\subsection{Packages for Drafts and Tests}
\begin{filedesc}
\item[fontsmpl]
        Package and test file for producing `font samples'. The base
distribution contains a file \File|nfssfont.tex| that shows some small
samples, and a character table for a given font. \File|fontsmpl.tex|
produces a much more extensive test showing examples of all the fonts
in a given family. If you want to devise your own similar test suite
you may use the \package{fontsmpl} package, following the examples in
\File|fontsmpl.tex|.

\item[layout] Defines a \verb|\layout| command that produces a half
size `picture' of the document page settings such as
\verb|\textwidth|, \verb|\oddsidemargin|, \ldots\ together with a table
of their values. This is quite useful when designing a new class file,
as it gives a visual representation of how the various areas of the
page for headlines, body text, marginal notes, etc.,\ relate to each
other.
\item[showkeys]
 \LaTeX's automatic numbering and cross referencing feature is one of
its strongest points, as it makes editing a document (and thus
potentially changing the numbering throughout the rest of the file)
quite painless. However, one disadvantage is that when reading a
printed draft, one sees `final' numbers rather than the symbolic names
that are used in the source file's \verb|\label| and \verb|\ref|
command. This package makes these symbolic names, or `keys', appear in
the
margin\vadjust{\smash{\rlap{\kern-3pt\small\fbox{lbl}}}} in the case
of \verb|\label| 
and \verb|\bibitem| or raised above the number, like this 
  \vbox to 0pt{\vss
    \rlap{\vrule\raise .75em
       \hbox{\underbar{\footnotesize\ttfamily lbl}}}}1, in the case of
\verb|\ref| and \verb|\cite|. Some people find the raised labels above
cross references distracting and so a package option turns them off,
just leaving the marginal notes showing the \verb|\label| and
\verb|\bibitem| keys.
\end{filedesc}

\section{The \package{Graphics} Distribution}

\TeX\ (and the \texttt{dvi} format) is only designed to deal with
rectangular boxes consisting of text, white space or rectangular
rules. However it has an `escape mechanism', the \verb|\special|
primitive command that allows processing instructions to be passed
straight from \TeX\ (via the \texttt{dvi} file) to the `driver'
program that is used to process (e.g., preview or print) the
\texttt{dvi} file. \TeX\ places essentially no restrictions on what
instructions may be passed via \verb|\special|, and so the
possibilities are unlimited\ldots

Most modern drivers can import `graphic' files of various sorts.
Those drivers that are producing \PS\ can often do more extensive
manipulations of the typeset text, such as scaling or rotation of the
text, or even writing text along an arbitrary curve. Many of these
drivers can also support colour to some extent. Unfortunately as all
these features require that the \texttt{dvi} file stores processing
instructions for the driver, it means that the \texttt{dvi} file is
not portable to a site that uses a different driver program. There
have been many attempts over the years to coordinate the
\verb|\special| syntax used by the different drivers, so that they
would all accept a common core of processing instructions, but there
has been notable lack of success in such efforts to date\ldots

As a `next best thing' to having portability at the \texttt{dvi} level,
\LaTeX\ supplies a suite of standard graphics commands provided by the
packages described in this section, so that at least \TeX\ source
files should be reasonably portable. At a given site the graphics
packages will be customised to use a suitable `back end' file that
converts the \LaTeX\ syntax into the form required by the local
driver. This should mean that as long as both drivers support some
feature, such as including \PS\ graphics, a file just needs to be
re-processed with \LaTeX\ to use the \verb|\special|s at the new site;
the \LaTeX\ file does not need to be edited. Although this suite of
programs was devised as part of \LaTeX, users of other \TeX\ formats
may use them by way of the interface available from \acro{CTAN}
hosts in \path{macros/generic/graphics}.

\subsection{Documentation}
All the packages in this distribution are, as usual, distributed as
documented sources in \texttt{dtx} form, however the documentation in
these package sources is rather technical. A separate `User Guide' is
available as \LaTeX\ source in \File|grfguide.tex| and also in
pre-formatted form in the \PS\ file \File|grfguide.ps|.

The \package{color} package (which produces colours despite the
strange spelling) and the \textsf{graphics} package are also described
in Lamport's \LaTeX\ manual. An alternative to \File|grfguide.tex| as
a free source of documentation is Keith Reckdahl's \emph{Using EPS
Graphics in \LaTeXe\ Documents} distributed
from \acro{CTAN} sites in the file \path{info/epslatex.ps}
and published in \tubissue{17}{1--2}. This
document covers the \package{graphicx} package in some depth, and also
related contributed packages for controlling figure placement and
captions, and the \package{psfrag} system for overlaying \LaTeX\ text
over a \PS\ diagram.

\subsection{Colour}

\begin{filedesc}
\item[color] Produce coloured effects in your document. The
\verb|\color{red}| declaration would make all the following text red,
the similar \verb|\textcolor| command takes an extra argument that
specifies the text to be coloured (by analogy with \verb|\rmfamily|
and \verb|\textrm|).

One may also produce boxes with coloured backgrounds using the
\verb|\colorbox| command.

Accurate treatment of colour is probably the feature that requires the
most `help' from the driver program. If your driver was not
specifically  written to support colour then probably the
\package{color} package will not work at all, or will be limited to
regions of colour that fall on one page, and all the current colours
will be `forgotten' at a page break.

\item[pstcol] The
\package{pstricks} package of Tim~van~Zandt provides a very powerful
interface to \PS. Unfortunately the package has some slight
incompatibilities with the \package{color} package. If a document
loads  \package{pstcol}, both \package{color} and
\package{pstricks} are loaded, and then a few internal
\package{pstricks} functions are redefined to repair the
incompatibility.
\end{filedesc}

\subsection{Rotation, Scaling and  Graphics Inclusion}
\begin{filedesc}
\item[graphics] This is the core \LaTeX\ package for
rotation
(\verb|\rotatebox|), scaling (\verb|\scalebox| and
\verb|\resizebox|) of text, and the inclusion of graphics images
(\verb|\includegraphics|). Unlike the old \LaTeX\,2.09 packages such
as \package{psfig} the \verb|\includegraphics| command is not
restricted to \PS\ graphics, but can include any graphics formats that
your driver supports.
\item[graphicx] Often when including graphics files one needs to
specify combinations of scaling and rotation and other special
effects. The \package{graphics} package uses standard \LaTeX\
`positional' optional arguments which means that it is not practical
for any command to support more than a couple of optional arguments.
The \package{graphicx} package calls the \package{graphics} package
internally, but offers a more powerful and friendly `named argument'
interface in which an arbitrary number of optional keys may be set in
one \verb|[ ]| argument. For instance to include a graphic scaled to
half size, and rotated through 90$^\circ$, one can specify
\begin{smallv}
\begin{verbatim}
\includegraphics[scale=.5, angle=90]{file}
\end{verbatim}
\end{smallv}
To do the equivalent with the \package{graphics} package would require
nested calls of \verb|\includegraphics| inside \verb|\scalebox| inside
\verb|\rotatebox|.

\item[lscape] Provides a \env{landscape} environment within which the
body of every page is rotated through 90$^\circ$. The page head and
foot are not rotated, but stay in their usual positions. It requires the
\package{graphics} package which is used to handle the rotation.
\item[epsfig] The obsolete \LaTeX\,2.09 did not come with a standard
graphics package. Two popular contributed packages to include \PS\
graphics were \package{psfig} (T.~Darrell) and \package{epsf}
(T.~Rokicki). Sebastian Rahtz merged and extended these to produce the
package \package{epsfig}. The \package{epsfig} package became very
popular, especially after it was given extensive coverage in \emph{The
\LaTeX\ Companion}. For this reason the current distribution contains
a package called  \package{epsfig} so that old documents do not
need converting to the new system. However this  \package{epsfig} is
just a wrapper that converts the old syntax into calls to the new
\verb|\includegraphics| command and so should not now be used for new
documents.
\end{filedesc}

\subsection{Driver Files}

As mentioned above, these packages all require customisation to a
particular driver. This may be specified either in a site
configuration file, or 
as a package option in the document. The code for these drivers is all
stored in `\texttt{.def}' files, so for instance the code for the
\emph{dvips} driver (and also for \emph{xdvi} which uses the same
\verb|\special| syntax) is stored in \File|dvips.def|. All these
driver files are 
derived from the same source, \File|drivers.dtx|, except for the
Textures file which is currently distributed as a separate
\File|textures.def| contributed by Arthur Ogawa. One special
\texttt{.def} file does not correspond to a driver,
\File|dvipsnam.def| predefines the 60$+$ colours that are `known' to
the \emph{dvips} driver. It may be used with other drivers as well, as
described in the \package{color} package documentation.

\subsection{Other Graphics Packages}

The remaining two packages do not have code that is specific to dvi
driver programs, and so in some sense do not really belong in the
\package{graphics} distribution; they are used by the
\package{graphics} and \package{graphicx} packages. In fact the code
of either of these packages may be extracted and used in any format
based on plain \TeX. They do not use any \LaTeX\ specific features.
\begin{filedesc}
\item[keyval] The \package{graphicx} package makes use of a `named
argument' or `key equals value' syntax as described above.
\package{Keyval} provides a general parser for such a syntax, so this
package is unlikely to be directly called within a document, but may
be loaded by \verb|\RequirePackage| by any package or class file that
needs to define commands with such a syntax.
\item[trig] This package provides functions for calculating the
trigonometric functions sin, cos and tan. These are used by the
\package{graphics} package for determining the amount of space a
rotated box will take up.
\end{filedesc}

\section{Coming Soon}
Part~3 of this tour will describe the files of Johannes Braams'
\package{babel} distribution of packages for multi-lingual
typesetting, the \package{psnfss} distribution of  
\PS\ font related packages, and \package{mfnfss} distribution of
packages for loading `Pandora' and `Old German'  fonts.
\end{Article}