summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/graphics/grfguide.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/graphics/grfguide.tex')
-rw-r--r--Master/texmf-dist/doc/latex/graphics/grfguide.tex848
1 files changed, 0 insertions, 848 deletions
diff --git a/Master/texmf-dist/doc/latex/graphics/grfguide.tex b/Master/texmf-dist/doc/latex/graphics/grfguide.tex
deleted file mode 100644
index 72379e5c4fe..00000000000
--- a/Master/texmf-dist/doc/latex/graphics/grfguide.tex
+++ /dev/null
@@ -1,848 +0,0 @@
-%% grfguide.tex Copyright (C) 1994 1995 1996 1998 1999 David Carlisle
-%%
-%% 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.0 or, at your option, any later version.
-%%
-
-\begin{filecontents*}{a.ps}
-%!
-%%BoundingBox:100 100 172 172
-100 100 moveto
-72 72 rlineto
-72 neg 0 rlineto
-72 72 neg rlineto
-stroke
-100 100 moveto
-/Times-Roman findfont
-72 scalefont
-setfont
-(A) show
-showpage
-\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{.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}
-\date{1999/01/13}
-
-\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.
-
-You should to set up a site default for these
-options, for the driver that you normally use. Suppose that you wish for
-the \package{color} package to always default to use specials for the
-PostScript driver, |dvipsone|. In that case create a file |color.cfg|
-containing the line:\\
-|\ExecuteOptions{dvipsone}|\\
-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.
-\begin{quote}\raggedright
- |dvips|, |xdvi|, |dvipdf|, |dvipdfm|, |pdftex|,
- |dvipsone|, |dviwindo|, |emtex|, |dviwin|,
- |pctexps|, |pctexwin|, |pctexhp|, |pctex32|,
- |truetex|, |tcidvi|, |vtex|,
- |oztex|, |textures|
-\end{quote}
-
-If you use a driver that is not in the list above you may add an option
-for that driver by putting the appropriate |\DeclareOption| line into
-|graphics.cfg| and |color.cfg|, before making it the default option
-with |\ExecuteOptions|, as described above.
-
-For example to add the option `|dvi2ps|' for the original Unix dvi to
-ps driver, and to make that the default, you just need configuration
-files looking like:
-\begin{verbatim}
-\DeclareOption{dvi2ps}{\def\Gin@driver{dvi2ps.def}}
-\ExecuteOptions{dvi2ps}
-\end{verbatim}
-
-There is a suitable |dvi2ps.def| file in the standard distribution.
-It is not enabled by default as it is not well tested as the driver is
-no longer available to me. The following driver files are similarly
-distributed but not enabled by default.
-\begin{quote}\raggedright
- |dvi2ps|, |dvialw|, |dvilaser|, |dvitops|, |psprint|, |pubps|, |ln|
-\end{quote}
-
-Most of these driver files are generated from the source file
-|drivers.dtx|. That file has the sources for other versions (for
-example older versions of dvips and textures) which are not generated
-by default.
-
-If you use a driver that is not covered by any of these possibilities,
-you may try to write a |.def| file by analogy with one of the existing
-ones, and then specify a suitable option in |graphics.cfg| and
-|color.cfg|, as for the above example of |dvi2ps|.
-
-\section{Colour}
-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}
-\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 |\pagecolor{white}| to `get
-back to normal'.
-
-\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}
-\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[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|.
-\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:100 100 172 172
-\end{verbatim}
-That is, the printed region consists of a one-inch square, 100\,pt in
-from the bottom and left hand edges 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[115,110][135,145]{a}}|\\
-\gx |\includegraphics[bb= 115 110 135 145]{a}|\\
-left---\fbox{\includegraphics[bb= 115 110 135 145]{a}}---right
-
-\gs |\includegraphics*[115,110][135,145]{a}}|\\
-\gx |\includegraphics[bb= 115 110 135 145,clip]{a}|\\
-left---\fbox{\includegraphics[bb= 115 110 135 145,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. This is unix syntax, on a Mac it would be:\\
- |\graphicspath{{:eps:}{:tiff:}}|\\
- Note the differing conventions, an initial |:| is needed on Macintosh
- systems to denote the current folder, whereas on unix an initial |/|
- would denote the top level `root' directory.
-
- 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.
-
-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{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.
-
-\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.
-
-\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}