From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 macros/latex/required/graphics/grfguide.tex | 1031 +++++++++++++++++++++++++++
 1 file changed, 1031 insertions(+)
 create mode 100644 macros/latex/required/graphics/grfguide.tex

(limited to 'macros/latex/required/graphics/grfguide.tex')

diff --git a/macros/latex/required/graphics/grfguide.tex b/macros/latex/required/graphics/grfguide.tex
new file mode 100644
index 0000000000..b00a86d307
--- /dev/null
+++ b/macros/latex/required/graphics/grfguide.tex
@@ -0,0 +1,1031 @@
+%% 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}
-- 
cgit v1.2.3

