The graphics package^{∗}

D. P. Carlisle  S. P. Q. Rahtz

1994/12/15

1 Introduction

This package implements various ‘graphics’ functions. The main features are a) inclusion of ‘graphics’ files. b) Rotation of sections of the page, c) Scaling of sections of the page.

The design is split into three ‘levels’.

• The user interface. This is the collection of commands designed to appear in a document text. Actually two separate user interface have been implemented. The ‘standard’ interface, described here, and a more powerful, and more ‘user-friendly’ interface provided by the graphicx package.

• The core functions. These functions, which are also implemented in this file do all the ‘main work’. the ‘user-interface functions just collect together the information from any optional-arguments or star-forms, and then call one of these functions.

• The driver files. All the functionns provided by this package are not possible to achieve just using TEX. The dvi driver used must be given additional instructions. (Using the \special command of TEX.) Unfortunately, the capabilities of various drivers differ, and the syntax required to pass instructions to the derivers is also not standardised. So the ‘core functions’ never acces \special directly, but rather call a series of commands that must be defined in a special file customised for each driver. The accompanying file, drivers.dtx has suitable files for a range of popular drivers.

2 Package Options

Most of the options, such as dvips, textures etc., specify the driver that is to be used to print the document. You may wish to set up a configuration file so that this option always takes effect, even if not specified in the document. To do this, produce a file graphics.cfg containing the line:

\ExecuteOptions{dvips}

(or whichever other driver you wish.)

Apart from the driver options there are a few other options to control the behaviour of the package. draft

∗This file has version number v0.6c, last revised 1994/12/15.

final

debugshow

hiderotate

hidescale

3 Standard Interface

3.1 Graphics Inclusion

\includegraphics *[llx,lly][urx,ury]{file}

Include a graphics file.

If * is present, then the graphic is ‘clipped’ to the size specified. If * is omitted, then any part of the graphic that is outside the specified ‘bounding box’ will overprint 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. If [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 ommited 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 [llx,lly] may be used to specify the cordinates of this point.

\graphicspath {dir-list}

This optional declaration may be used to specify a list of directories in which to search for graphics files. The format is as for the L^{A}TEX 2ε 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. The default setting of this path is \input@path that is: graphics files will be found wherever TEX files are found.

\DeclareGraphicsExtensions {ext-list}

This specifies the behaviour of the system when argument to \includegraphics does not have an extension specified. {ext-list} should be a comma separated list of file extensions. A file name is produced by appending sep and one extension. If a file is found, the system acts as if that extension had been specified. If not, the next extension in ext-list is tried.

Earlier versions of this package defined a default argument for this command. This has been removed.

\DeclareGraphicsRule {ext}{type}{read-file}{command}

Any number of these declarations can be made. they determine how the system behaves when a file with extension 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 ext-list specified with

\DeclareGraphicsExtensions.)

ext is the extension of the file. Any file with this extension will be processed by this graphics rule. Normally a file with an extension for which no rule has been declared will generate an error, however you may use * as the extension to define a default rule, for instance the dvips driver file declares all files to be of type eps unless a more specific rule is declared.

Since Version v0.6, extensions should be specified including the . that is, .eps not eps.

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.

read-file determines the extension of the file that should be read to determine size information. It may be the same as 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 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. As a special case * may be used to denote the same extension as the graphic file. This is mainly of use in conjuction with using * as the extension, as in that case the particular graphic extension is not known. For example

 \DeclareGraphicsRule{*}{eps}{*}{}

This would decalare 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.

If the driver file specifies a procedure for reading size files for 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.

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

\DeclareGrahicsRule{.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.

3.2 Rotation

\rotatebox {angle}{text}

Rotate text angle degrees anti-clockwise. Normally the rotation is about the lefthand end of the baseline of text.

3.3 Scaling

\scalebox {h-scale}[v-scale]{text} Scale text by the specified ammounts. If v-scale is omitted, the vertical scale factor is the same as the horizontal one.

\resizebox *{h-length}{v-length}{text} Scale text so that the width is 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 v-length refers to the height of the box, but in the star form, it refers to the ‘height + depth’. As normal for L^{A}TEX 2ε box length arguments, \height, \width, \totalheight, \depth may be used to refer to the original size of the box.

4 The Key=Value Interface

As mentioned in the introcuction, apart from the above ‘standard interface’ there is an alternative synatx to the \includegraphicsand \rotatebox commands that some people may prefer. It is provided by the accompanying graphicx package.