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.
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.
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 reenabled with \psnoisy.
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.
DOCUMENTATION
For complete documentation on Psfig, you may print the PostScript file /vol/docs/TeX/psfig-doc.ps
The manual provides many examples with real-life PostScript graphics.
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