# Interaction with PostScript

## PostScript figures

Scaling and including PostScript graphics is a breeze--if the PostScript file is correctly formed. Even if it is not, however, the file can usually be accommodated with just a little more work.

### The bounding box comment

The most important feature of a good PostScript file from the standpoint of including it in another document is an accurate bounding box comment. Every well-formed PostScript file has a comment describing where on the page the graphic is located, and how big that graphic is.

This information is given as the lower left and upper right corners of the box just enclosing the graphic, and is thus referred to as the bounding box. These coordinates are given in the default PostScript units (there are precisely 72 PostScript units to the inch, like TeX big points) with respect to the lower left corner of the sheet of paper.

To see if a PostScript file has a bounding box comment, just look at the first few lines of the file. PostScript files are standard ASCII, so you can use any text editor to do this. If within the first few dozen lines there is a line like

%%BoundingBox: 25 50 400 300


(with any reasonable numbers), chances are very good that the file is Encapsulated PostScript and will work easily with Dvips. If the file contains instead a line like

%%BoundingBox: (atend)


the file is still probably Encapsulated PostScript, but the bounding box is given at the end of the file. Dvips needs it at the beginning. You can move it with that same text editor, or a simple script. (The bounding box is given in this way when the program that generated the PostScript couldn't know the size in advance, or was too lazy to compute it.)

If the document lacks a %%BoundingBox:' altogether, you can determine one in a couple of ways. One is to use the bbfig' program distributed with Dvips in the contrib' directory. This can usually find the correct bounding box automatically; it works best with Ghostscript.

If the comment looks like this:

%%BoundingBox: 0 0 612 792


the graphic claims to take up an entire sheet of paper. This is usually a symptom of a bug in the program that generated it.

The other is to do it yourself: print the file. Now, take a ruler, and make the following measurements (in PostScript units, so measure in inches and multiply by 72): From the left edge of the paper to the leftmost mark on the paper is llx, the first number. From the bottom edge of the paper to the bottommost mark on the paper is lly, the second number. From the left edge of the paper to the rightmost mark on the paper is urx, the third number. The fourth and final number, ury, is the distance from the bottom of the page to the uppermost mark on the paper.

Once you have the numbers, add a comment of the following form as the second line of the document. (The first line should already be a line starting with the two characters %!'; if it is not, the file probably isn't PostScript.)

%%BoundingBox: llx lly urx ury


Or, if you don't want to modify the file, you can simply write these numbers down in a convenient place and give them in your TeX document when you import the graphic, as described in the next section.

If the document does not have such a bounding box, or if the bounding box is given at the end of the document, or the bounding box is wrong, please complain to the authors of the software package that generated the file.

### Using the EPSF macros

Once the figure file has a bounding box comment (see the previous section,) you are ready it the graphic into a TeX document. Many packages for using EPS files exist. One distributed with Dvips is the files epsf.tex' (for plain TeX) and epsf.sty' (for LaTeX). For plain TeX, add a line like this near the top of your input file:

\input epsf


If you are using LaTeX 2e, use the graphics' or graphicx' package. If you are using LaTeX 2.09, add the epsf' style option, as in:

\documentstyle[12pt,epsf]{article}


In any case, the above only needs to be done once, no matter how many figures you plan to include.

Now, at the point you want to include a file, enter a line such as:

\epsffile{foo.eps}


If you are using LaTeX, you may need to add \leavevmode immediately before the \epsffile command to get certain environments to work correctly. If your file does not have a bounding box comment, you can supply the numbers as determined in the previous section, in the same order they would have been in a normal bounding box comment:

\epsffile[100 100 500 500]{foo.ps}


Now, save your changes and run TeX and Dvips; the output should have your graphic positioned at precisely the point you indicated, occupying the proper amount of space.

The \epsffile macro typesets the figure as a TeX \vbox at the point of the page that the command is executed. By default, the graphic will have its natural' width (namely, the width of its bounding box). The TeX box will have depth zero and its natural height. By default, the graphic will be scaled by any DVI magnification in effect, just as is everything else in your document. See the next section for more information on scaling.

If you want TeX to report the size of the figure as a message on your terminal when it processes each figure, give the command:

\epsfverbosetrue


#### EPSF scaling

Usually, you will want to scale an EPSF figure to some size appropriate for your document, since its natural size is determined by the creator of the EPS file.

The best way to do this is to assign the desired size to the TeX \epsfxsize or \epsfysize variables, whichever is more convenient for you. That is, put

\epsfxsize=dimen


right before the call to \epsffile. Then the width of the TeX box will be dimen and its height will be scaled proportionately. Similarly, you can set the vertical size with

\epsfysize=dimen


in which case the height will be set and the width scaled proportionally.

If you set both, both will be honored, but the aspect ratio of the included graphic may necessarily be distorted, i.e., its contents stretched in one direction or the other.

You can resize graphics in a more general way by redefining the \epsfsize macro. \epsffile calls this with two parameters: the natural horizontal and vertical sizes of the PostScript graphic. \epsfsize must expand to the desired horizontal size, that is, the width of the \vbox. Schematically:

\def\epsfsize#1#2{body}


Some useful definitions of body:

\epsfxsize'
This definition (the default) enables the default features listed above, by setting \epsfxsize to the same value it had before the macro was called.
#1'
Force the natural size by returning the first parameter (the original width).
0pt'
A special case, equivalent to #1'.
0.5#1'
Scale to half the natural size.
\hsize'
Scale to the current \hsize. (In LaTeX, use \textwidth instead of \hsize.)
\ifnum#1>\hsize\hsize\else#1\fi'
If the natural width is greater than the current \hsize, scale to \hsize, otherwise use the natural width.

For compatibility with other PostScript drivers, it is possible to turn off the default scaling of included figures by the DVI magnification with the following TeX command:

\special{! /magscale false def}


Use of this command is not recommended because it will make the \epsffile graphics the "wrong" size if global magnification is being used, and it will cause any PostScript graphics to appear improperly scaled and out of position if a DVI to DVI program is used to scale or otherwise modify the document.

DVI magnification is not applied to any output from code you write in bop-hook' or its ilk (see section PostScript hooks),

#### EPSF clipping

By default, clipping is disabled for included EPSF images. This is because clipping to the bounding box dimensions often cuts off a small portion of the figure, due to slightly inaccurate bounding box arguments. The problem might be subtle; lines around the boundary of the image might be half their intended width, or the tops or bottoms of some text annotations might be sliced off. If you want to turn clipping on, just use the command

\epsfclipon


and to turn clipping back off, use

\epsfclipoff


### psfile' special

The basic special for file inclusion is as follows:

\special{psfile=filename.ps [key=value] ... }


This downloads the PostScript file filename.ps' such that the current point will be the origin of the PostScript coordinate system. The optional key=value assignments allow you to specify transformations on the PostScript.

The possible keys are:

hoffset'
The horizontal offset (default 0)
voffset'
The vertical offset (default 0)
hsize'
The horizontal clipping size (default 612)
vsize'
The vertical clipping size (default 792)
hscale'
The horizontal scaling factor (default 100)
vscale'
The vertical scaling factor (default 100)
angle'
The rotation (default 0)
clip'
Enable clipping to the bounding box

The dimension parameters are all given in PostScript units. The hscale' and vscale' are given in non-dimensioned percentage units, and the rotation value is specified in degrees. Thus

\special{psfile=foo.ps hoffset=72 hscale=90 vscale=90}


will shift the graphics produced by file foo.ps' right by one inch and will draw it at 0.9 times normal size. Offsets are given relative to the point of the special command, and are unaffected by scaling or rotation. Rotation is counterclockwise about the origin. The order of operations is to rotate the figure, scale it, then offset it.

For compatibility with older PostScript drivers, it is possible to change the units that hscale' and vscale' are given in. This can be done by redefining @scaleunit' in SDict' by a TeX command such as

\special{! /@scaleunit 1 def}


The @scaleunit' variable, which is by default 100, is what hscale' and vscale' are divided by to yield an absolute scale factor.

### Dynamic creation of PostScript graphics files

PostScript is an excellent page description language--but it does tend to be rather verbose. Compressing PostScript graphics files can reduce them by factor of five or more. For this reason, if the name of an included PostScript file ends with .Z' or .gz', Dvips automatically runs gzip -d'. For example:

\epsffile[72 72 540 720]{foo.ps.gz}


Since the results of such a command are not accessible to TeX, if you use this facility with the epsf' macros, you need to supply the bounding box parameter yourself, as shown.

More generally, if the filename parameter to one of the graphics inclusion techniques starts with a left quote ('), the parameter is instead interpreted as a command to execute that will send the actual file to standard output. For example:

\special{psfile="gnuplot foo"}


to include the file foo'. Of course, the command to be executed can be anything, including using a file conversion utility such as tek2ps' or whatever is appropriate. This feature can be disabled with the -R' command-line option or R' configuration option.

### Fonts in figures

You can use any font available to TeX and Dvips within a graphics file by putting a %*Font: line in the leading commentary of the file. Schematically, this looks like:

%*Font: tfmname scaledbp designbp hex-start:hex-bitstring


Here is the meaning of each of these elements:

tfmname
The TeX TFM filename, e.g., cmr10'. You can give the same tfmname on more than one %*Font' line; this is useful when the number of characters from the font used needs a longer hex-bitstring (see item below) than conveniently fits on one line.
scaledbp
The size at which you are using the font, in PostScript points (TeX big points). 72bp = 72.27pt = 1in.
designbp
The designsize of the font, again in PostScript points. This should match the value in the TFM file tfmname. Thus, for cmr10', it should be 9.96265'.
hex-start
The character code of the first character used from the font, specified as two ASCII hexadecimal characters, e.g., 4b' or 4B' for K'.
hex-bitstring
An arbitrary number of ASCII hexadecimal digits specifying which characters following (and including) hex-start are used. This is treated as a bitmap. For example, if your figure used the single letter K', you would use 4b:8' for hex-start and hex-bitstring. If it used KLMNP', you would use 4b:f4'.

MetaPost's output figures contain lines like this for bitmap fonts used in a MetaPost label (see section MetaPost' in Web2c).

Header files are bits of PostScript included in the output file; generally they provide support for special features, rather than producing any printed output themselves. You can explicitly request downloading header files if necessary for some figure, or to achieve some special effect.

Dvips includes some headers on its own initiative, to implement features such as PostScript font reencoding, bitmap font downloading, handling of \special's, and so on. These standard headers are the .pro' files (for "prologue") in the installation directory \$(psheaderdir)'; they are created from the .lpro' ("long prologue") files in the distribution by stripping comments, squeezing blank lines, etc., for maximum efficiency. If you want to peruse one of the standard header files, read the .lpro' version.

The PostScript dictionary stack will be at the userdict' level when header files are included.

In order to get a particular graphic file to work, a certain font or header file might need to be sent first. The Dvips program provides support for this with the header' \special. For instance, to ensure that foo.ps' gets downloaded:

\special{header=foo.ps}


As another example, if you have some PostScript code that uses a PostScript font not built into your printer, you must download it to the printer. If the font isn't used elsewhere in the document, Dvips can't know you've used it, so you must include it in the same way, as in:

\special{header=putr.pfa}


to include the font definition file for Adobe Utopia Roman.

### Including headers from the command line

You can include headers when you run Dvips, as well as from your document (see the previous section). To do this, run Dvips with the option -P header'; this will read the file config.header', which in turn can specify a header file to be downloaded with the h' option. See section Configuration file commands. These files are called header.cfg' on MS-DOS.

You can arrange for the same file to serve as a -P' config file and the downloadable header file, by starting the lines of PostScript code with a space, leaving only the h' line and any comments starting in the first column. As an example, see contrib/volker/config.*' (contrib/volker/*.cfg' on MS-DOS). (These files also perform useful functions: controlling duplex/simplex mode on duplex printers, and setting various screen frequencies; contrib/volker/README' explains further.)

Dvips tries to avoid overflowing the printer's memory by splitting the output files into "sections" (see the -i' option in section Option details). Therefore, for all header files, Dvips debits the printer VM budget by some value. If the header file has, in its leading commentary a line of the form

