UIC Computer Center Document #3332005 6 Pages Psfig/TeX 1.2 Users Guide Trevor Darrell trevor@grasp.cis.upenn.edu Computer and Information Science University of Pennsylvania December 1, 1990 UIC Abstract This document describes the use of the Psfig/TeX system to include PostScript graphics in the documents you produce with LaTeX and TeX. Please note that in order to actually see the example graphics, you must print a copy of this docu- ment on a PostScript printer. The PostScript version of this document is available through INFORM and is also available on the TEX disk. To print a __________ PostScript copy with INFORM, use the INFORM 2700 printing option, PF14 on the _______________________________________________________________________________ INFORM reference lists. For most terminal types, type either Shift-F2 or _______________________ Escape w to execute PF14. To print the copy on the TEX disk, enter: GETDISK TEX PRINT PSFIGUG PS 1. INTRODUCTION The TeX typesetting system is a powerful tool in the preparation of the written word, yet when the time came to add figures or pictures to a document, one tra- ditionally had to resort to tedious manual paste-up. With the advent of the PostScript page description language, which allows the 'nesting' of environ- ments and is rapidly becoming a de facto standard, it is possible to merge graphics directly into a document. Psfig/TeX is a macro package for TeX that facilitates the inclusion of arbitrary PostScript figures into TeX documents.¶ Figures are automatically scaled and positioned on the page, and the proper amount of space is reserved. Some possible figures include: =========================== ¶ The Psfig/TeX macro package was developed for Unix and has been ported to CMS for use at UIC. This Users Guide has been slightly modified to reflect the CMS port. (1Dec90) Psfig/TeX 1.2 Users Guide page 2 =============================================================================== \par \hbox{ \hspace{.3in} \vbox{\psfig{figure=zip.ps}\vspace{.5in}} \psfig{figure=piechart.ps,height=1.5in} \vbox{\psfig{figure=starlines.ps}\vspace{.6in}} } \par Custom characters such as '\psfig{figure=pretzel.ps,height=8pt,silent=}' and '\psfig{figure=cm.ps,height=8pt,silent=}' may be created and used freely throughout a document. 2. SIMPLE FIGURES To include a PostScript figure with psfig, first load the psfig macros at the beginning of your document with \input{psfig} then, when you wish to include a figure, invoke the macro \psfig\{figure=input} where input is the name of a PostScript file. Psfig will automatically posi- tion the figure at the current point on the page, and reserve the proper amount of space in TeX so that it doesn't conflict with any other objects on the page. For example, if we have a file called 'piechart ps' which contains the Post- Script code to draw the chart in the introduction, we could use the commands \par \centerline\{\psfig\{figure=piechart.ps}} \par to include it as a centered paragraph. Since no mention of size was made in the above example, psfig draws the figure at its natural size (as if it was printed directly on a PostScript printer.) The pie's natural size is several inches across, which is a little large; the pie in the introduction was pro- duced with: \centerline{\psfig{figure=piechart.ps,height=1.5in}} The "height" option specifies how tall the figure should be on the page. Since no "width" was specified, the figure was scaled equally in both dimensions. By listing both a height and a width, figures can be scaled disproportionately, with interesting results. For example: ... a series of 5 distorted rosettes ... was produced with: Psfig/TeX 1.2 Users Guide page 3 =============================================================================== \centerline{\hbox{ \psfig{figure=rosette.ps,height=.8in,width=.15in} \psfig{figure=rosette.ps,height=.8in,width=.35in} \psfig{figure=rosette.ps,height=.8in} \psfig{figure=rosette.ps,height=.8in,width=1.2in} \psfig{figure=rosette.ps,height=.8in,width=1.5in} }} =============================================================================== Figure 1: A figure produced by MacDraw \centerline{ \psfig{figure=lab2.ps,width=3.25in,prolog=lprep65.pro} =============================================================================== 3. MACINTOSH FILES Since the Macintosh drawing applications produce PostScript, they can be used to create figures. MacDraw is a recommended program for creating figures, since it produces code that is independent of scaling (as opposed to MacPaint, which produces a bitmap of the figure). Many other drawing applications exist; hopefully they will also behave in the manner described below. Before including a Macintosh figure in your TeX document, it must be created on the Macintosh and moved to CMS. As of this writing, it is possible to convince MacDraw, and most other Macintosh applications, to place a PostScript descrip- tion of a figure in a file rather than sending it directly to a LaserWriter by hitting clover-F immediately after clicking 'OK' on the print dialog box. The file is always called 'PostScript' and is left in the folder MacDraw was start- ed in. Use a communications program, like FTP, to move the file over to CMS, saving it in EBCDIC with record lengths no longer than 80 characters. MacDraw creates an output file in the form of 'QuickDraw' calls, which are interpreted as a set of PostScript procedures. These procedures are defined in a file commonly called the LaserPrep file, which must be prepended to any Macintosh file before being sent to the printer. LaserPrep files are also known as 'Macintosh prologs' and 'AppleDict files'. By using clover-K rather than clover-F in the key sequence above, both the prolog and figure will be captured in the PostScript file. The prolog can be extracted by hand-editing out the portion of the clover-K file also present in the clover-F file. There are various versions of LaserPrep files which often differ from one Macintosh operating system software release to another. Graphic files must match the LaserPrep of the Macintosh operating system software under which the graphics were generated. Furthermore, LaserPrep files require some customiza- tion before they can be used by any DVI to PostScript driver. Currently, there are two Macintosh prologs available on CMS: 'lprep65 pro' and 'lprep68 pro', Psfig/TeX 1.2 Users Guide page 4 =============================================================================== which correspond to LaserPrep versions #65 and #68, respectively. Other Laser- Prep files will be ported, as they become available. Some versions of MacDraw and the Macintosh LaserWriter driver do not include a bounding box comment in the PostScript files they produce; figures created by these systems will have to have their bounding box added manually (see section 6). There is a prolog option in the psfig macro to specify a file that should be prepended to the figure. The name of the prolog is, of course, site dependent; we have used 'lprep65 pro'. For example, if you had a file 'lab2 ps' that con- tained the Macintosh code to draw a floor-plan (Figure 1 on page 3), you could use the following psfig macro call to embed it in you document: macro call to embed it in you document: \psfig{figure=lab2.ps,prolog=lprep65.pro}} If there are many such figures, it is probable that the repeated inclusion of the 'lprep65 pro' file will cause a significant increase in transmission and printing time. An article called Including Macintosh Graphics in LaTeX Documents by Len Schwer, recently appeared in TUGBoat, Volume 11, No. 2, and covers this subject in much more detail. 4. OTHER SOURCES OF FIGURES \hbox{ \vbox{\psfig{figure=trevor.ps,height=1in}} \hspace{.15in} \vbox{:pbox{3.5in} Any program that produces PostScript as output can be used for psfig figures as long as it adheres to the bounding box comment convention (see below). For instance, the Unix ph program was used to convert a bitmap image of the author into PostScript form and included as a figure at left. Today, a very large number of PC programs can produce PostScript and Encapsu- lated PostScript Files, which can be embedded with psfig. Again, use a commu- nications program, such as FTP, to transfer the PS or EPS files to CMS, saving them in EBCDIC with record lengths no longer than 80 characters. 5. DRAFT FIGURES AND SILENT MODE Normally, psfig will print advisory messages to remind you that it is including figures as TeX processes a document. This behavior can be disabled with \pssi- lent, and re-enabled with \psnoisy. Some PostScript figures can take quite a long time to transmit and print; for these figures a draft mode is available to speed printing intermediate versions of the document. A figure printed in draft mode will occupy the proper space Psfig/TeX 1.2 Users Guide page 5 =============================================================================== as far as TeX is concerned but no PostScript code will be executed to print it. If psfig is not in silent mode, it will also print the name of the PostScript file in the space reserved for the figure. No \special's are used in draft mode; thus any dvi processor can be used. 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.ý 6. BOUNDING BOXES To properly translate and scale a figure psfig must know its 'natural' position on the page; this information is present in what is called the bounding box of a PostScript program. The bounding box is a outer limit to the marks created by a program, and is specified as four coordinates of a rectangle: 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). Adobe has defined a convention whereby the bounding box of a program is contained in a 'bounding box comment'.· This comment, which must be present in any file to be used as a psfig figure, is a line of the form %%BoundingBox: bbllx bblly bburx bbury All values are in PostScript points, relative to the default transformation matrix. The only mandatory PostScript convention is that the first line of the file should begin with the characters '%!' (a '%' begins a comment in Post- Script.) A good place for the bounding box comment is as the second line of the file. The bounding box values may be specified directly on the psfig macro, using clauses bbllx=bbllx,bblly=bblly,..., in which case the file is not searched for the bounding box. 7. RESERVED SIZE \psfig{figure=box.ps,rheight=0bp,rwidth=0bp,height=1.05in, width=\textwidth,silent=} 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 clauses of the form 'rheight=dimen' and 'rwidth=dimen'. If ommited, 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 the grey box enclosing this paragraph. =========================== ý The TeX source of this document, saved as 'psfigug tex', illustrates the use of these and other psfig macro calls invoked throughout this Users Guide. · See 'Appendix J: PostScript File Structuring Conventions' in The PostScript Language Reference Manual. Psfig/TeX 1.2 Users Guide page 6 =============================================================================== 8. CLIPPING Normally a PostScript program can be expected to not mark the page outside its bounding box. If this is not the case, or if you want to specify a bounding box so as to isolate part of a larger figure, there is an option that sets the PostScript clip path so that no marks will show up outside the declared bound- ing box. Currently this is invoked by adding a clause of the form 'clip='. Here a slice has been taken out of the pie chart in the example by specifying a smaller bounding box and adding the clip option. \centerline{\protect\fbox{\psfig{figure=piechart.ps,height=2in,bbllx=306bp, bblly=396bp,bburx=486bp,bbury=546bp,clip=}}} \centerline{A piece of the pie.} \vspace{.2in} Some PostScript programs use the clipping path to position their output on the page; if a figure is being drawn at its natural size and position despite psfig commands to the contrary, it may need the clip option. 9. POSTSCRIPT ENVIRONMENT The PostScript environment within psfig is fairly robust. All of the usual PostScript operators will operate as desired; in particular the operators 'showpage', 'initgraphics', and 'defaultmatrix' will all behave consistently inside a figure, except that 'showpage' will only do an 'initgraphics' and will not print or erase the current page.¸ It is very possible, however, for a PostScript program to bypass the psfig environment and disrupt a document. 10. CAVEATS Some versions of LaTeX will fail to properly center a lone figure in a center- ing environment; a good work-around is to precede the figure with a hard space. On documents with complicated figures, the printer memory allocated to dvips may have to be limited to avoid vmerrors. PostScript files produced from Adobe's ps4014 need to have the clipping boundary set. Finally, the \psfig macro will be confused by white space or newlines in its argument. 11. ACKNOWLEDGEMENTS Ned Batchelder co-developed the original troff version of this program with the author, and was responsible for much of the overall design. Greg Hager provid- ed an initial TeX implementation. The three broken out figures in the intro- duction were taken from examples in The PostScript Language Tutorial and Cook- book. Thanks to Ira Winston and the CIS department for supporting this work. =========================== ¸ For more detailed information about PostScript issues in the internals of psfig, see Pfig -- 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.