guess we don't want the build dir

[latex2e.git] / trunk / required / graphics / grfguide.tex

%% grfguide.tex Copyright (C) 1994 1995 1996 1998 1999 David Carlisle
%%              Copyright (C) 2005 2014 2016 2017 David Carlisle, LaTeX3 Project
%%
%% This file is part of the Standard LaTeX `Graphics Bundle'.
%% It may be distributed under the terms of the LaTeX Project Public
%% License, as described in lppl.txt in the base LaTeX distribution.
%% Either version 1.3c or, at your option, any later version.
%%
%% This file has the LPPL maintenance status "maintained".

\begin{filecontents*}{a.ps}
%!
%%BoundingBox:0 0 72 72
0 0 moveto
72 72 rlineto
72 neg 0 rlineto
72 72 neg rlineto
stroke
0 0 moveto
/Times-Roman findfont
72 scalefont
setfont
(A) show
showpage
\end{filecontents*}
\begin{filecontents*}{a.pdf}
%PDF-1.4
%%%%%
1 0  obj
<<
/Pages 2 0 R
/Type /Catalog
>>
 endobj
2 0  obj
<<
/Kids [3 0 R]
/Type /Pages
/Count 1
>>
 endobj
3 0  obj
<<
/Rotate 0
/Parent 2 0 R
/MediaBox [0 0 72 72]
 /Resources
<<
/ExtGState 4 0 R
/Font 5 0 R
/ProcSet [/PDF /Text]
>>
/pdftk_PageNum 1
/Type /Page
/Contents 6 0 R
>>
 endobj
4 0  obj
<<
/R7 7 0 R
>>
 endobj
5 0  obj
<<
/R8 8 0 R
>>
 endobj
6 0  obj
<<
/Length 135
>>
stream
q 0.1 0 0 0.1 0 0 cm
/R7 gs
10 w
0 G
0 0 m
720 720 l
0 720 l
720 0 l
S
0 g
q
10 0 0 10 0 0 cm BT
/R8 72 Tf
1 0 0 1 0 0 Tm
(A)Tj
ET
Q
Q

 endstream
 endobj
7 0  obj
<<
/Type /ExtGState
/OPM 1
>>
 endobj
8 0  obj
<<
/BaseFont /Times-Roman
/LastChar 65
/Subtype /Type1
/FontDescriptor 9 0 R
/Widths [722]
/Type /Font
/Encoding /WinAnsiEncoding
/FirstChar 65
>>
 endobj
9 0  obj
<<
/FontName /Times-Roman
/StemV 105
/CharSet (/A)
/Ascent 674
/Flags 65568
/Descent 0
/ItalicAngle 0
/MissingWidth 250
/FontBBox [0 0 706 674]
/Type /FontDescriptor
/CapHeight 674
>>
 endobj
10 0  obj
<<
/Producer (GPL Ghostscript 9.06)
/ModDate (D:20140426202438+01'00')
/CreationDate (D:20140426202438+01'00')
>>
endobj xref
0 11
0000000000 65535  f
0000000015 00000  n
0000000066 00000  n
0000000125 00000  n
0000000308 00000  n
0000000341 00000  n
0000000374 00000  n
0000000563 00000  n
0000000610 00000  n
0000000774 00000  n
0000000975 00000  n
trailer

<<
/Info 10 0 R
/Root 1 0 R
/Size 11
/ID [<4ca1370d594acd28b9d948a5e8b925c3> <4ca1370d594acd28b9d948a5e8b925c3>]
>>
startxref
1106
%%EOF
\end{filecontents*}
\documentclass{ltxguide}

%%% No driver option specified
%%% set up the files color.cfg and graphics.cfg for your site.
%%% for example:
%%%
%%% \ExecuteOptions{dvips}
%%%
\usepackage{color,graphicx,shortvrb}

%% Just as an example, and to make sure, in case some
%% driver option has not declared a default rule for
%% .ps files:
%\DeclareGraphicsRule{.ps}{eps}{.ps}{}
%\DeclareGraphicsExtensions{.pdf,.ps}
%% Which means:
%% .ps files are (to be treated as) EncapsulatedPostScript
%% files. The .ps file is to be read for the BoundingBox.
%% No `special' commands need to be applied by the driver.


\renewcommand\star{{\ttfamily*}}

\let\package\textsf

\newlength{\gxlen}
\settowidth{\gxlen}{\package{graphicx}: }
\newcommand\gs{\makebox[\gxlen][l]{\package{graphics}:}}
\newcommand\gx{\makebox[\gxlen][l]{\package{graphicx}:}}

\MakeShortVerb{\|}