%%VMusage: min max


then max is used. If there is no %%VMusage line, then the size (in bytes) of the header file is used as an approximation.

Illustrations (figure files) are also checked for %%VMusage line.

## Literal PostScript

You can include literal PostScript code in your document in several ways.

### " special: Literal PostScript

For simple graphics, or just for experimentation, literal PostScript code can be included. Simply use a \special beginning with a double quote character "'; there is no matching closing "'.

For instance, the following (simple) graphic:

was created by typing:

\vbox to 100bp{\vss % a bp is the same as a PostScript unit
\special{" newpath 0 0 moveto 100 100 lineto 394 0 lineto
closepath gsave 0.8 setgray fill grestore stroke}}


You are responsible for leaving space for such literal graphics, as with the \vbox above.

### ps' special

Generally, Dvips encloses specials in a PostScript save/restore pair, guaranteeing that the special will have no effect on the rest of the document. The ps' special, however, allows you to insert literal PostScript instructions without this protective shield; you should understand what you're doing (and you shouldn't change the PostScript graphics state unless you are willing to take the consequences). This command can take many forms because it has had a torturous history; any of the following will work:

\special{ps:text}
\special{ps::text}
\special{ps::[begin]text}
\special{ps::[end]text}


(with longer forms taking precedence over shorter forms, when they are present). ps::' and ps::[end]' do no positioning, so they can be used to continue PostScript literals started with ps:' or ps::[begin]'.

\special{ps: plotfile filename}


inserts the contents of filename verbatim into the output (except for omitting lines that begin with %). An example of the proper use of literal specials can be found in the file rotate.tex', which makes it easy to typeset text turned in multiples of 90 degrees.

### Literal headers: !' \special

You can download literal PostScript header code in your TeX document, for use with (for example) literal graphics code that you include later. The text of a \special beginning with an !' is copied into the output file. A dictionary SDict will be current when this code is executed; Dvips arranges for SDict to be first on the dictionary stack when any PostScript graphic is included, whether literally (the "' special) or through macros (e.g., epsf.tex').

For example:

\special{! /reset { 0 0 moveto} def}


### PostScript hooks

Besides including literal PostScript at a particular place in your document (as described in the previous section), you can also arrange to execute arbitrary PostScript code at particular times while the PostScript is printing.

If any of the PostScript names bop-hook, eop-hook, start-hook, or end-hook are defined in userdict, they will be executed at the beginning of a page, end of a page, start of the document, and end of a document, respectively.

When these macros are executed, the default PostScript coordinate system and origin is in effect. Such macros can be defined in headers added by the -h' option or the header=' special, and might be useful for writing, for instance, DRAFT' across the entire page, or, with the aid of a shell script, dating the document. These macros are executed outside of the save/restore context of the individual pages, so it is possible for them to accumulate information, but if a document must be divided into sections because of memory constraints, such added information will be lost across section breaks.

The single argument to bop-hook is the physical page number; the first page gets zero, the second one, etc. bop-hook must leave this number on the stack. None of the other hooks are passed arguments.

As an example of what can be done, the following special will write a light grey DRAFT' across each page in the document:

\special{!userdict begin /bop-hook{gsave 200 30 translate
65 rotate /Times-Roman findfont 216 scalefont setfont
0 0 moveto 0.7 setgray (DRAFT) show grestore}def end}


Using bop-hook or eop-hook to preserve information across pages breaks compliance with the Adobe document structuring conventions, so if you use any such tricks, you may also want to use the -N' option to turn off structured comments (such as %%Page'). Otherwise, programs that read your file will assume its pages are independent.

