Dvips supports inclusion of PostScript figure files (e.g., Encapsulated PostScript), downloading other header files (e.g., fonts), including literal PostScript code, and hypertext.
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 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.
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
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 to the same value it had before the macro
was called.
\hsize. (In LaTeX, use \textwidth
instead of \hsize.)
\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),
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
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:
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.
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.
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:
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.
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.
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.
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.
\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}
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.
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.
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/}.
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 fonts/postscript/paradissa
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.
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:
\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.)
\special{html:<a name="#paradise">}Paradise\special{html:</a>}
is exactly where you are right now.
This will resolve an `href="paradise"'.
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.