\begin{document}
\title{Packages in the `graphics' bundle}
\author{D. P. Carlisle \and The \LaTeX3 Project}
\date{2017-06-01}

\maketitle

\tableofcontents

\section{Introduction}
This document serves as a user-manual for the packages \package{color},
\package{graphics}, and \package{graphicx}. Further documentation may be
obtained by processing the  source (|dtx|) files of the individual
packages.

\section{Driver support}\label{drivers}
All these packages rely on features that are not in \TeX\ itself.
These features must be supplied by the `driver' used to print the
|dvi| file. Unfortunately not all drivers support the same features, and
even the internal method of accessing these extensions varies between
drivers. Consequently all these packages take options such as
`|dvips|' to specify which driver is being used.

Normally you should \emph{not} specify the driver option explicitly
in the document, but allow it to be defaulted automatically.
This allows the document to be portable between different systems.

Your \TeX\ distribution should have included |graphics.cfg| and
|color.cfg| configuration files to specify these defaults.
Standard versions of the configuration files are maintained by the
\LaTeX\ Project and distributed in the CTAN |graphics-cfg| collection.

For special requirements you may edit a copy of these |cfg| files
to set up a site default for these options. Suppose that you wish
the \package{color} package to always default to use specials for the
PostScript driver, |dvisvgm|. In that case, create a file |color.cfg|
containing the line:\\
|\ExecuteOptions{dvisvgm}|\\
Normally you will want an identical file |graphics.cfg| to set a similar
default for the graphics packages.

The following driver options are declared in the packages.
The matching definition files (\emph{driver}|.def|)
are now also maintained by the \LaTeX\ project,
but distributed separately, in the CTAN |graphics-def| collection.
\begin{quote}\raggedright
  |dvipdfmx|, |dvips|, |dvisvgm|, |luatex|, |pdftex|, |xetex|
\end{quote}


The following two options are also supported, they do not correspond
to separate definition files, but are essentially aliases for the
|dvips| option (and |monochrome| in the case of |xdvi|).
\begin{quote}\raggedright
 |xdvi|,  |oztex|
\end{quote}

The following set of options are supported by these packages
with associated driver files extracted from the |drivers.dtx|
documented source in this bundle. These are now, mainly of historic
interest but the documented sources do contain some useful code
and advice if you need to produce a new definition file for a new
driver or \TeX\ system. |drivers.dtx| also contains documented
sources for older driver files that are no longer extracted.
\begin{quote}\raggedright
 |dvipdf|, |dvipdfm|, |dviwin|, |dvipsone|,
 |emtex|, |pctexps|, |pctexwin|,  |pctexhp|, |pctex32|,
 |truetex|, |tcidvi|, |vtex|
\end{quote}

The final driver option is an alias for |dvipsone|.
\begin{quote}\raggedright
  |dviwindo|
\end{quote}
  

\section[Colour]{Colour\footnote{%
The basic \package{color} package functionality described here
will be enough for many uses, however a much extended version
is available in the contributed \package{xcolor} package, distributed
and maintained separately. All the color commands described here are
also available if you specify \package{xcolor} in your document.}%
}
The colour support is built around the idea of a system of
\emph{Colour Models}. The Colour models supported by a driver vary,
but typically include
\begin{description}
\item[rgb] Red Green Blue: A comma separated list of three numbers
  between~0 and~1, giving the components of the colour.
\item[cmyk] Cyan Magenta Yellow [K]Black:  A comma separated list of
  four numbers between~0 and~1, giving the components of the colour
  according to the additive model used in most printers.
\item[gray] Grey scale: a single number between~0 and~1.
\item[named] Colours accessed by name, e.g.\ `JungleGreen'. Not all
  drivers support this model. The names must either be `known' to the
  driver or added using commands described in |color.dtx|. Some drivers
  support an extended form of the named model in which an `intensity' of
  the colour may also be specified, so `\mbox{JungleGreen, 0.5}' would
  denote that colour at half strength.
\end{description}
Note that the \textbf{named} model is really just given as an example
of a colour model that takes names rather than a numeric specification.
Other options may be provided locally that provide different colour
models, eg \textbf{pantone} (An industry standard set of colours),
\textbf{x11} (Colour names from the X Window System), etc. The
standard distribution does not currently have such models, but the
\textbf{named} model could be used as an example of how to define a new
colour model. The names used in the \textbf{named} model are those 
suggested by Jim Hafner in his \textsf{colordvi} and \textsf{foiltex}
packages, and implemented originally in the |color.pro| header file for
the \texttt{dvips} driver.

\subsection{Package Options}
Most of the options to the \package{color} package just specify a
driver, e.g., \ |dvips|, as discussed in section~\ref{drivers}.

One special option for the \package{color} package 
that is of interest is |monochrome.|
If this option is selected the colour commands are all
disabled so that they do not generate errors, but do not generate colour
either. This is useful if previewing with a previewer that can not
produce colour.

Three other package options control the use of the \textbf{named} model.
The |dvips| driver (by default) pre-defines 68 colour names. The |dvips|
option normally makes these names available in the \textbf{named} colour
model. If you do not want these names to be declared in  this model
(Saving \TeX\ some memory) you may give the |nodvipsnames|
option. Conversely, if you are using another driver, you may wish to
add these names to the named model for that driver (especially if you
are processing a document originally produced on |dvips|). In this case
you could use the |dvipsnames| option. Lastly the |usenames| option
makes all names in the \textbf{named} model directly available, as
described below.

\subsection{Defining Colours}

The colours |black|, |white|, |red|, |green|, |blue|, |cyan|,
|magenta|, |yellow| should be predefined, but should you wish to mix
your own colours use the |\definecolor| command.

\begin{decl}
|\definecolor|\arg{name}\arg{model}\arg{colour specification}
\end{decl}


This defines \m{name} as a colour which can be used in later colour
commands. For example
\begin{verbatim}
\definecolor{light-blue}{rgb}{0.8,0.85,1}
\definecolor{mygrey}{gray}{0.75}
\end{verbatim}
\definecolor{light-blue}{rgb}{0.8,0.85,1}
\definecolor{mygrey}{gray}{0.75}

Now |light-blue| and |mygrey| may be used in addition to the
predefined colours above.

\subsection{Using Colours}

\subsubsection{Using predefined colours}
The syntax for colour changes is designed to mimic font changes.
The basic syntax is:

\begin{decl}
|\color|\arg{name}
\end{decl}

This is a \emph{declaration}, like |\bfseries| It changes the current
colour to \m{name} until the end of the current group or
environment.

An alternative command syntax is to use a \emph{command} form that
takes the text to be coloured as an \emph{argument}. This is similar
to the font commands such as |\textbf|:

\begin{decl}
|\textcolor|\arg{name}\arg{text}
\end{decl}


So the above is essentially equivalent to
|{\color|\arg{name}\emph{text}|}|.

\subsubsection{Using colour specifications directly}


\begin{decl}
|\color|\oarg{model}\arg{specification}\\
|\textcolor|\oarg{model}\arg{specification}\arg{text}
\end{decl}

Normally one would predeclare all the colours used in a package, or in
the document preamble, but sometimes it is convenient to directly use
a colour without naming it first. To achieve this |\color| (and all
the other colour commands) take an optional argument specifying the
model. If this is used then the mandatory argument takes a
\m{colour specification} instead of a \m{name}. For example:\\
|\color[rgb]{1,0.2,0.3}|\\
would directly select that colour.

This is particularly useful for accessing the \textbf{named} model:\\
|\color[named]{BrickRed}| selects the |dvips| colour BrickRed.

Rather than repeatedly use |[named]| you may use |\definecolor| to
provide convenient aliases:\\
|\definecolor{myred}{named}{WildStrawberry}|
     \ldots\ |\color{myred}|\ \ldots

Alternatively if you are happy to use the existing names from the
\textbf{named} model, you may use the |usenames| package option, which
effectively calls |\definecolor| on every colour in the \textbf{named}
model, thus allowing |\color{WildStrawberry}| in addition to
|\color[named]{WildStrawbery}|.

\subsection{Named Colours}
Using the \textbf{named} colour model has certain advantages over
using other colour models. 

Firstly as the |dvi| file contains a request
for a colour by \emph{name}, the actual mix of primary colours used to
obtain the requested colour can be tuned to the characteristics of a
particular printer. In the |dvips| driver the meanings of the colour
names are defined in the header file |color.pro|. Users are encouraged
to produce different versions of this file for any printers they use. By
this means the same dvi file should produce colours of similar
appearance when printed on printers with different colour
characteristics.

Secondly, apart from the so called `process colours' that are produced
by mixing primary colours during the print process, one may want to use
`spot' or `custom' colours. Here a particular colour name does not
refer to a mix of primaries, but to a particular ink. The parts of the
document using this colour will be printed separately using this named
ink colour.

\subsection{Page Colour}


\begin{decl}
|\pagecolor|\arg{name}\\
|\pagecolor|\oarg{model}\arg{specification}\\
|\nopagecolor|
\end{decl}

The background colour of the whole page can be set using
|\pagecolor|. This takes the same argument forms as |\color| but sets
the background colour for the current and all subsequent pages. It is
a global declaration, so you need to  use
|\nopagecolor|\NEWfeature{2014/04/23}\ to `get back to normal'.
If that is not supported, you may use |\pagecolor{white}| although that
will make a white background rather than the default transparent background.

\subsection{Box Backgrounds}
Two commands similar to |\fbox| produce boxes with the backgrounds
shaded an appropriate colour.

\begin{decl}
|\colorbox|\arg{name}\arg{text}\\
|\colorbox|\oarg{model}\arg{specification}\arg{text}\\
|\fcolorbox|\arg{name1}\arg{name2}\arg{text}\\
|\fcolorbox|\oarg{model}%
            \arg{specification1}\arg{specification2}\arg{text}
\end{decl}


The former produces a box coloured with \emph{name}
\colorbox{mygrey}{like this}. The latter is similar but puts a frame of
colour \emph{name1} around the box coloured \emph{name2}.

These commands use the |\fbox| parameters |\fboxrule| and |\fboxsep|
to determine the thickness of the rule, and the size of the shaded area.

\subsection{Possible Problems}

\TeX\ was not designed with colour in mind, and producing colours
requires a lot of help from the driver program. Thus, depending on the
driver, some or all features of the \package{color} package may not be
available.

Some drivers do not maintain a special `colour stack'. These drivers are
likely to get confused if you nest colour changes, or use colours in
floating environments.

Some drivers do not maintain colours over a page break, so that if the
page breaks in the middle of a coloured paragraph, the last part of the
text will incorrectly be printed in black.

There is a different type of problem that will occur for all drivers.
Due to certain technical difficulties\footnote{At least two causes:
1) The presence of a \texttt{\char`\\special} \m{whatsit} prevents
\texttt{\char`\\addvspace} `seeing' space on the current vertical list,
so causing it to incorrectly add extra vertical space. 2) A
\m{whatsit} as the first item in a \texttt{\char`\\vtop} moves the
reference point of the box.}%
, it is possible that at points
where the colour changes, the \emph{spacing} is affected. For this
reason the |monochrome| option does not completely disable the colour
commands, it redefines them to write to the log file. This will have the
same effects on spacing, so you can produce monochrome drafts of your
document, at least knowing that the final spacing is being shown.
\section{The Graphics packages}
There are two graphics packages:
\begin{description}
\item[\package{graphics}] The `standard' graphics package.
\item[\package{graphicx}] The `extended' or `enhanced' graphics
  package. 
