The graphicx package^{∗}

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

1994/11/29

1 Introduction

This package provides an alternative interface to the L^{A}TEX 2ε graphics functions. The command names provided are the same as in the standard package, and they use the same internal functions. However the meaning of the optional arguments is different. Note only the optional arguments have changed: any document which only uses the graphics commands with the mandatory arguments and/or the starforms will work identically (with essentially identical implementation) with the two packages.

2 Key=Value Interface

When the decision to produce L^{A}TEX 2ε was made, certain ‘guiding principles’ were made (and published in the original announcement). One of these was that all new features would ‘conform to the conventions of version 2.09’. Specifically this meant that new commands would obey the same basic syntax rules for arguments as the existing commands.

Standard L^{A}TEX optional arguments are positional if a command were to take three optional arguments, then there would be no way of specifying only the third, one would have to give all three, even if the first two were repeats of the default values. Basically this means that ‘standard’ optional arguments are not suitable if there is more than one option. Various existing packages (for L^{A}TEX 2.09) have recognised this, and used ‘named arguments’ in various forms. Perhaps teh two most noticeable are psfig and pstricks. With ‘named arguments’ (sometimes called ‘attributes’) each option is not tied to a particular position, but rather given a name (or key) and any options that must be set are set by explicitly associating this name with the desired value.

The members of the L^{A}TEX3 project do appreciate the importance of this kind of syntax, but felt that rather than extending the syntax of L^{A}TEX in an uncoordinated way, it would be better to keep with ‘standard arguments’ in L^{A}TEX 2ε, which is intended as a ‘consolidation of existing L^{A}TEX variants’. The long term planning for an eventual L^{A}TEX3 release will then be able to consider the whole L^{A}TEX user interface, and a suitable syntax for named arguments. It is important that such an interface design is not hampered by having to retain compatibility with earlier attempts at a named argument syntax. For this reason this graphicx package, which uses the named argument mechanism from the keyval package should be considered ‘non standard’ although it is supported by the same mechanism, and same authors as the ‘standard’ graphics package.

∗This file has version number v0.5a, last revised 1994/11/29.

3 The User Interface

\includegraphics *[key-val list]{file}
\includegraphics *[llx,lly][urx,ury]{file}

Include a graphics file.

The star form is just for compatibility with the standard interface, and essentially just adds clip to the keys specified. Similarly the second, two-optional argument form is for increased compatibility with the standard package. The two optional argument form is not needed in the keyval interface.

Various ‘keys’ or named arguments are supported.

bb Set the bounding box. The argument should be four dimensions, separated by spaces.

bbllx,bblly,bburx,bbury Set the bounding box. Mainly for compatibility with older packages. bbllx=a,bblly=b,bburx=c,bbury=d is equivalent to

     bb = a b c d.

natwidth,natheight Again an alternative to bb. natheight=h,natwidth=w is eqivalent to bb = 0 0 h w.

angle Rotation angle.

width Required width, a dimension (default units bp). The graphic will be scaled to make the width the specified dimension.

height Required height. a dimension (default units bp).

scale Scale factor.

clip Either ‘true’ or ‘false’ (or no value, which is equivalent to ‘true’). Clip the graphic to the bounding box.

draft a boolean valued key, like ‘clip’. locally switches to draft mode, ie. do not include the graphic, but leave the correct space, and print the filename.

type Specify the file type. (Normally determined from the file extension.)

ext Specify the file extension, for use with type.

read Specify the ‘read file’ which is used for determining the size of the graphic. For use with type.

command Specify the file command, for use with type.

The arguments are interpreted left to right. clip, draft, bb,, and llx etc have the same effect wherever they appear. but the scaling and rotation keys interact.

Any scaling that is specified before rotation, is handled by the internal graphics inclusion function. rotation, or any later scaling is handled by implicitly calling

\rotatebox or \scalebox. So [height=1in,angle=90] scales the graphic to 1in,

then rotates it, so it is one inch wide. [angle=90,height=1in] first rotates, then scales the result so that it is 1in high. A driver that can scale included graphics, but not arbitrary text will not be able to support the second form, as it will require a call to \scalebox, but the first form should work as there the scaling is handled

by \Ginclude@graphics.

\rotatebox [key-val list]{text}

Rotate text.

The keys supported by \rotatebox are:

origin Specify the centre of rotation. origin=⟨label⟩, where the labels are up to two of lrctbB (B denotes the baseline, as for PSTricks).

x,y An alternative to origin. x=⟨dimen⟩,y=⟨dimen⟩ The x, y coordinate of the centre of rotation. As usual \height etc may be used.

units Specify the units used in the main argument. eg units=-360 would mean that the argument refered to degrees clockwise instead of the default anticlockwise rotation.

As an example \rotatebox[origin=c]{text} will rotate “text” around its centre, thus creating a final box of the same dimensions as the original box. This is to be contarsted to the default behaviour, which rotates around the reference point on the baseline, thus producing a box that is mainly below the baseline.