### Literal examples

To finish off this section, the following examples of literal PostScript are presented without explanation:

\def\rotninety{\special{ps:currentpoint currentpoint translate 90
rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept
\setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0
\special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety
\box0\special{ps:grestore}}\vskip16truept

\vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in
width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big
\vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt
\line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}%
\hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss}


Some caveats are in order, however. Make sure that each gsave is matched with a grestore on the same page. Do not use save and restore; they can interact with the PostScript generated by Dvips if care is not taken. Try to understand what the above macros are doing before writing your own. The \rotninety macro especially has a useful trick that appears again and again.

## HyperTeXt

Dvips has support for producing hypertext PostScript documents. If you specify the -z' option, the html:' specials described below will be converted into pdfmark' PostScript operators to specify links. Without -z', html:' specials are ignored.

The resulting PostScript can then be processed by a distiller program to make a PDF file. (It can still be handled by ordinary PostScript interpreters as well.) Various versions of both PC and Unix distillers are supported; Ghostscript includes limited distiller support (see section Ghostscript installation).

Macros you can use in your TeX document to insert the specials in the first place are available from CTAN:/support/hypertex'. For CTAN info, see section unixtex.ftp' in Kpathsea.

This hypertext support (and original form of the documentation) was written by Mark Doyle and Tanmoy Bhattacharya as the dvihps' program. You can retrieve their software and additional documentation via the CTAN reference above. You may also be interested in the Java previewer IDVI, available at @url{http://www.win.tue.nl/~dickie/idvi}, and/or in @url{http://www.emrg.com/texpdf.html}, which describes the process of making PDF files from TeX files in more detail.

