Psfig/TeX
Section: User Commands (1)
Index
Return to Main Contents
NAME
Psfig/TeX (1.10) - PostScript figures in TeX
SYNTAX
\input psfig
DESCRIPTION
Psfig/TeX
is a macro package for TeX, as well as LaTeX, that facilitates the
inclusion of PostScript figures into (La)TeX documents.
With the help of a compatible postprocessor, PostScript figures are
automatically scaled and positioned on the page, and the proper amount
of space is reserved.
Figures can be presented as traditional broken-out displays,
and Custom characters may be created and used freely throughout a document.
The dvips program developed by Tomas Rokicki has full
psfig support. The OzTeX package has support for
all psfig functions except compressed figures.
USAGE
To include a figure with psfig, include the psfig style at
the top of your document.
In LaTeX: ``\documentstyle[psfig,...]{article}''; in TeX:
``\input psfig''.
Then invoke the macro ``\psfig{figure=filename}'', where
filename is the name of a PostScript file.
Psfig
will automatically position the figure at the current
point on the page, and reserve the proper amount of space.
OPTIONS
Options may be specified in the form
``\psfig{figure=filename,option=value,option=value,...}'';
recognized options include height, width, rheight,
rwidth, clip, and angle.
- height
-
The ``height=dimen'' option specifies how tall the
figure should be on the page.
When no width is specified, the figure is scaled equally
in both dimensions.
- width
-
The ``width=dimen'' option specifies how wide the
figure should be on the page.
When no heigth is specified, the figure is scaled equally
in both dimensions.
-
If no height or width option is given, the figure's
`natural' size will be used.
By listing both a height and width, figures can be scaled
disproportionately.
- rheight
-
There are two sizes associated with each psfig figure: the size
at which it is to be printed on the page and the size it reserves
in TeX.
This latter size is appropriately termed the reserved size, and is
expressed as an option of the form ``rheight=dimen'',
to reserve a vertical size of dimen.
If omitted, the reserved size defaults to the real size.
Some special effects need to be transparent to TeX and thus have a
zero reserved size, such as a grey box enclosing a paragraph.
- rwidth
-
To reserve a width in TeX, the ``rwidth=dimen''
option is used.
- clip
-
The ``clip=t'' option sets the PostScript clipping path
so that no marks will show up outside the declared bounding box.
This option allows the user to isolate part of a larger figure,
by specifying a new bounding box:
``\psfig{figure=figs/piechart.ps,height=2in,bbllx=306bp,%
bblly=396bp,bburx=486bp,bbury=546bp,clip=}''
- angle
-
Figures can be rotated by psfig using the ``angle=degrees''
option.
Example:
``\psfig{figure=figs/rosette.ps,height=1.0in,angle=90}''.
AUTOSCALING
With autoscaling, some rotated figures come out smaller because the
diagonal of their bounding box is longer than their height
or width alone.
This behavior can be disabled with \psscalefirst, and re-enabled
with \psrotatefirst.
With \psscalefirst a new height and width are
computed after the bounding box.
While the rotated figures will all come out at the same size, their
reserved sizes will be different, thus they may not be aligned
correctly.
SOURCES OF FIGURES
Any PostScript program can be used as a
psfig figure, as long as it adheres to the
Encapsulated PostScript Format (EPSF), which
dictates a set of forbidden operators and a comment
structuring convention. Psfig
is actually less restrictive than the EPSF requirements; it can handle
some of the "non-compliant" postscript operators, and the only
required comment is the Bounding Box comment (see below).
BOUNDING BOXES
To properly translate and scale a figure psfig must know
its `natural' position on the page; this information is present
in the `bounding box comment' of a PostScript program.
This is a line of the form
``%%BoundingBox: bbllx bblly bburx bbury'' in the header of
the file.
The bounding box specifies four coordinates of a rectangle that
defines the outermost edges of the PostScript figure: the lower-left
x coordinate (bbllx), the lower-left y coordinate
(bblly), the upper-right x coordinate (bburx), and
the upper-right y coordinate (bbury).
This rectangle must be present in any file to be used as a
psfig figure.
Most modern graphics packages produce (encapsulated) PostScript
files which contain a ``%%BoundingBox:'' comment line in the header.
All bb... values are in points, relative to the default
transformation matrix.
MISSING BOUNDING BOX
When no bounding box comment line is present in your PostScript file,
you can edit one in.
The only mandatory PostScript convention is that the first line of
the file should begin with the characters `%!'.
A good place for the bounding box comment is the second line of
the file.
The bounding box values may also be specified directly in the
\psfig argument, using clauses of the form
``bbllx=bbllx,bblly=bblly,...'', in which case
the figure file is not searched for the bounding box.
To control the amount of white space around a figure in a (La)TeX
document, it may be necessary to experiment with the bounding box
parameters bb..., also in cases where the bounding box is
provided by the plot or graphics package.
DRAFT FIGURES
Some PostScript figures take quite a long time to transmit and print;
for these figures a draft mode is available to speed printing of draft
versions of the document.
A figure printed in draft mode will appear as an empty box.
The macro \psdraft will switch into draft mode, and all
subsequent psfig macros will produce draft figures until reaching
the macro \psfull, which switches out of draft mode.
No \special commands are used in draft mode, so a draft document
can be previewed using any DVI viewer.
The printing of boxes in draft mode can be disabled/enabled with
\psnodraftbox and \psdraftbox.
SILENT MODE
Normally, psfig will print advisory messages to remind you that it is
including figures as (La)TeX processes a document. This behavior can
be disabled with \pssilent, and re-enabled with \psnoisy.
COMPRESSED POSTSCRIPT FILES
As off version 1.9, psfig allows the inclusion of compressed
PostScript files (when using dvips).
To compress PostScript files, the shell script pscompress is used.
Pscompress produces two files: filename.bb and filename.Z.
The first file contains the bounding box comment only, while the second
file contains the actual compressed PostScript file.
Usage: ``% pscompress filename''.
When (La)TeX is run on your_document.tex, the file filename.bb
is scanned for the bounding box comment, to allow (La)TeX to properly
reserve the right size for the figure.
Only when the file your_document.dvi is printed by means of dvips,
the actual PostScript file filename.Z is decompressed (zcat-ed)
and included in your_document.ps.
MACINTOSH FIGURES
Since the Macintosh drawing applications produce PostScript, they can
be used to create figures.
However, the PostScript produced by most Macintosh applications is often
not well
suited to be included directly as a psfig figure, unless it is
saved as an "EPSF compliant" file. If the file is not "EPSF compliant"
then the postscript may have to be edited before being used
as an included figure. See the psfig tool cleanfig
and the sample document macdemo.tex for guidance.
Non-EPSF Macintosh PostScript files often
require a ``Laserprep'' prolog in order to
be properly printed.
A laserprep prolog can be included with the dvips special
header command at the top of your (La)TeX file:
``\special{header=lprep70.procs}''.
Psfig provides `lprep68.procs', as well as `lprep70.procs',
to suit various versions of the Macintosh applications.
FIGURE SEARCH PATH
Psfig first searches in the current directory for a figure (or
in the specified directory if given an absolute path). If it fails
to find the figure in the current directory, it optionally searches
a search path of figure directories to see if the figure is
present. To specify the figure search path, use
"\psfigurepath{dir1:dir2:...:dirn}",
where dir1...dirn are the directories figures are to be found in.
PROBLEMS
- Problem:
-
The page with graphics is not printed.
- Solution:
-
Remove lines containing `showpage' and/or `stop'
from the PostScript graphics file.
Lines of this kind are usually found near the end of the file.
- Problem:
-
The figure is positioned in weird places.
-
Generally, this is an indication that the PostScript ``%%BoundingBox:''
comment is missing.
It may also be that a translation takes places after the
bounding box was determined.
- Solution:
-
Edit a bounding box comment into the PostScript file
and/or experiment with the bb... values (see: MISSING BOUNDING
BOX above).
BUGS
The \psfig macro is (unfortunately) sensitive to whitespace,
and will be confused by any extra spaces or newlines in its argument.
The LaTeX letter style must be loaded after the
\psfig macros due to naming conflicts. This can be
forced by including psfig with an explicit \input
command before the \documentstyle command.
ACKNOWLEDGEMENTS
This work was done while the author was with the Department of
Computer and Information Science, University of Pennsylvania. Ned
Batchelder co-developed the original troff version of this
program with the author, and was responsible for much of the overall
design. For more detailed information on the original version of
see Psfig - A Ditroff Preprocessor for PostScript Figures in
the USENIX 87 proceedings, or Bringing troff up to speed in the
July 1987 issue of Unix Review.
Greg Hager provided the initial pure-TeX implementation of psfig.
J. Daniel Smith of Schlumberger CAD/CAM implemented the rotation
feature and improved the file scanning routines, using certain code
fragments from Tom Rokicki's dvips program.
Thanks to Sake Hogeveen (hogeveen.fys.ruu.nl) for editing this man page.
AUTHOR
Trevor Darrell
SEE ALSO
tex(1), latex(1), dvips(1), psfig-troff(1)
A printed version of the psfig-tex manual may be obtained by typing
``% latex psfig-doc'', then ``% dvips psfig-doc'',
and finally printing the resulting psfig-doc.ps file on your nearest
PostScript printer.
The manual provides many examples with real-life PostScript graphics,
see the text of psfig-doc.tex for more usage examples.
Index
- NAME
-
- SYNTAX
-
- DESCRIPTION
-
- USAGE
-
- OPTIONS
-
- AUTOSCALING
-
- SOURCES OF FIGURES
-
- BOUNDING BOXES
-
- MISSING BOUNDING BOX
-
- DRAFT FIGURES
-
- SILENT MODE
-
- COMPRESSED POSTSCRIPT FILES
-
- MACINTOSH FIGURES
-
- FIGURE SEARCH PATH
-
- PROBLEMS
-
- BUGS
-
- ACKNOWLEDGEMENTS
-
- AUTHOR
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 01:46:06 GMT, February 01, 2023