\end{description}
The two differ only in the format of optional arguments for the
commands defined. The command names, and the mandatory arguments are
the same for the two packages.

\subsection{Package Options}
As discussed in section~\ref{drivers}, the graphics packages share the
same `driver' options as the \package{color} package. As for colour
you should set up a site-default in a file,
|graphics.cfg|, containing the line (for |dvips|):\\
|\ExecuteOptions{dvips}|

The graphics packages have some other options for controlling how many
of the features to enable:
\begin{description}
\item[draft] suppress all the `special' features. In particular
  graphics files are not included (but they are still read for size
  info) just the filename is printed in a box of the correct size.
\item[final] The opposite of |draft|. Useful to over-ride a global
  |draft| option specified in the |\documentclass| command.
\item[hiderotate] Do not show rotated text (presumably because the
  previewer can not rotate).
\item[hidescale] Do not show scaled text (presumably because the
  previewer can not scale).
\item[hiresbb] Look for size specifications in |%%HiResBoundingBox|
  lines rather than standard |%%BoundingBox| lines.%
  \NEWfeature{1996/10/29}
\item[demo] Instead of inserting an image file |\includegraphics|
  draws a 150\,pt by 100\,pt rectangle unless other dimensions are
  specified manually.\NEWfeature{2006/02/20}
