\newenvironment{Show}{\begin{trivlist}\item[]}{\end{trivlist}}
\newcommand{\rcub}{{\ttfamily\upshape\char'175}}
\newcommand{\lcub}{{\ttfamily\upshape\char'173}}
\newcommand\BS{{\ttfamily\upshape\char'134}}
\let\bs\BS
\def\OptArg#1{{\ttfamily[}{\textrm{\emph{#1}}}{\ttfamily]}}
\def\Arg#1{\lcub{\textrm{\emph{#1}}}\rcub}
\def\star{{\ttfamily*}}
\def\PST{\emph{PStricks}}
\def\COMMAND#1{\begin{trivlist}\item[]\tt #1\end{trivlist}}
\title{\LaTeXe\ standard graphics and colour support}
\author[David Carlisle and Sebastian Rahtz]{%
 David Carlisle\\
\texttt{carlisle@cs.man.ac.uk}\\
 Sebastian Rahtz\\
\texttt{spqr@ftp.tex.ac.uk}
}
\begin{Article}
\MakeShortVerb{|}
\section{Introduction}
With the release of \LaTeXe, graphics file inclusion, rotation,
scaling and colour macros are now a standard part of the system
(though implemented as two separate packages).  These are, of course,
dependent on the abilities of the driver in use, as they are all
implemented by using |\special| commands; it is hoped that until (if
ever?) a common |\special| format is agreed upon, the standardized
interface will make life easier for authors.  This article
\emph{briefly} describes the facilities of the new packages, but for
the full glory readers are advised to book for the July training
meeting which covers this area.

Both these packages are now available on CTAN\footnote{Subscribers to
  the Mac or DOS disk packages from \ukt\ will receive copies during
  June with the first full release of \LaTeXe.} in
|macros/latex2e/packages/graphics|, but users are warned that
documentation is incomplete, and that the \emph{internal} interface is
still open to change. Making the packages available is simple; if we
start our document:
\begin{verbatim}
\documentclass[dvips]{article}
\usepackage{graphics}
\usepackage{color}
\end{verbatim}
\noindent we load both packages, and the global option `dvips' is
passed to them, indicating which driver we are using (most common
drivers are supported).

\section{The graphics package}

\subsection{Rotation}
Any \TeX\ box can be rotated with the command
\COMMAND{\bs rotatebox\Arg{angle}\Arg{text}}
\noindent where  \emph{angle} degrees is measured anti-clockwise.
Normally the rotation is about the left-hand end of the baseline of
\emph{text}, but more complex examples are possible. A simple example
of rotation is
\begin{verbatim}
I like \rotatebox{45}{cats} but
I cannot bear \rotatebox{-45}{dogs}
\end{verbatim}
which produces: I like \rotatebox{45}{cats} but
I cannot bear \rotatebox{-45}{dogs}; note that the right amount of
space is left for the rotated material.

\subsection{Scaling}
A box can be resized in two ways, by scale or by specifying the
desired size. The first is achieved with
\COMMAND{\bs scalebox\Arg{h-scale}\OptArg{v-scale}\Arg{text}}
\noindent If \emph{v-scale} is
omitted, the vertical scale factor is the same as the horizontal one.
Thus \verb|\scalebox{2}[.5]{Cats}| produces \scalebox{2}[.5]{Cats}.

Scaling to size is done with
\COMMAND{\bs resizebox\star\Arg{h-length}\Arg{v-length}\Arg{text}}
\noindent which resizes \emph{text} so that the width is
\emph{h-length}.  If |!| (exclamation mark) is used as either length
argument, the other argument is used to determine a scale factor that
is used in both directions.  Normally \emph{v-length} refers to the
height of the box, but in the starred form, it refers to the `height +
depth'.  As normal in \LaTeXe, box length arguments, |\height|,
|\width|, |\totalheight|, |\depth| may be used to refer to the
original size of the box. The cats can be resized again using
\verb|\resizebox{1in}{0.2in}{Cats}| to produce
\resizebox{1in}{0.2in}{Cats}. 

The user should be aware that these scaling operations are done by the
\emph{driver}, and it is likely that bitmap fonts will be scaled,
instead of a new size being selected from scratch.

\subsection{Graphics inclusion}
The basic command to include a graphics file is:
\COMMAND{\bs includegraphics\star\OptArg{llx,lly}\OptArg{urx,ury}\Arg{file}}
If \star\ is present, then the graphic is `clipped' to the size
specified. If \star\ is omitted, then any part  of the graphic that is
outside the specified `bounding box' will  over-print the surrounding
text.

If the optional arguments are omitted, then the size of the graphic
will be determined by reading the graphic file itself, if possible.
If \OptArg{urx,ury} is present, then it should specify the coordinates
of the top right corner of the image, as a pair of \TeX\ dimensions.
If the units are ommited they default to |bp|. So |[1in,1in]| and
|[72,72]| are equivalent. If only one optional argument appears, the
lower left corner of the image is assumed to be at |[0,0]|. Otherwise
\OptArg{llx,lly} may be used to specify the cordinates of this point.

The package works by examining the suffix of the file name and looking
that up in a rule-table, which tells it whether or not the file can be
read for a size, how to do so, and what driver-specific macro to call
for the type of file. This allows extensible support for whatever
bitmap or vector graphic file types the driver can work with. The
interested reader should consult the documentation for the interface
to this system.

A combination of features in the graphics package allows us to rotate
a scaled portion of a figure:
\begin{verbatim}
\rotatebox{45}{%
  \resizebox{1.5cm}{4cm}{%
  \includegraphics*%
    [100,100][500,600]{%
    golfer.ps}%
  }%
}
\end{verbatim}
\noindent which produces \rotatebox{45}{%
  \resizebox{1.5cm}{4cm}{%
  \includegraphics[bbllx=100,bblly=100,bburx=500,bbury=600,clip]{%
    golfer}%
  }%
}

Those users familiar with the \emph{(e)psfig} package can use an
extended form of the graphics package (provisionally entitled
\texttt{graphicx}) which offers a full `key=value' interface to all
the commands described above, using the generic \texttt{keyval} parser
by David Carlisle described elsewhere in this issue of \BV. A small
wrapper package (\texttt{epsfig}) provides an exact emulation of
\texttt{psfig} (and Rokicki's \texttt{epsf} macros) for those with
existing documents marked up in this way.

\section{The colour package}
The \LaTeXe\ colour support offers a variety of facilities:
\begin{itemize}
\item colouring text;
\item colouring box backgrounds;
\item setting the page colour;
\item defining new colour names
\end{itemize}

\subsection{Using colours}
There are two text colouring commands, which work in the same was as the normal
font-changing macros. The first one is a \emph{command}:
 
\COMMAND{\bs 
 textcolor\lcub\textit{<colourname>}\rcub\lcub\textit{<text>}\rcub}
 
\noindent This takes an argument enclosed in brackets and writes it in
the selected colour.  This can be used for local colour
changes, since it restores the original colour state when it is
completed, \eg
 
\begin{verbatim}
This will be in black 
\textcolor{Blue}{This text will be in blue}
and this reverts to black
\end{verbatim}
 
\noindent The second colour macro is a \emph{declaration}:
 
\COMMAND{\bs{}color\lcub\textit{<colourname>}\rcub}
 
\noindent This colour macro takes only one argument and simply sets a
new colour at this point, \eg
 
\begin{verbatim}
\color{red} All the following text
         will be red.
\color{black} Set the text colour
         to black again.
\end{verbatim}
 
The colour declaration does of course respect normal \TeX\ grouping;
if we write
\begin{verbatim}
We start in black, but now
{\color{red} all text 
is in red, {\color{green} but this
should be in green} and this
should be back in red.}
And we finish in black 
\end{verbatim}
we will see\footnote{The examples of colour like this will
be set using gray scales.}
\begin{Show}
We start in black, but now
{\color{red} all text 
is in red, {\color{green} but this
should be in green} and this
should be back in red.}
And we finish in black 
\end{Show}
The \emph{background} of a  normal LR \TeX\ box can also be coloured:
\COMMAND{\bs{}colorbox\lcub\textit{<colourname>}\rcub\lcub\textit{<text>}\rcub}
\noindent This takes the same argument forms as |\textcolor|, but the
colour specifies the background colour of the box. 

There is an extended form:
\COMMAND{\bs{}fcolorbox\lcub\textit{<colourname>}\rcub\lcub\textit{<colourname>}\rcub\lcub\textit{<text>}\rcub}
\noindent This has an extra \emph{colourname} argument, and puts a
frame of the first colour around a box with a background specified by
the second colour. 

The line width and the offset of the frame from the text are controlled
by the standard |\fboxsep| and |\fboxrule| lengths.

\TeX\ does not have internal support for colour attributes of text,
and \TeX\ `grouping' across pages, floats, footnotes etc will not
always yield the expected results.  However, \LaTeXe\ has extended
support to cope with most situations, and it is hoped that more driver
support will make this even better.

\subsection{Defining new colours}
The colour names `white', `black', `red', `green', `blue', `cyan',
`magenta' and `yellow' are predefined by all driver files. New colour
names can be defined with:
\COMMAND{\bs{}definecolor\lcub\textit{<name>}\rcub\lcub\textit{<model>}\rcub\lcub\textit{<spec>}\rcub}
\noindent where \emph{spec} is usually a list of comma-separated numbers needed
by the \emph{model}. Typically, drivers can cope with the models
\emph{gray}, \emph{rgb} and \emph{cmyk} (although the system is
extensible), allowing, \eg:
\begin{verbatim}
\definecolor{lightgrey}{gray}{.25}
\definecolor{cornflowerblue}{rgb}{.39,.58,.93}
\definecolor{GreenYellow}{cmyk}{0.15,0,0.69,0}
\end{verbatim}
It is also possible to use the |\textcolor| and |\color| macros with
an explicit colour model and specifications, to avoid the overhead of
defining new colors.

One of the important concepts inherited from James Hafner's |colordvi|
macros is the allowance for a layer of colour `names' above the actual
specification given to the printer; Hafner worked out a set of 68 CMYK
colours which correspond to a common set of Crayola crayons;  these
are predefined in the header files used by \emph{dvips}, and the user
calls them \emph{by name}, allowing for tuning of the header files for
a particular printer without changing the source. This system is
provided by the \LaTeXe\ colour package for those drivers which
support it, and its use is strongly recommended.
\end{Article}
\endinput