From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex-dev/required/graphics/grfguide.tex | 1031 +++++++++++++++++++++++ 1 file changed, 1031 insertions(+) create mode 100644 macros/latex-dev/required/graphics/grfguide.tex (limited to 'macros/latex-dev/required/graphics/grfguide.tex') diff --git a/macros/latex-dev/required/graphics/grfguide.tex b/macros/latex-dev/required/graphics/grfguide.tex new file mode 100644 index 0000000000..b00a86d307 --- /dev/null +++ b/macros/latex-dev/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