\end{description}
\subsection{Rotation}

\begin{decl}
\gs |\rotatebox|\arg{angle}\arg{text}\\
\gx |\rotatebox|\oarg{key val list}\arg{angle}\arg{text}
\end{decl}

This puts \emph{text} in a box, like |\mbox|, but rotates the box
through \emph{angle} degrees, \rotatebox{15}{like this}.

The standard version always rotates around the reference point of the
box, but the \package{keyval} version takes the following keys:

\begin{decl}
|origin|=\m{label}\\
|x|=\m{dimen}\\
|y|=\m{dimen}\\
|units|=\m{number}
\end{decl}

So you may specify both |x| and |y|, which give the coordinate of
the centre of rotation relative to the reference point of the box, eg
|[x=2mm, y=5mm]|. Alternatively, for the most common points, one may use
|origin| with a \emph{label} containing one or two of the following:
|lrctbB| (|B| denotes the baseline, as for \package{PSTricks}). For
example, compare a default rotation of $180^\circ$
\ldots\rotatebox{180}{Like This}\ldots\ to the effects gained by using
the |origin| key:\\
|[origin = c]| rotates about the centre of the box,\ldots
         \rotatebox[origin=c]{180}{Like This}\ldots\\
|[origin = tr]| rotates about the top right hand corner\ldots
                   \rotatebox[origin=tr]{180}{Like This}\ldots