Mail archives for the original project are at @url{http://math.albany.edu:8800/hm/ht/}.

### Hypertext caveats

If you intend to go all the way to PDF, you will probably want to use PostScript fonts exclusively, since the Adobe PDF readers are extremely slow when dealing with bitmap fonts. Commercial versions of the Computer Modern fonts are available from Blue Sky; public domain versions are available from CTAN sites (for CTAN info, see section unixtex.ftp' in Kpathsea) in:

fonts/postscript/bakoma


You may need to modify these fonts; see @url{http://xxx.lanl.gov/faq/bakoma.html}.

Also, the Adobe distillers prior to 2.1 drop trailing space characters (character code 32) from strings. Unfortunately, the PostScript fonts use this character code for characters other than space (notably the Greek letter psi in the Symbol font), and so these characters are dropped. This bug is fixed in version 2.1.

If you can't upgrade, One workaround is to change all the trailing blanks in strings to a character code that isn't in the font. This works because the default behavior is to substitute a blank for a missing character, i.e., the distiller is fooled into substituting the right character. For instance, with the Blue Sky fonts, you can globally replace  )' with \200)' (with sed, for example) and get the desired result. With the public domain fonts, you will probably have to use a character code in the range 128 to 191 since these fonts duplicate the first 32 characters starting at 192 to avoid MS-DOS problems.

### Hypertext specials

Current support for the World Wide Web in the TeX system does not involve modifying TeX itself. We need only define some specials; Arthur Smith (@email{apsmith@aps.org}), Tanmoy Bhattacharya, and Paul Ginsparg originally proposed and implemented the following:

html:<a href="xurl">
html:<a name="name">
html:</a>
html:<img src="xurl">
html:<base href="xurl">


Like all TeX \special's, these produce no visible output, and are uninterpreted by TeX itself. They are instructions to DVI processors only.

Here, xurl is a standard WWW uniform resource locator (URL), possibly extended with a #type.string' construct, where type is page', section', equation', reference' (for bibliographic references), figure', table', etc. For example,

\special{html:<a href="http://www.maths.tcd.ie/~tim/ch1.dvi#equation.1.1">}


is a link to equation (1.1) in an example document by Tim Murphy.

See @url{http://www.w3.org/hypertext/WWW/Addressing/Addressing.html} for a precise description of base URL's. (That itself is a URL, in case you were wondering.)

Descriptions of the \special's:

href'
\special{html:<a href="http://www.tug.org/">}\TeX\ Users
Group\special{html:</a>}

The user will be able to click on the text TeX Users Group' while running Xdvi and get to the TUG home page. (By the way, this is for illustration. In practice, you most likely want to use macros to insert the \special commands; reference above.)
name'
Defines URL targets in your TeX documents, so links can be resolved. For example:
\special{html:<a name="#paradise">}Paradise\special{html:</a>}
is exactly where you are right now.

This will resolve an href="paradise"'.
img'
Links to an arbitrary external file. Interactively, a viewer is spawned to read the file according to the file extension and your mailcap' file (see the Xdvi documentation).
base'
Defines a base URL that is prepended to all the name targets. Typically unnecessary, as the name of the DVI file being read is used by default.

The img' and base' tags are not yet implemented in Dvips or the NeXTSTEP DVI viewer.