| 1 |
%% grfguide.tex Copyright (C) 1994-1999 David Carlisle |
| 2 |
%% Copyright (C) 2005-2024 |
| 3 |
%% The LaTeX Project and any individual authors listed elsewhere |
| 4 |
%% in this file. |
| 5 |
%% |
| 6 |
%% This file is part of the Standard LaTeX `Graphics Bundle'. |
| 7 |
%% It may be distributed under the terms of the LaTeX Project Public |
| 8 |
%% License, as described in lppl.txt in the base LaTeX distribution. |
| 9 |
%% Either version 1.3c or, at your option, any later version. |
| 10 |
%% |
| 11 |
%% This file has the LPPL maintenance status "maintained". |
| 12 |
|
| 13 |
\begin{filecontents*}{a.eps} |
| 14 |
%!PS-Adobe-2.0 EPSF-2.0 |
| 15 |
%%BoundingBox: 0 0 72 72 |
| 16 |
0 0 moveto |
| 17 |
72 72 rlineto |
| 18 |
72 neg 0 rlineto |
| 19 |
72 72 neg rlineto |
| 20 |
stroke |
| 21 |
newpath |
| 22 |
0 0 moveto |
| 23 |
20 40 lineto |
| 24 |
40 0 lineto |
| 25 |
10 20 moveto |
| 26 |
30 20 lineto |
| 27 |
stroke |
| 28 |
%%EOF |
| 29 |
\end{filecontents*} |
| 30 |
\documentclass{ltxguide} |
| 31 |
|
| 32 |
%%% No driver option specified |
| 33 |
%%% set up the files color.cfg and graphics.cfg for your site. |
| 34 |
%%% for example: |
| 35 |
%%% |
| 36 |
%%% \ExecuteOptions{dvips} |
| 37 |
%%% |
| 38 |
\usepackage{color,graphicx,shortvrb} |
| 39 |
|
| 40 |
%% Just as an example, and to make sure, in case some |
| 41 |
%% driver option has not declared a default rule for |
| 42 |
%% .ps files: |
| 43 |
%\DeclareGraphicsRule{.ps}{eps}{.ps}{} |
| 44 |
%\DeclareGraphicsExtensions{.pdf,.ps} |
| 45 |
%% Which means: |
| 46 |
%% .ps files are (to be treated as) EncapsulatedPostScript |
| 47 |
%% files. The .ps file is to be read for the BoundingBox. |
| 48 |
%% No `special' commands need to be applied by the driver. |
| 49 |
|
| 50 |
|
| 51 |
\renewcommand\star{{\ttfamily*}} |
| 52 |
|
| 53 |
\let\package\textsf |
| 54 |
|
| 55 |
\newlength{\gxlen} |
| 56 |
\settowidth{\gxlen}{\package{graphicx}: } |
| 57 |
\newcommand\gs{\makebox[\gxlen][l]{\package{graphics}:}} |
| 58 |
\newcommand\gx{\makebox[\gxlen][l]{\package{graphicx}:}} |
| 59 |
|
| 60 |
\MakeShortVerb{\|} |
| 61 |
|
| 62 |
\begin{document} |
| 63 |
\title{Packages in the `graphics' bundle} |
| 64 |
\author{D. P. Carlisle \and The \LaTeX\ Project} |
| 65 |
|
| 66 |
\date{2025-02-26} |
| 67 |
|
| 68 |
\maketitle |
| 69 |
|
| 70 |
\tableofcontents |
| 71 |
|
| 72 |
\section{Introduction} |
| 73 |
This document serves as a user-manual for the packages \package{color}, |
| 74 |
\package{graphics}, and \package{graphicx}. Further documentation may be |
| 75 |
obtained by processing the source (|dtx|) files of the individual |
| 76 |
packages. |
| 77 |
|
| 78 |
\section{Driver support}\label{drivers} |
| 79 |
All these packages rely on features that are not in \TeX\ itself. |
| 80 |
These features must be supplied by the `driver' used to print the |
| 81 |
|dvi| file. Unfortunately not all drivers support the same features, and |
| 82 |
even the internal method of accessing these extensions varies between |
| 83 |
drivers. Consequently all these packages take options such as |
| 84 |
`|dvips|' to specify which driver is being used. |
| 85 |
|
| 86 |
Normally you should \emph{not} specify the driver option explicitly |
| 87 |
in the document, but allow it to be defaulted automatically. |
| 88 |
This allows the document to be portable between different systems. |
| 89 |
|
| 90 |
Your \TeX\ distribution should have included |graphics.cfg| and |
| 91 |
|color.cfg| configuration files to specify these defaults. |
| 92 |
Standard versions of the configuration files are maintained by the |
| 93 |
\LaTeX\ Project and distributed in the CTAN |graphics-cfg| collection. |
| 94 |
|
| 95 |
For special requirements you may edit a copy of these |cfg| files |
| 96 |
to set up a site default for these options. Suppose that you wish |
| 97 |
the \package{color} package to always default to use specials for the |
| 98 |
PostScript driver, |dvisvgm|. In that case, create a file |color.cfg| |
| 99 |
containing the line: |
| 100 |
\begin{quote} |
| 101 |
|\ExecuteOptions{dvisvgm}| |
| 102 |
\end{quote} |
| 103 |
Normally you will want an identical file |graphics.cfg| to set a similar |
| 104 |
default for the graphics packages. |
| 105 |
|
| 106 |
The following driver options are declared in the packages. |
| 107 |
The matching definition files (\emph{driver}|.def|) |
| 108 |
are now also maintained by the \LaTeX\ project, |
| 109 |
but distributed separately, in the CTAN |graphics-def| collection. |
| 110 |
\begin{quote}\raggedright |
| 111 |
|dvipdfmx|, |dvips|, |dvisvgm|, |luatex|, |pdftex|, |xetex| |
| 112 |
\end{quote} |
| 113 |
|
| 114 |
|
| 115 |
The following two options are also supported, they do not correspond |
| 116 |
to separate definition files, but are essentially aliases for the |
| 117 |
|dvips| option (and |monochrome| in the case of |xdvi|). |
| 118 |
\begin{quote}\raggedright |
| 119 |
|xdvi|, |oztex| |
| 120 |
\end{quote} |
| 121 |
|
| 122 |
The following set of options are supported by these packages |
| 123 |
with associated driver files extracted from the |drivers.dtx| |
| 124 |
documented source in this bundle. These are now mainly of historic |
| 125 |
interest but the documented sources do contain some useful code |
| 126 |
and advice if you need to produce a new definition file for a new |
| 127 |
driver or \TeX\ system. |drivers.dtx| also contains documented |
| 128 |
sources for older driver files that are no longer extracted. |
| 129 |
\begin{quote}\raggedright |
| 130 |
|dvipdf|, |dvipdfm|, |dviwin|, |dvipsone|, |
| 131 |
|emtex|, |pctexps|, |pctexwin|, |pctexhp|, |pctex32|, |
| 132 |
|truetex|, |tcidvi|, |vtex| |
| 133 |
\end{quote} |
| 134 |
|
| 135 |
The final driver option is an alias for |dvipsone|. |
| 136 |
\begin{quote}\raggedright |
| 137 |
|dviwindo| |
| 138 |
\end{quote} |
| 139 |
|
| 140 |
|
| 141 |
\section[Colour]{Colour\footnote{% |
| 142 |
The basic \package{color} package functionality described here |
| 143 |
will be enough for many uses, however a much extended version |
| 144 |
is available in the contributed \package{xcolor} package, distributed |
| 145 |
and maintained separately. All the color commands described here are |
| 146 |
also available if you specify \package{xcolor} in your document.}% |
| 147 |
} |
| 148 |
The colour support is built around the idea of a system of |
| 149 |
\emph{Colour Models}. The Colour models supported by a driver vary, |
| 150 |
but typically include |
| 151 |
\begin{description} |
| 152 |
\item[rgb] Red Green Blue: A comma separated list of three numbers |
| 153 |
between~0 and~1, giving the components of the colour. |
| 154 |
\item[cmyk] Cyan Magenta Yellow [K]Black: A comma separated list of |
| 155 |
four numbers between~0 and~1, giving the components of the colour |
| 156 |
according to the additive model used in most printers. |
| 157 |
\item[gray] Grey scale: a single number between~0 and~1. |
| 158 |
\item[named] Colours accessed by name, e.g.\ `JungleGreen'. Not all |
| 159 |
drivers support this model. The names must either be `known' to the |
| 160 |
driver or added using commands described in |color.dtx|. Some drivers |
| 161 |
support an extended form of the named model in which an `intensity' of |
| 162 |
the colour may also be specified, so `\mbox{JungleGreen, 0.5}' would |
| 163 |
denote that colour at half strength. |
| 164 |
\end{description} |
| 165 |
Note that the \textbf{named} model is really just given as an example |
| 166 |
of a colour model that takes names rather than a numeric specification. |
| 167 |
Other options may be provided locally that provide different colour |
| 168 |
models, eg \textbf{pantone} (An industry standard set of colours), |
| 169 |
\textbf{x11} (Colour names from the X Window System), etc. The |
| 170 |
standard distribution does not currently have such models, but the |
| 171 |
\textbf{named} model could be used as an example of how to define a new |
| 172 |
colour model. The names used in the \textbf{named} model are those |
| 173 |
suggested by Jim Hafner in his \textsf{colordvi} and \textsf{foiltex} |
| 174 |
packages, and implemented originally in the |color.pro| header file for |
| 175 |
the \texttt{dvips} driver. |
| 176 |
|
| 177 |
\subsection{Package Options} |
| 178 |
Most of the options to the \package{color} package just specify a |
| 179 |
driver, e.g., \ |dvips|, as discussed in section~\ref{drivers}. |
| 180 |
|
| 181 |
One special option for the \package{color} package |
| 182 |
that is of interest is |monochrome.| |
| 183 |
If this option is selected the colour commands are all |
| 184 |
disabled so that they do not generate errors, but do not generate colour |
| 185 |
either. This is useful if previewing with a previewer that can not |
| 186 |
produce colour. |
| 187 |
|
| 188 |
Three other package options control the use of the \textbf{named} model. |
| 189 |
The |dvips| driver (by default) pre-defines 68 colour names. The |dvips| |
| 190 |
option normally makes these names available in the \textbf{named} colour |
| 191 |
model. If you do not want these names to be declared in this model |
| 192 |
(Saving \TeX\ some memory) you may give the |nodvipsnames| |
| 193 |
option. Conversely, if you are using another driver, you may wish to |
| 194 |
add these names to the named model for that driver (especially if you |
| 195 |
are processing a document originally produced on |dvips|). In this case |
| 196 |
you could use the |dvipsnames| option. Lastly the |usenames| option |
| 197 |
makes all names in the \textbf{named} model directly available, as |
| 198 |
described below. |
| 199 |
|
| 200 |
\subsection{Defining Colours} |
| 201 |
|
| 202 |
The colours |black|, |white|, |red|, |green|, |blue|, |cyan|, |
| 203 |
|magenta|, |yellow| should be predefined, but should you wish to mix |
| 204 |
your own colours use the |\definecolor| command. |
| 205 |
|
| 206 |
\begin{decl} |
| 207 |
|\definecolor|\arg{name}\arg{model}\arg{colour specification} |
| 208 |
\end{decl} |
| 209 |
|
| 210 |
|
| 211 |
This defines \m{name} as a colour which can be used in later colour |
| 212 |
commands. For example: |
| 213 |
\begin{quote} |
| 214 |
|\definecolor{light-blue}{rgb}{0.8,0.85,1}| \\ |
| 215 |
|\definecolor{mygrey}{gray}{0.75}| |
| 216 |
\end{quote} |
| 217 |
\definecolor{light-blue}{rgb}{0.8,0.85,1} |
| 218 |
\definecolor{mygrey}{gray}{0.75} |
| 219 |
|
| 220 |
Now |light-blue| and |mygrey| may be used in addition to the |
| 221 |
predefined colours above. |
| 222 |
|
| 223 |
\subsection{Using Colours} |
| 224 |
|
| 225 |
\subsubsection{Using predefined colours} |
| 226 |
The syntax for colour changes is designed to mimic font changes. |
| 227 |
The basic syntax is: |
| 228 |
|
| 229 |
\begin{decl} |
| 230 |
|\color|\arg{name} |
| 231 |
\end{decl} |
| 232 |
|
| 233 |
This is a \emph{declaration}, like |\bfseries|. It changes the current |
| 234 |
colour to \m{name} until the end of the current group, or |
| 235 |
environment. It does not automatically start horizontal mode so typically at |
| 236 |
the start of a paragraph it should be used in combination with a |\leavevmode|. |
| 237 |
|
| 238 |
An alternative command syntax is to use a \emph{command} form that |
| 239 |
takes the text to be coloured as an \emph{argument}. This is similar |
| 240 |
to the font commands such as |\textbf|: |
| 241 |
|
| 242 |
\begin{decl} |
| 243 |
|\textcolor|\arg{name}\arg{text} |
| 244 |
\end{decl} |
| 245 |
|
| 246 |
The command switches to horizontal mode, |
| 247 |
so the above is essentially equivalent to |
| 248 |
|{\leavevmode\color|\arg{name}\emph{text}|}|. In contrast to |\textbf|, |
| 249 |
the command gobbles spaces at the start of its argument, so |Hello\textcolor{red}{ World}| will output Hello\textcolor{red}{ World}. |
| 250 |
|
| 251 |
\subsection{Using Colours in math formulas} |
| 252 |
|
| 253 |
While |\color| and to some extent |\textcolor| can be used in |
| 254 |
formulas, this is cumbersome, may lead to bad spacing, and in some |
| 255 |
situations is simply not possible. For this reason we also introduce |
| 256 |
|\mathcolor| which will help in this respect. The basic syntax is: |
| 257 |
|
| 258 |
\begin{decl} |
| 259 |
|\mathcolor|\arg{name}\arg{math} |
| 260 |
\end{decl} |
| 261 |
|
| 262 |
See \texttt{mathcolor.pdf} for details on this command. |
| 263 |
|
| 264 |
|
| 265 |
\subsubsection{Using colour specifications directly} |
| 266 |
|
| 267 |
\begin{decl} |
| 268 |
|\color|\oarg{model}\arg{specification}\\ |
| 269 |
|\textcolor|\oarg{model}\arg{specification}\arg{text}\\ |
| 270 |
|\mathcolor|\oarg{model}\arg{specification}\arg{math} |
| 271 |
\end{decl} |
| 272 |
|
| 273 |
Normally one would predeclare all the colours used in a package, or in |
| 274 |
the document preamble, but sometimes it is convenient to directly use |
| 275 |
a colour without naming it first. To achieve this |\color| (and all |
| 276 |
the other colour commands) take an optional argument specifying the |
| 277 |
model. If this is used then the mandatory argument takes a |
| 278 |
\m{colour specification} instead of a \m{name}. For example: |
| 279 |
\begin{quote} |
| 280 |
|\color[rgb]{1,0.2,0.3}| |
| 281 |
\end{quote} |
| 282 |
would directly select that colour. |
| 283 |
|
| 284 |
This is particularly useful for accessing the \textbf{named} model: |
| 285 |
\begin{quote} |
| 286 |
|\color[named]{BrickRed}| |
| 287 |
\end{quote} |
| 288 |
selects the |dvips| colour BrickRed. |
| 289 |
|
| 290 |
Rather than repeatedly use |[named]| you may use |\definecolor| to |
| 291 |
provide convenient aliases: |
| 292 |
\begin{quote} |
| 293 |
|\definecolor{myred}{named}{WildStrawberry}|\ldots |\color{myred}|\kern-10pt |
| 294 |
\end{quote} |
| 295 |
Alternatively if you are happy to use the existing names from the |
| 296 |
\textbf{named} model, you may use the |usenames| package option, which |
| 297 |
effectively calls |\definecolor| on every colour in the \textbf{named} |
| 298 |
model, thus allowing |\color{WildStrawberry}| in addition to |
| 299 |
|\color[named]{WildStrawbery}|. |
| 300 |
|
| 301 |
\subsection{Named Colours} |
| 302 |
Using the \textbf{named} colour model has certain advantages over |
| 303 |
using other colour models. |
| 304 |
|
| 305 |
Firstly as the |dvi| file contains a request |
| 306 |
for a colour by \emph{name}, the actual mix of primary colours used to |
| 307 |
obtain the requested colour can be tuned to the characteristics of a |
| 308 |
particular printer. In the |dvips| driver the meanings of the colour |
| 309 |
names are defined in the header file |color.pro|. Users are encouraged |
| 310 |
to produce different versions of this file for any printers they use. By |
| 311 |
this means the same dvi file should produce colours of similar |
| 312 |
appearance when printed on printers with different colour |
| 313 |
characteristics. |
| 314 |
|
| 315 |
Secondly, apart from the so called `process colours' that are produced |
| 316 |
by mixing primary colours during the print process, one may want to use |
| 317 |
`spot' or `custom' colours. Here a particular colour name does not |
| 318 |
refer to a mix of primaries, but to a particular ink. The parts of the |
| 319 |
document using this colour will be printed separately using this named |
| 320 |
ink colour. |
| 321 |
|
| 322 |
\subsection{Page Colour} |
| 323 |
|
| 324 |
|
| 325 |
\begin{decl} |
| 326 |
|\pagecolor|\arg{name}\\ |
| 327 |
|\pagecolor|\oarg{model}\arg{specification}\\ |
| 328 |
|\nopagecolor| |
| 329 |
\end{decl} |
| 330 |
|
| 331 |
The background colour of the whole page can be set using |
| 332 |
|\pagecolor|. This takes the same argument forms as |\color| but sets |
| 333 |
the background colour for the current and all subsequent pages. It is |
| 334 |
a global declaration, so you need to use |
| 335 |
|\nopagecolor|\NEWfeature{2014/04/23}\ to `get back to normal'. |
| 336 |
If that is not supported, you may use |\pagecolor{white}| although that |
| 337 |
will make a white background rather than the default transparent background. |
| 338 |
|
| 339 |
\subsection{Box Backgrounds} |
| 340 |
Two commands similar to |\fbox| produce boxes with the backgrounds |
| 341 |
shaded an appropriate colour. |
| 342 |
|
| 343 |
\begin{decl} |
| 344 |
|\colorbox|\arg{name}\arg{text}\\ |
| 345 |
|\colorbox|\oarg{model}\arg{specification}\arg{text}\\ |
| 346 |
|\fcolorbox|\arg{name1}\arg{name2}\arg{text}\\ |
| 347 |
|\fcolorbox|\oarg{model}% |
| 348 |
\arg{specification1}\arg{specification2}\arg{text} |
| 349 |
\end{decl} |
| 350 |
|
| 351 |
|
| 352 |
The former produces a box coloured with \emph{name} |
| 353 |
\colorbox{mygrey}{like this}. The latter is similar but puts a frame of |
| 354 |
colour \emph{name1} around the box coloured \emph{name2}. |
| 355 |
|
| 356 |
These commands use the |\fbox| parameters |\fboxrule| and |\fboxsep| |
| 357 |
to determine the thickness of the rule, and the size of the shaded area. |
| 358 |
|
| 359 |
\subsection{Possible Problems} |
| 360 |
|
| 361 |
\TeX\ was not designed with colour in mind, and producing colours |
| 362 |
requires a lot of help from the driver program. Thus, depending on the |
| 363 |
driver, some or all features of the \package{color} package may not be |
| 364 |
available. |
| 365 |
|
| 366 |
Some drivers do not maintain a special `colour stack'. These drivers are |
| 367 |
likely to get confused if you nest colour changes, or use colours in |
| 368 |
floating environments. |
| 369 |
|
| 370 |
Some drivers do not maintain colours over a page break, so that if the |
| 371 |
page breaks in the middle of a coloured paragraph, the last part of the |
| 372 |
text will incorrectly be printed in black. |
| 373 |
|
| 374 |
There is a different type of problem that will occur for all drivers. |
| 375 |
Due to certain technical difficulties\footnote{At least two causes: |
| 376 |
1) The presence of a \texttt{\char`\\special} \m{whatsit} prevents |
| 377 |
\texttt{\char`\\addvspace} `seeing' space on the current vertical list, |
| 378 |
so causing it to incorrectly add extra vertical space. 2) A |
| 379 |
\m{whatsit} as the first item in a \texttt{\char`\\vtop} moves the |
| 380 |
reference point of the box.}% |
| 381 |
, it is possible that at points |
| 382 |
where the colour changes, the \emph{spacing} is affected. For this |
| 383 |
reason the |monochrome| option does not completely disable the colour |
| 384 |
commands, it redefines them to write to the log file. This will have the |
| 385 |
same effects on spacing, so you can produce monochrome drafts of your |
| 386 |
document, at least knowing that the final spacing is being shown. |
| 387 |
\section{The Graphics packages} |
| 388 |
There are two graphics packages: |
| 389 |
\begin{description} |
| 390 |
\item[\package{graphics}] The `standard' graphics package. |
| 391 |
\item[\package{graphicx}] The `extended' or `enhanced' graphics |
| 392 |
package. |
| 393 |
\end{description} |
| 394 |
The two differ only in the format of optional arguments for the |
| 395 |
commands defined. The command names, and the mandatory arguments are |
| 396 |
the same for the two packages. |
| 397 |
|
| 398 |
\subsection{Package Options} |
| 399 |
As discussed in section~\ref{drivers}, the graphics packages share the |
| 400 |
same `driver' options as the \package{color} package. As for colour |
| 401 |
you should set up a site-default in a file, |
| 402 |
|graphics.cfg|, containing the line (for |dvips|):\\ |
| 403 |
|\ExecuteOptions{dvips}| |
| 404 |
|
| 405 |
The graphics packages have some other options for controlling how many |
| 406 |
of the features to enable: |
| 407 |
\begin{description} |
| 408 |
\item[draft] Suppress all the `special' features. In particular |
| 409 |
graphics files are not included (but they are still read for size |
| 410 |
info) just the filename is printed in a box of the correct size. |
| 411 |
\item[final] The opposite of |draft|. Useful to over-ride a global |
| 412 |
|draft| option specified in the |\documentclass| command. |
| 413 |
\item[hiderotate] Do not show rotated text (presumably because the |
| 414 |
previewer can not rotate). |
| 415 |
\item[hidescale] Do not show scaled text (presumably because the |
| 416 |
previewer can not scale). |
| 417 |
\item[hiresbb] Look for size specifications in |%%HiResBoundingBox| |
| 418 |
lines rather than standard |%%BoundingBox| lines.% |
| 419 |
\NEWfeature{1996/10/29} |
| 420 |
\item[demo] Instead of inserting an image file |\includegraphics| |
| 421 |
draws a 150\,pt by 100\,pt rectangle unless other dimensions are |
| 422 |
specified manually.\NEWfeature{2006/02/20} |
| 423 |
\end{description} |
| 424 |
\subsection{Rotation} |
| 425 |
|
| 426 |
\begin{decl} |
| 427 |
\gs |\rotatebox|\arg{angle}\arg{text}\\ |
| 428 |
\gx |\rotatebox|\oarg{key val list}\arg{angle}\arg{text} |
| 429 |
\end{decl} |
| 430 |
|
| 431 |
This puts \emph{text} in a box, like |\mbox|, but rotates the box |
| 432 |
through \emph{angle} degrees, \rotatebox{15}{like this}. |
| 433 |
|
| 434 |
The standard version always rotates around the reference point of the |
| 435 |
box, but the \package{keyval} version takes the following keys: |
| 436 |
|
| 437 |
\begin{decl} |
| 438 |
|origin|=\m{label}\\ |
| 439 |
|x|=\m{dimen}\\ |
| 440 |
|y|=\m{dimen}\\ |
| 441 |
|units|=\m{number} |
| 442 |
\end{decl} |
| 443 |
|
| 444 |
So you may specify both |x| and |y|, which give the coordinate of |
| 445 |
the centre of rotation relative to the reference point of the box, eg |
| 446 |
|[x=2mm, y=5mm]|. Alternatively, for the most common points, one may use |
| 447 |
|origin| with a \emph{label} containing one or two of the following: |
| 448 |
|lrctbB| (|B| denotes the baseline, as for \package{PSTricks}). For |
| 449 |
example, compare a default rotation of $180^\circ$ |
| 450 |
\ldots\rotatebox{180}{Like This}\ldots\ to the effects gained by using |
| 451 |
the |origin| key:\\ |
| 452 |
|[origin = c]| rotates about the centre of the box,\ldots |
| 453 |
\rotatebox[origin=c]{180}{Like This}\ldots\\ |
| 454 |
|[origin = tr]| rotates about the top right hand corner\ldots |
| 455 |
\rotatebox[origin=tr]{180}{Like This}\ldots |
| 456 |
|
| 457 |
The |units| key allows a change from the default units of degrees |
| 458 |
anti-clockwise. Give the number of units in one full anti-clockwise |
| 459 |
rotation. For example:\\ |
| 460 |
|[units = -360]| specifies degrees clockwise.\\ |
| 461 |
|[units= 6.283185]| specifies radians. |
| 462 |
|
| 463 |
\subsection{Scaling} |
| 464 |
|
| 465 |
\subsubsection{Scaling by scale factor} |
| 466 |
|
| 467 |
\begin{decl} |
| 468 |
|\scalebox|\arg{h-scale}\oarg{v-scale}\arg{text} |
| 469 |
\end{decl} |
| 470 |
|
| 471 |
Again this is basically like |\mbox| but scales the \emph{text}. |
| 472 |
If \emph{v-scale} is not specified it defaults to \emph{h-scale}. |
| 473 |
If it is specified the text is distorted as the horizontal and |
| 474 |
vertical stretches are different, \scalebox{3}[.7]{Like This}. |
| 475 |
|
| 476 |
|
| 477 |
\begin{decl} |
| 478 |
|\reflectbox|\arg{text} |
| 479 |
\end{decl} |
| 480 |
|
| 481 |
An abbreviation for |\scalebox{-1}[1]|\arg{text}. |
| 482 |
|
| 483 |
\subsubsection{Scaling to a requested size} |
| 484 |
|
| 485 |
\begin{decl} |
| 486 |
|\resizebox|\star\arg{h-length}\arg{v-length}\arg{text} |
| 487 |
\end{decl} |
| 488 |
|
| 489 |
Scale \emph{text} so that the width is \emph{h-length}. |
| 490 |
If |!| is used as either length argument, the other argument is used |
| 491 |
to determine a scale factor that is used in both directions. |
| 492 |
|
| 493 |
As normal for \LaTeXe\ box length arguments, |\height|, |
| 494 |
|\width|, |\totalheight|, |\depth| may be used to refer to the |
| 495 |
original size of the box. |
| 496 |
|
| 497 |
Normally \emph{v-length} refers to the height of the box, but in the |
| 498 |
star form, |\resizebox*|, it refers to the `height + depth'. |
| 499 |
|
| 500 |
|\resizebox{1in}{\height}{Some text}|: |
| 501 |
\resizebox{1in}{\height}{Some text} |
| 502 |
|
| 503 |
|\resizebox{1in}{!}{Some text}|: |
| 504 |
\resizebox{1in}{!}{Some text} |
| 505 |
|
| 506 |
|\resizebox{!}{20pt}{Q} \resizebox*{!}{20pt}{Q}|: |
| 507 |
\resizebox{!}{20pt}{Q} \resizebox*{!}{20pt}{Q} |
| 508 |
|
| 509 |
\subsection{Including Graphics Files} |
| 510 |
The functions for graphics inclusion try to give the same user syntax |
| 511 |
for including any kind of graphics file that can be understood by the |
| 512 |
driver. This relies on the file having an extension that identifies |
| 513 |
the file type. The `driver options' will define a collection of file |
| 514 |
extensions that the driver can handle, although this list may be |
| 515 |
extended using the declarations described below. |
| 516 |
|
| 517 |
If the file's extension is unknown to the driver, the system may try a |
| 518 |
default file type. The PostScript driver files set this default to be |
| 519 |
|eps| (PostScript), but this behaviour may be customised if other |
| 520 |
defaults are required. |
| 521 |
|
| 522 |
\begin{decl} |
| 523 |
\gs |\includegraphics|\star\oarg{llx,lly}\oarg{urx,ury}\arg{file}\\ |
| 524 |
\gx |\includegraphics|\star\oarg{key val list}\arg{file} |
| 525 |
\end{decl} |
| 526 |
Include a graphics file. |
| 527 |
|
| 528 |
If \star\ is present, then the graphic is `clipped' to the size |
| 529 |
specified. If \star\ is omitted, then any part of the graphic that is |
| 530 |
outside the specified `bounding box' will over-print the surrounding |
| 531 |
text. |
| 532 |
|
| 533 |
If the optional arguments are omitted, then the size of the graphic |
| 534 |
will be determined by reading an external file as described below. |
| 535 |
|
| 536 |
\paragraph{\package{graphics} version} |
| 537 |
If \oarg{urx,ury} is present, then it should specify the coordinates |
| 538 |
of the top right corner of the image, as a pair of \TeX\ dimensions. |
| 539 |
If the units are omitted they default to |bp|. So |[1in,1in]| and |
| 540 |
|[72,72]| are equivalent. If only one optional argument appears, the |
| 541 |
lower left corner of the image is assumed to be at |[0,0]|. Otherwise |
| 542 |
\oarg{llx,lly} may be used to specify the coordinates of this point. |
| 543 |
|
| 544 |
\paragraph{\package{graphicx} version} |
| 545 |
Here the star form is just for compatibility with the standard |
| 546 |
version. It just adds |clip| to the list of keys specified. |
| 547 |
(Also, for increased compatibility, if \emph{two} optional arguments are |
| 548 |
used, the `standard' version of |\includegraphics| is always used, even |
| 549 |
if the \package{graphicx} package is loaded.) |
| 550 |
|
| 551 |
The allowed keys are listed below. |
| 552 |
\begin{description} |
| 553 |
\item[bb] The argument should be four dimensions, separated by spaces. |
| 554 |
These denote the `Bounding Box' of the printed region within |
| 555 |
the file. |
| 556 |
\item[bbllx,bblly,bburx,bbury] Set the bounding box. Mainly for |
| 557 |
compatibility with older packages. |
| 558 |
Specifying |bbllx=a,bblly=b,bburx=c,bbury=d| |
| 559 |
is equivalent to specifying |bb = a b c d|. |
| 560 |
\item[natwidth,natheight] Again an alternative to |bb|. |
| 561 |
|natheight=h,natwidth=w| is equivalent to |bb = 0 0 h w|. |
| 562 |
\item[hiresbb]\NEWfeature{1996/10/29} |
| 563 |
Boolean valued key. If set to |true| (just specifying |hiresbb| |
| 564 |
is equivalent to |hiresbb=true|) then \TeX\ will look for |
| 565 |
|%%HiResBoundingBox| lines rather than |%%BoundingBox|. It may be set |
| 566 |
to |false| to overrule a default setting of |true| set by the |
| 567 |
|hiresbb| package option. |
| 568 |
\item[pagebox]\NEWfeature{2017/06/01} |
| 569 |
PDF files do not have BoundingBox but may specify up to four predefined |
| 570 |
rectangles. |
| 571 |
|
| 572 |
|MediaBox|: the boundaries of the physical medium. |
| 573 |
|CropBox|: the region to which the contents of the page are to be |
| 574 |
clipped when displayed. |
| 575 |
|BleedBox|: the region to which the contents of the |
| 576 |
page should be clipped in production. |
| 577 |
|TrimBox|: the intended dimensions of the finished page. |
| 578 |
|ArtBox|: the extent of the page's meaningful content. |
| 579 |
|
| 580 |
The driver will set the image size based on |CropBox| if present, |
| 581 |
otherwise it will not use one of the others, |
| 582 |
with a driver-defined order of preference. |
| 583 |
|MediaBox| is always present. |
| 584 |
|
| 585 |
The |pagebox| key may be used to specify which bounding box specification to use. |
| 586 |
The value should be one of |
| 587 |
|mediabox|, |cropbox|, |bleedbox|, |trimbox|, |artbox|. |
| 588 |
\item[viewport]\NEWfeature{1995/06/01} |
| 589 |
The |viewport| key takes four arguments, just like |
| 590 |
|bb|. However in this case the values are taken relative to the |
| 591 |
origin specified by the bounding box in the file. So to `view' the |
| 592 |
1in square in the bottom left hand corner of the area specified by |
| 593 |
the bounding box, use the argument |viewport=0 0 72 72|. |
| 594 |
\item[trim]\NEWfeature{1995/06/01} |
| 595 |
Similar to viewport, but here the four lengths specify the |
| 596 |
amount to remove or add to each side. |trim= 1 2 3 4| `crops' the |
| 597 |
picture by 1bp at the left, 2bp at the bottom, 3bp on the right and |
| 598 |
4bp at the top. |
| 599 |
\item[angle] Rotation angle. |
| 600 |
\item[origin]\NEWfeature{1995/09/28} |
| 601 |
Origin for rotation. See the documentation of |\rotatebox|. |
| 602 |
\item[width] Required width. The |
| 603 |
graphic is scaled to this width. The special value |!| can be used |
| 604 |
to (re)set the width to the natural width. |
| 605 |
\item[height] Required height. The |
| 606 |
graphic is scaled to this height. The special value |!| can be used |
| 607 |
to (re)set the height to the natural height. |
| 608 |
\item[totalheight]\NEWfeature{1995/06/01} |
| 609 |
Specify the total height (height $+$ depth) of the figure. |
| 610 |
This will differ from the `height' if rotation has occurred. |
| 611 |
In particular if the figure has been rotated by $-90^\circ$ |
| 612 |
then it will have zero height but large depth. The special value |!| can be used |
| 613 |
to (re)set the totalheight to the natural totalheight. |
| 614 |
\item[keepaspectratio]\NEWfeature{1995/09/27} |
| 615 |
Boolean valued key like `clip'. |
| 616 |
If set to true then specifying both `width' and `height' (or |
| 617 |
`totalheight') does not distort the figure but scales such that |
| 618 |
neither of the specified dimensions is \emph{exceeded}. |
| 619 |
\item[scale] Scale factor. |
| 620 |
\item[clip] Either `true' or `false' (or no value, which is equivalent |
| 621 |
to `true'). Clip the graphic to the bounding box. |
| 622 |
\item[draft] A boolean valued key, like `clip'. Locally switches to |
| 623 |
draft mode. |
| 624 |
\item[type] Specify the graphics type. |
| 625 |
\item[ext] Specify the file extension. This should \emph{only} be |
| 626 |
used in conjunction with |type|. |
| 627 |
\item[read] Specify the file extension of the `read file'. This |
| 628 |
should \emph{only} be used in conjunction with |type|. |
| 629 |
\item[command] Specify any command to be applied to the file. This |
| 630 |
should \emph{only} be used in conjunction with |type|. |
| 631 |
\item[quiet]\NEWfeature{2017/06/01} |
| 632 |
Skip writing information to the log. |
| 633 |
\item[page]\NEWfeature{2017/06/01} |
| 634 |
Page of a multi-page PDF file. (By default the first page will be used.) |
| 635 |
\item[interpolate]\NEWfeature{2017/06/01} |
| 636 |
Enable/disable interpolation of bitmap images by the viewer. |
| 637 |
\item[alt]\NEWfeature{2021/09/16} |
| 638 |
Alternative text for accessibility uses. By default this key is not used |
| 639 |
but users are encouraged to add descriptive text here that may be used in |
| 640 |
tagged PDF or as the |alt| attribute in conversions to HTML. |
| 641 |
\item[actualtext]\NEWfeature{2024/12/31} |
| 642 |
ActualText text for accessibility uses. By default this key is not used |
| 643 |
but users are encouraged to add text here that may be used in |
| 644 |
tagged PDF or as the text to use in formats that do not use the image. |
| 645 |
\item[artifact]\NEWfeature{2024/12/31} |
| 646 |
Boolean to mark the graphic as an artifact for accessibility uses. By default this key is not used |
| 647 |
but users are encouraged to flag decorative or other non structural images as an artifact for |
| 648 |
tagged PDF. |
| 649 |
\end{description} |
| 650 |
|
| 651 |
For the keys specifying the original size (i.e., the bounding box, |
| 652 |
trim and viewport keys) the units can be omitted, in |
| 653 |
which case bp (i.e., PostScript points) are assumed. |
| 654 |
|
| 655 |
The first seven keys specify the original size of the image. This size |
| 656 |
needs to be specified in the case that the file can not be read by |
| 657 |
\TeX, or it contains an incorrect size `BoundingBox' specification. |
| 658 |
|
| 659 |
|bbllx|\ldots\ |\bbury| are mainly for compatibility for older |
| 660 |
packages.\\ |
| 661 |
|bbllx=a, bblly=b, bburx=c, bbury=d|\\ |
| 662 |
is equivalent to\\ |
| 663 |
|bb = a b c d|. |
| 664 |
|
| 665 |
|natheight| and |natwidth| are just shorthands for setting the lower |
| 666 |
left coordinate to 0 0 and the upper right coordinate to the specified |
| 667 |
width and height. |
| 668 |
|
| 669 |
The next few keys specify any scaling or rotation to be applied to the |
| 670 |
image. To get these effects using the standard package, the |
| 671 |
|\includegraphics| call must be placed inside the argument of a |
| 672 |
|\rotatebox| or |\scalebox| command. |
| 673 |
|
| 674 |
The keys are read left-to-right, so |[angle=90, height=1in]| means |
| 675 |
rotate by 90 degrees, and then scale to a height of 1in. |
| 676 |
|[height=1in, angle=90]| would result in a final \emph{width} of 1in. |
| 677 |
|
| 678 |
If the \textsf{calc} package is also loaded the lengths may use |
| 679 |
\textsf{calc} syntax, for instance to specify a width of 2\,cm |
| 680 |
less than the text width: |[width=\textwidth-2cm]|. |
| 681 |
|
| 682 |
\TeX\ leaves the space specified either in the file, or in |
| 683 |
the optional arguments. If any part of the image is actually outside |
| 684 |
this area, it will by default overprint the surrounding text. |
| 685 |
If the star form is used, or |clip| specified, any part of the image |
| 686 |
outside this area will not be printed. |
| 687 |
|
| 688 |
The last four keys suppress the parsing of the filename. If they are |
| 689 |
used, the main \emph{file} argument should not have the file |
| 690 |
extension. They correspond to the arguments of |\DeclareGraphicsRule| |
| 691 |
described below. |
| 692 |
|
| 693 |
To see the effect that the various options have consider the file |
| 694 |
|a.ps|. This file contains the bounding box specification |
| 695 |
\begin{verbatim} |
| 696 |
%%BoundingBox:0 0 72 72 |
| 697 |
\end{verbatim} |
| 698 |
That is, the printed region consists of a one-inch square, in |
| 699 |
the bottom left hand corner of the paper. |
| 700 |
|
| 701 |
In all the following examples the input will be of the form |
| 702 |
\begin{verbatim} |
| 703 |
left---\fbox{\includegraphics{a}}---right |
| 704 |
\end{verbatim} |
| 705 |
With different options supplied to |\includegraphics|. |
| 706 |
|
| 707 |
No optional argument.\\ |
| 708 |
left---\fbox{\includegraphics{a.eps}}---right |
| 709 |
|
| 710 |
\gs |\scalebox{0.5}{\includegraphics{a}}|\\ |
| 711 |
\gx |\includegraphics[scale=.5]{a}|\\ |
| 712 |
left---\fbox{\includegraphics[scale=.5]{a.eps}}---right |
| 713 |
|
| 714 |
\gs |\includegraphics[15,10][35,45]{a}}|\\ |
| 715 |
\gx |\includegraphics[viewport= 15 10 35 45]{a}|\\ |
| 716 |
left---\fbox{\includegraphics[viewport= 15 10 35 45]{a.eps}}---right |
| 717 |
|
| 718 |
\gs |\includegraphics*[15,10][35,45]{a}}|\\ |
| 719 |
\gx |\includegraphics[viewport= 15 10 35 45,clip]{a}|\\ |
| 720 |
left---\fbox{\includegraphics[viewport= 15 10 35 45,clip]{a.eps}}---right |
| 721 |
|
| 722 |
\gs |\scalebox{0.5}{\includegraphics{a}}| |
| 723 |
and |draft| option.\\ |
| 724 |
\gx |\includegraphics[scale=.5, draft]{a}|\\ |
| 725 |
left---\fbox{\includegraphics[scale=.5, draft]{a.eps}}---right |
| 726 |
|
| 727 |
\subsection{Other commands in the \package{graphics} package} |
| 728 |
|
| 729 |
\begin{decl} |
| 730 |
|\graphicspath|\arg{dir-list} |
| 731 |
\end{decl} |
| 732 |
This optional declaration may be used to specify a list of directories |
| 733 |
in which to search for graphics files. The format is the same as for |
| 734 |
the \LaTeXe\ primitive |\input@path|. A list of directories, each in a |
| 735 |
|{}| group (even if there is only one in the list). For example:\\ |
| 736 |
|\graphicspath{{eps/}{tiff/}}|\\ |
| 737 |
would cause the system to look in the subdirectories |eps| and |tiff| |
| 738 |
of the current directory. (All modern \TeX{} systems use |/| |
| 739 |
as the directory separator, even on Windows.) |
| 740 |
|
| 741 |
The default setting of this path is |
| 742 |
|\input@path|, so that graphics files will be found wherever \TeX\ |
| 743 |
files are found. |
| 744 |
|
| 745 |
\begin{decl} |
| 746 |
|\DeclareGraphicsExtensions|\arg{ext-list} |
| 747 |
\end{decl} |
| 748 |
\NEWdescription{1994/12/01} |
| 749 |
This specifies the behaviour of the system when no file extension |
| 750 |
is specified in the argument to |\includegraphics|. |
| 751 |
\arg{ext-list} should be a comma separated list of file extensions. |
| 752 |
(White space is ignored between the entries.) |
| 753 |
A file name is produced by appending one extension from the list. |
| 754 |
If a file is found, the system acts as if that extension had been |
| 755 |
specified. If not, the next extension in \emph{ext-list} is tried. |
| 756 |
|
| 757 |
|
| 758 |
Note that if the extension is not specified in the |\includegraphics| |
| 759 |
command, the graphics file must exist at the time \LaTeX\ is run, as |
| 760 |
the existence of the file is used to determine which extension from |
| 761 |
the list to choose. However if a file extension \emph{is} specified, |
| 762 |
e.g.\ |\includegraphics{a.eps}| instead of |\includegraphics{a}|, then |
| 763 |
the graphics file need not exist at the time \LaTeX\ is used. (In |
| 764 |
particular it may be created on the fly by the \m{command} |
| 765 |
specified in the |\DeclareGraphicsRule| command described below.) |
| 766 |
\LaTeX\ does however need to be able to determine the size of the |
| 767 |
image so this size must be specified in arguments, or the `read file' |
| 768 |
must exist at the time \LaTeX\ is used. |
| 769 |
|
| 770 |
\begin{decl} |
| 771 |
|\DeclareGraphicsRule|\arg{ext}\arg{type}\arg{read-file}\arg{command} |
| 772 |
\end{decl} |
| 773 |
Any number of these declarations can be made. They determine how the |
| 774 |
system behaves when a file with extension \emph{ext} is specified. |
| 775 |
(The extension may be specified explicitly or, if the argument to |
| 776 |
|\includegraphics| does not have an extension, it may be a default |
| 777 |
extension from the \emph{ext-list} specified with |
| 778 |
|\DeclareGraphicsExtensions|.) |
| 779 |
|
| 780 |
\emph{ext} is the file extension for which this rule applies. As a special |
| 781 |
case, \emph{ext} may be given as |*| to denote the default behaviour for |
| 782 |
all undeclared extensions (see the example below). |
| 783 |
|
| 784 |
\emph{type} is the `type' of file involved. All files of the same type |
| 785 |
will be input with the same internal command (which must be defined in |
| 786 |
a `driver file'). For example files with extensions |ps|, |eps|, |
| 787 |
|ps.gz| may all be classed as type |eps|. |
| 788 |
|
| 789 |
\emph{read-file} determines the extension of the file that should be |
| 790 |
read to determine size information. It may be the same as \emph{ext} |
| 791 |
but it may be different, for example |.ps.gz| files are not readable |
| 792 |
easily by \TeX, so you may want to put the bounding box information in |
| 793 |
a separate file with extension |.ps.bb|. If \emph{read-file} is empty, |
| 794 |
|{}|, then the system will not try to locate an external file for size |
| 795 |
info, and the size must be specified in the arguments of |
| 796 |
|\includegraphics|. If the driver file specifies a procedure for |
| 797 |
reading size files for \emph{type}, that will be used, otherwise the |
| 798 |
procedure for reading |eps| files will be used. Thus the size of |
| 799 |
bitmap files may be specified in a file with a PostScript style |
| 800 |
|%%BoundingBox| line, if no other specific format is available. |
| 801 |
|
| 802 |
As a special case |*| may be used to denote the |
| 803 |
same extension as the graphic file. This is mainly of use in |
| 804 |
conjunction with using |*| as the extension, as in that case the |
| 805 |
particular graphic extension is not known. For example |
| 806 |
\begin{verbatim} |
| 807 |
\DeclareGraphicsRule{*}{eps}{*}{} |
| 808 |
\end{verbatim} |
| 809 |
This would declare a default rule, such that all unknown extensions |
| 810 |
would be treated as EPS files, and the graphic file would be read for |
| 811 |
a BoundingBox comment. |
| 812 |
|
| 813 |
\emph{command} is usually empty, but if non empty it may hold \TeX{} code |
| 814 |
to modify the name of the file as passed to the back end file inclusion |
| 815 |
commands. Within this argument, |#1| may be |
| 816 |
used to denote the original filename. Very early releases of the |dvips| code |
| 817 |
used this mechanism to support compressed EPS files, however for some years |
| 818 |
dvips has directly supported uncompression. |
| 819 |
|
| 820 |
\subsection{Global setting of keys} |
| 821 |
|
| 822 |
Most of the \package{keyval} keys used in the \package{graphicx} package |
| 823 |
may also be set using the command |\setkeys| provided by the |
| 824 |
\package{keyval} package.% |
| 825 |
\footnote{\texttt{clip}, \texttt{scale} and \texttt{angle} may not be set via |
| 826 |
\texttt{\string\setkeys} prior to calling |
| 827 |
\texttt{\string\includegraphics}.} |
| 828 |
|
| 829 |
For instance, suppose you wanted all the files to be included in the |
| 830 |
current document to be scaled to 75\% of the width of the lines of text, |
| 831 |
then one could issue the following command:\\ |
| 832 |
|\setkeys{Gin}{width=0.75\textwidth}|\\ |
| 833 |
Here `|Gin|' is the name used for the \package{keyval} keys associated |
| 834 |
with `Graphics inclusion'. All following |
| 835 |
|\includegraphics| commands (within the same group or environment) will |
| 836 |
act as if |[width=0.75\textwidth]| had been specified, in addition to |
| 837 |
any other key settings actually given in the optional argument. |
| 838 |
|
| 839 |
Similarly to make all |\rotatebox| arguments take an argument in |
| 840 |
radians, one just needs to specify:\\ |
| 841 |
|\setkeys{Grot}{units=6.28318}| |
| 842 |
|
| 843 |
\subsection{Compatibility between \package{graphics} and |
| 844 |
\package{graphicx}} |
| 845 |
|
| 846 |
For a document author, there are not really any problems of |
| 847 |
compatibility between the two packages. You just choose the interface |
| 848 |
that you personally prefer, and then use the appropriate package. |
| 849 |
|
| 850 |
For a package or class writer the situation is slightly |
| 851 |
different. Suppose that you are writing a letter class that needs to |
| 852 |
print a company logo as part of the letterhead. |
| 853 |
|
| 854 |
As the author of the class you may want to give the users the |
| 855 |
possibility of using either interface in their letters (should they |
| 856 |
need to include any further graphics into the letter body). |
| 857 |
In this case the class should load the \package{graphics} package (not |
| 858 |
\package{graphicx}, as this would commit any users of the class to the |
| 859 |
\package{keyval} interface). The logo should be included with |
| 860 |
|\includegraphics| either with \emph{no} optional argument (if the |
| 861 |
correct size information is in the file) or \emph{both} optional |
| 862 |
arguments otherwise. |
| 863 |
Do not use the \emph{one} optional argument form, as the meaning of this |
| 864 |
argument would change (and generate errors) if the user were to load |
| 865 |
\package{graphicx} as well as your class. |
| 866 |
|
| 867 |
\section{Remaining packages in the graphics bundle} |
| 868 |
|
| 869 |
\subsection{Epsfig} |
| 870 |
This is a small package, essentially a `wrapper' around the |
| 871 |
\package{graphicx} package, defining a command |\psfig| which has the |
| 872 |
syntax\\ |
| 873 |
|\psfig{file=xxx,...}| rather than |\includegraphics[...]{xxx}|.\\ |
| 874 |
It also has a few more commands to make it slightly more compatible with |
| 875 |
the old \LaTeX~2.09 style of the same name. |
| 876 |
|
| 877 |
\subsection{Rotating} |
| 878 |
An extension package to \package{graphicx}, mainly used for providing |
| 879 |
rotated float environments. |
| 880 |
|
| 881 |
\subsection{Trig} |
| 882 |
The trig package is not intended to be used directly in documents. It |
| 883 |
calculates sine, cosine and tangent trigonometric functions. These |
| 884 |
are used to calculate the space taken up by a rotated box. This |
| 885 |
package is also used by the |fontinst| program which converts |
| 886 |
PostScript files to a form usable by \TeX. |
| 887 |
|
| 888 |
As well as being used as a \LaTeX\ package, the macros may be extracted |
| 889 |
with the \package{docstrip} options \texttt{plain,package}. In this case |
| 890 |
the \LaTeX\ package declarations are omitted from the file, and the |
| 891 |
macros may be directly used as part of another macro file (they work |
| 892 |
with any format based on plain \TeX). |
| 893 |
|
| 894 |
\subsection{Keyval} |
| 895 |
The \package{keyval} package is intended to be used by other |
| 896 |
packages. It provides a generic way of setting `keys' as used by the |
| 897 |
\package{graphicx} package, and splitting up the comma separated lists |
| 898 |
of \m{key}~=~\m{value} pairs. |
| 899 |
|
| 900 |
Like the \package{trig} package, these macros may be extracted and used |
| 901 |
as part of another macro file, based on plain \TeX, as well as the |
| 902 |
standard use as a \LaTeX\ package. |
| 903 |
|
| 904 |
By default an undeclared key will generate an error. |
| 905 |
If however the option \texttt{unknownkeysallowed} is used, then |
| 906 |
unknown keys will be silently ignored (leaving a message in the log |
| 907 |
file). This option is also accepted by the \textsf{graphicx} package. |
| 908 |
|
| 909 |
\iffalse |
| 910 |
|
| 911 |
\subsection{Pstcol} |
| 912 |
\package{PSTricks}, by Timothy Van Zandt is an immensely powerful |
| 913 |
package that enables a very full featured interface between PostScript |
| 914 |
and \TeX. Unfortunately the colour support in \package{PSTricks} is |
| 915 |
slightly incompatible with the colour mechanism defined in the |
| 916 |
\package{color} package. The \package{pstcol} package is a (hopefully |
| 917 |
temporary) package that modifies a very small number of internal |
| 918 |
PSTricks functions, to remove this incompatibility. If |
| 919 |
\package{pstricks} is loaded via this package, you may use any colours |
| 920 |
defined by \package{color} package commands within \package{pstricks} |
| 921 |
commands, and vice versa. |
| 922 |
|
| 923 |
\fi |
| 924 |
|
| 925 |
\subsection{Lscape} |
| 926 |
The \package{lscape} package requires and takes the same options |
| 927 |
as the \package{graphics} package. It defines a |landscape| environment |
| 928 |
within which page bodies are rotated through 90 degrees. The page head |
| 929 |
and foot are not affected, they appear in the standard (portrait) |
| 930 |
position. |
| 931 |
\end{document} |