The |units| key allows a change from the default units of degrees
anti-clockwise. Give the number of units in one full anti-clockwise
rotation. For example:\\
|[units = -360]| specifies degrees clockwise.\\
|[units= 6.283185]| specifies radians.

\subsection{Scaling}

\subsubsection{Scaling by scale factor}

\begin{decl}
|\scalebox|\arg{h-scale}\oarg{v-scale}\arg{text}
\end{decl}

Again this is basically like |\mbox| but scales the \emph{text}.
If \emph{v-scale} is not specified it defaults to \emph{h-scale}.
If it is specified the text is distorted as the horizontal and
vertical stretches are different, \scalebox{3}[.7]{Like This}.


\begin{decl}
|\reflectbox|\arg{text}
\end{decl}

An abbreviation for |\scalebox{-1}[1]|\arg{text}.

\subsubsection{Scaling to a requested size}

\begin{decl}
|\resizebox|\star\arg{h-length}\arg{v-length}\arg{text}
\end{decl}

 Scale \emph{text} so that the width is \emph{h-length}.
 If |!| 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
 star form, it refers to the `height +  depth'. 
 As normal for \LaTeXe\ box length arguments, |\height|,
 |\width|, |\totalheight|, |\depth| may be used to refer to the
 original size of the box.

|\resizebox{1in}{\height}{Some text}|: 
\resizebox{1in}{\height}{Some text}

|\resizebox{1in}{!}{Some text}|: 
\resizebox{1in}{!}{Some text}

\subsection{Including Graphics Files}
The functions for graphics inclusion try to give the same user syntax
for including any kind of graphics file that can be understood by the
driver. This relies on the file having an extension that identifies
the file type. The `driver options' will define a collection of file
extensions that the driver can handle, although this list may be
extended using the declarations described below.

If the file's extension is unknown to the driver, the system may try a
default file type. The PostScript driver files set this default to be
|eps| (PostScript), but this behaviour may be customised if other
defaults are required.

\begin{decl}
\gs |\includegraphics|\star\oarg{llx,lly}\oarg{urx,ury}\arg{file}\\
\gx |\includegraphics|\star\oarg{key val list}\arg{file}
\end{decl}
 Include a graphics 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 an external file as described below.

\paragraph{\package{graphics} version}
 If \oarg{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 omitted 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
 \oarg{llx,lly} may be used to specify the coordinates of this point.

\paragraph{\package{graphicx} version}
Here the star form is just for compatibility with the standard
version. It just adds |clip| to the list of keys specified.
(Also, for increased compatibility, if \emph{two} optional arguments are
used, the `standard' version of |\includegraphics| is always used, even
if the \package{graphicx} package is loaded.)

The allowed keys are listed below.
\begin{description}
\item[bb] The argument should be four dimensions, separated by spaces.
  These denote the `Bounding Box' of the printed region within
  the file.
\item[bbllx,bblly,bburx,bbury] Set the bounding box. Mainly for
 compatibility with older packages.
 Specifying |bbllx=a,bblly=b,bburx=c,bbury=d|
 is equivalent to specifying |bb = a b c d|.
\item[natwidth,natheight] Again an alternative to |bb|. 
 |natheight=h,natwidth=w| is equivalent to |bb = 0 0 h w|.
\item[hiresbb]\NEWfeature{1996/10/29}
 Boolean valued key. If set to |true| (just specifying |hiresbb|
 is equivalent to |hiresbb=true|) then \TeX\ will look for
 |%%HiResBoundingBox| lines rather than |%%BoundingBox|. It may be set
 to |false| to overrule a default setting of |true| set by the
 |hiresbb| package option.
\item[pagebox]\NEWfeature{2017/06/01}
PDF files do not have BoundingBox but may specify up to four predefined
rectangles.

|MediaBox|: the boundaries of the physical medium.
|CropBox|: the region to which the contents of the page are to be
  clipped when displayed.
|BleedBox|: the region to which the contents of the
 page should be clipped in production.
|TrimBox|: the intended dimensions of the finished page.
|ArtBox|: the extent of the page's meaningful content.

The driver will set the image size based on |CropBox| if present,
otherwise it will not use one of the others,
with a driver-defined order of preference.
|MediaBox| is always present.

The |pagebox| key may be used to specify which bounding box specification to use,
The value should be one of
|mediabox|, |cropbox|, |bleedbox|, |trimbox|, |artbox|.
\item[viewport]\NEWfeature{1995/06/01}
 The |viewport| key takes four arguments, just like
 |bb|. However in this case the values are taken relative to the
 origin specified by the bounding box in the file. So to `view' the
 1in square in the bottom left hand corner of the area specified by
 the bounding box, use the argument |viewport=0 0 72 72|.
\item[trim]\NEWfeature{1995/06/01}
 Similar to viewport, but here the four lengths specify the
 amount to remove or add to each side. |trim= 1 2 3 4| `crops' the
 picture by 1bp at the left, 2bp at the bottom, 3bp on the right and
 4bp at the top.
\item[angle] Rotation angle.
\item[origin]\NEWfeature{1995/09/28}
 Origin for rotation. See the documentation of |\rotatebox|.
\item[width] Required width. The
  graphic is scaled to this width.
\item[height] Required height. The
  graphic is scaled to this height.
\item[totalheight]\NEWfeature{1995/06/01}
 Specify the total height (height $+$ depth) of the figure.
 This will differ from the `height' if rotation has occurred.
 In particular if the figure has been rotated by $-90^\circ$ 
 then it will have zero height but large depth.
\item[keepaspectratio]\NEWfeature{1995/09/27}
 Boolean valued key like `clip'.
 If set to true then specifying both `width' and `height' (or
 `totalheight') does not distort the figure but scales such that
  neither of the specified dimensions is \emph{exceeded}.
\item[scale] Scale factor.
\item[clip] Either `true' or `false' (or no value, which is equivalent
  to `true'). Clip the graphic to the bounding box.
\item[draft] a boolean valued key, like `clip'. Locally switches to
  draft mode.
\item[type] Specify the graphics type.
\item[ext]  Specify the file extension. This should \emph{only} be
 used in conjunction with |type|.
\item[read] Specify the file extension of the `read file'. This
 should \emph{only} be used in conjunction with |type|. 
\item[command] Specify any command to be applied to the file.  This
 should \emph{only} be used in conjunction with |type|.
\item[quiet]\NEWfeature{2017/06/01}
 Skip writing information to the log.
\item[page]\NEWfeature{2017/06/01}
Page of a multi-page PDF file. (by default the first page will be used.)
\item[interpolate]\NEWfeature{2017/06/01}
Enable/disable interpolation of bitmap images by the viewer.
\end{description}

For the keys specifying the original size (i.e,, the bounding box,
trim and viewport keys) the units can be omitted, in
which case bp (i.e., PostScript points) are assumed.

The first seven keys specify the original size of the image. This size
needs to be specified in the case that the file can not be read by
\TeX, or it contains an incorrect size `BoundingBox' specification.

|bbllx|\ldots\ |\bbury| are mainly for compatibility for older
packages.\\
|bbllx=a, bblly=b, bburx=c, bbury=d|\\
is equivalent to\\
|bb = a b c d|.

|natheight| and |natwidth| are just shorthands for setting the lower
left coordinate to 0 0 and the upper right coordinate to the specified
width and height.

The next few keys specify any scaling or rotation to be applied to the
image. To get these effects using the standard package, the
|\includegraphics| call must be placed inside the argument of a
|\rotatebox| or |\scalebox| command.

The keys are read left-to-right, so |[angle=90, height=1in]| means
rotate by 90 degrees, and then scale to a height of 1in. 
|[height=1in, angle=90]| would result in a final \emph{width} of 1in.

If the \textsf{calc} package is also loaded the lengths may use 
\textsf{calc} syntax, for instance to specify a width of 2\,cm 
less than the text width: |[width=\textwidth-2cm]|.

\TeX\ leaves the space specified either in the file, or in
the optional arguments. If any part of the image is actually outside
this area, it will by default overprint the surrounding text. 
If the star form is used, or |clip| specified, any part of the image
outside this area will not be printed.

The last four keys suppress the parsing of the filename. If they are
used, the main \emph{file} argument should not have the file
extension. They correspond to the arguments of |\DeclareGraphicsRule|
described below.

To see the effect that the various options have consider the file
|a.ps|. This file contains the bounding box specification
\begin{verbatim}
%%BoundingBox:0 0 72 72
\end{verbatim}
That is, the printed region consists of a one-inch square, in
the bottom left hand  corner of the paper.

In all the following examples the input will be of the form
\begin{verbatim}
left---\fbox{\includegraphics{a}}---right
\end{verbatim}
With different options supplied to |\includegraphics|.

No optional argument.\\
left---\fbox{\includegraphics{a}}---right

\gs |\scalebox{0.5}{\includegraphics{a}}|\\
\gx |\includegraphics[scale=.5]{a}|\\
left---\fbox{\includegraphics[scale=.5]{a}}---right

\gs |\includegraphics[15,10][35,45]{a}}|\\
\gx |\includegraphics[viewport= 15 10 35 45]{a}|\\
left---\fbox{\includegraphics[viewport= 15 10 35 45]{a}}---right

\gs |\includegraphics*[15,10][35,45]{a}}|\\
\gx |\includegraphics[viewport= 15 10 35 45,clip]{a}|\\
left---\fbox{\includegraphics[viewport= 15 10 35 45,clip]{a}}---right

\gs |\scalebox{0.5}{\includegraphics{a}}|
                   and |draft| option.\\
\gx |\includegraphics[scale=.5, draft]{a}|\\
left---\fbox{\includegraphics[scale=.5, draft]{a}}---right

\subsection{Other commands in the \package{graphics} package}

\begin{decl}
|\graphicspath|\arg{dir-list}
\end{decl}
This optional declaration may be used to specify a list of directories
in which to search for graphics files. The format is the same as for
the \LaTeXe\ primitive |\input@path|. A list of directories, each in a
|{}| group (even if there is only one in the list). For example:\\
  |\graphicspath{{eps/}{tiff/}}|\\
 would cause the system to look in the subdirectories |eps| and |tiff|
 of the current directory. (All modern \TeX{} systems use |/|
 as the directory separator, even on Windows.)

 The default setting of this path is
 |\input@path| that is: graphics files will be found wherever \TeX\
 files are found.

\begin{decl}
|\DeclareGraphicsExtensions|\arg{ext-list}
\end{decl}
 \NEWdescription{1994/12/01}
 This specifies the behaviour of the system when no file extension
 is specified in the argument to |\includegraphics|.
 \arg{ext-list} should be a comma separated list of file extensions.
 (White space is ignored between the entries.)
 A file name is produced by appending one extension from the list.
 If a file is found, the system acts as if that extension had been
 specified. If not, the next extension in \emph{ext-list} is tried.


Note that if the extension is not specified in the |\includegraphics|
command, the graphics file must exist at the time \LaTeX\ is run, as
the existence of the file is used to determine which extension from
the list to choose. However if a file extension \emph{is} specified,
e.g.\ |\includegraphics{a.ps}| instead of |\includegraphics{a}|, then
the graphics file need not exist at the time \LaTeX\ is used. (In
particular it may be created on the fly by  the \m{command}
specified in the |\DeclareGraphicsRule| command described below.)
\LaTeX\ does however need to be able to determine the size of the
image so this size must be specified in arguments, or the `read file'
must exist at the time \LaTeX\ is used.

\begin{decl}
|\DeclareGraphicsRule|\arg{ext}\arg{type}\arg{read-file}\arg{command}
\end{decl}
 Any number of these declarations can be made. They determine how the
 system behaves when a file with extension \emph{ext} is specified.
 (The extension may be specified explicitly or, if the argument to
 |\includegraphics| does not have an extension, it may be a default
 extension from the \emph{ext-list} specified with 
 |\DeclareGraphicsExtensions|.)
 
\emph{ext} the file extension for which this rule applies. As a special
case, \emph{ext} may be given as |*| to denote the default behaviour for
all undeclared extensions (see the example below).

\emph{type} is the `type' of file involved. All files of the same type
will be input with the same internal command (which must be defined in
a `driver file'). For example files with extensions |ps|, |eps|,
|ps.gz| may all be classed as type |eps|.

\emph{read-file} determines the extension of the file that should be
read to determine size information. It may be the same as \emph{ext}
but it may be different, for example |.ps.gz| files are not readable
easily by \TeX, so you may want to put the bounding box information in
a separate file with extension  |.ps.bb|. If \emph{read-file} is empty,
|{}|, then the system will not try to locate an external file for size
info, and the size must be specified in the arguments of
|\includegraphics|. If the driver file specifies a procedure for
reading size files for \emph{type}, that will be used, otherwise the 
procedure for reading |eps| files will be used. Thus the size of
bitmap files may be specified in a file with a PostScript style
|%%BoundingBox| line, if no other specific format is available.

As a special case |*| may be used to denote the
same extension as the graphic file. This is mainly of use in
conjunction with using |*| as the extension, as in that case the
particular graphic extension is not known. For example
\begin{verbatim}
 \DeclareGraphicsRule{*}{eps}{*}{}
\end{verbatim}
This would declare a default rule, such that all unknown extensions
would be treated as EPS files, and the graphic file would be read for
a BoundingBox comment.

\emph{command} is usually empty, but if non empty it is used in place
of the filename in the |\special|. Within this argument, |#1| may be
used to denote the filename. Thus using the dvips driver, one may
use\\
|\DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{`zcat #1}|\\
the final argument causes dvips to use the |zcat| command to unzip the
file before inserting it into the PostScript output.

Note that \LaTeX\ will find the graphics file by searching along
TEXINPUTS (and possibly other places, as specified with
|\graphicspath|) however it may be that the command you specify
in this argument can not find such files unless they are in the
current directory. On some systems it may be possible to modify
the command so that it will find any files that \LaTeX\ can find.
For example on newer web2c \TeX\ releases on unix, one may modify the
above command so that the last argument is:\\
|{`zcat `kpsewhich -n latex tex #1`}|\\
which incantation causes the |kpsewhich| program to find the
file, by searching along \LaTeX's path, and then pass the full path
name to the |zcat| program so that it can uncompress the file.
Any such uses are very system dependent, and would best be placed in 
a |graphics.cfg| file, thus keeping the document itself portable.

\subsection{Global setting of keys}

Most of the \package{keyval} keys used in the \package{graphicx} package
may also be set using the command |\setkeys| provided by the
\package{keyval} package.%
\footnote{\texttt{clip}, \texttt{scale} and \texttt{angle} may not be set via
\texttt{\string\setkeys} prior to calling
\texttt{\string\includegraphics}.}

For instance, suppose you wanted all the files to be included in the
current document to be scaled to 75\% of the width of the lines of text,
then one could issue the following command:\\
|\setkeys{Gin}{width=0.75\textwidth}|\\
Here `|Gin|' is the name used for the \package{keyval} keys associated
with `Graphics inclusion'. All following
|\includegraphics| commands (within the same group or environment) will
act as if |[width=0.75\textwidth]| had been specified, in addition to
any other key settings actually given in the optional argument.

Similarly to make all |\rotatebox| arguments take an argument in
radians, one just needs to specify:\\
|\setkeys{Grot}{units=6.28318}|

\subsection{Compatibility between \package{graphics} and
  \package{graphicx}}

For a document author, there are not really any problems of
compatibility between the two packages. You just choose the interface
that you personally prefer, and then use the appropriate package.

For a package or class writer the situation is slightly
different. Suppose that you are writing a letter class that needs to
print a company logo as part of the letterhead.

As the author of the class you may want to give the users the
possibility of using  either interface in their letters (should they
need to include any further graphics into the letter body). 
In this case the class should load the \package{graphics} package (not
\package{graphicx}, as this would commit any users of the class to the
\package{keyval} interface). The logo should be included with
|\includegraphics| either with \emph{no} optional argument (if the
correct size information is in the file) or \emph{both} optional
arguments otherwise. 
Do not use the \emph{one} optional argument form, as the meaning of this
argument would change (and generate errors) if the user were to load
\package{graphicx} as well as your class.

\section{Remaining packages in the graphics bundle}

\subsection{Epsfig}
This is a small package essentially a `wrapper' around the
\package{graphicx} package, defining a command |\psfig| which has the
syntax\\
|\psfig{file=xxx,...}| rather than |\includegraphics[...]{xxx}|.\\
It also has a few more commands to make it slightly more compatible with
the old \LaTeX~2.09 style of the same name.

\subsection{Rotating}
An extension package to \package{graphicx}, mainly used for providing
rotated float environments.

\subsection{Trig}
The trig package is not intended to be used directly in documents. It
calculates sine, cosine and tangent trigonometric functions. These
are used to calculate the space taken up by a rotated box. This
package is also used by the |fontinst| program which converts
PostScript files to a form usable by \TeX.

As well as being used as a \LaTeX\ package, the macros may be extracted
with the \package{docstrip} options \texttt{plain,package}. In this case
the \LaTeX\ package declarations are omitted from the file, and the
macros may be directly used as part of another macro file (they work
with any format based on plain \TeX.)

\subsection{Keyval}
The \package{keyval} package is intended to be used by other
packages. It provides a generic way of setting `keys' as used by the
\package{graphicx} package, and splitting up the comma separated lists
of \m{key}~=~\m{value} pairs.

Like the \package{trig} package, these macros may be extracted and used
as part of another macro file, based on plain \TeX, as well as the
standard use as a \LaTeX\ package.

By default an undeclared key will generate an error.
If however the option  \texttt{unknownkeysallowed} is used, then
unknown keys will be silently ignored (leaving a message in the log
file). This option is also accepted by the \textsf{graphicx} package.

\iffalse

\subsection{Pstcol}
\package{PSTricks}, by Timothy Van Zandt is an immensely powerful
package that enables a very full featured interface between PostScript
and \TeX. Unfortunately the colour support in \package{PSTricks} is
slightly incompatible with the colour mechanism defined in the
\package{color} package. The \package{pstcol} package is a (hopefully
temporary) package that modifies a very small number of internal
PSTricks functions, to remove this incompatibility. If
\package{pstricks} is loaded via this package, you may use any colours
defined by \package{color} package commands within \package{pstricks}
commands, and vice versa.

\fi

\subsection{Lscape}
The \package{lscape} package requires and takes the same options
as the \package{graphics} package. It defines a |landscape| environment
within which page bodies are rotated through 90 degrees. The page head
and foot are not affected, they appear in the standard (portrait)
position.
\end{document}