⟦437905e87⟧

TextFile

\documentstyle[psfig]{article}
\begin{document}
\addtolength{\parskip}{7pt}
%
% PostScript Logo 
\def\Ps{PostScript}
\title{Incorporating \Ps\ and Macintosh figures in \TeX\ }
\author{Trevor Darrell}
\date{January 9, 1987}
\maketitle
%
\begin{abstract}
psfig/\TeX\ is a new macro package for \TeX\ that facilitates the
inclusion of arbitrary \Ps\ figures into \TeX\ documents.
Figures are automatically scaled and positioned
on the page, and the proper amount of space is reserved.
For example:
\par
\hbox{
\hspace{.3in}
\vbox{\psfig{figure=figs/zip.ps}\vspace{.5in}}
\psfig{figure=figs/piechart.ps,height=1.5in}
\vbox{\psfig{figure=figs/starlines.ps}\vspace{.6in}}
}
\par
Custom characters such as
`\psfig{figure=figs/pretzel.ps,height=8pt}' and 
`\psfig{figure=figs/cm.ps,height=8pt}'
may be created and used freely throughout a document. Since the
Macintosh drawing applications produce \Ps, they can be used to create
figures.
\end{abstract}
%
\section{Introduction}
The \TeX\ typesetting system is a powerful tool in the preparation of the 
written word, yet when the time comes to add figures or pictures to a document,
one traditionally had to resort to tedious manual paste-up. 
With the advent of the \Ps\ page description language,
which allows the `nesting' of environments and is rapidly becoming
a {\it de facto} standard, it is now possible to merge graphics
directly into a document. psfig provides the facility for the
nested inclusion of a \Ps\ figure in a \TeX\ document.
%
\par
\section{Including a figure}
To include a \Ps\ figure with psfig, simply load the psfig macros at the 
beginning of your document with
\par
{\tt\verb+\input{psfig}+}
\par
then invoke the macro
\par
{\tt\verb+\+psfig\{figure={\it input}\}}
\par
where {\it input} is the name of a \Ps\ file. 
psfig will automatically position the figure at the current place on the page, 
and reserve the proper amount of space in \TeX\ so that it doesn't conflict
with any other objects.
\par
For example, if we have a file called `piechart.ps' which contains the
\Ps\ code to draw the chart in the abstract, and it was the first figure
in our non-page reversed document, we would use the commands
\begin{quote}
{\tt\verb+\+input psfig } \\
{\tt\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps\}\}}
\end{quote}
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 \Ps\ printer.) The pie's natural size is several inches across, which
is a little large; the pie in the abstract was produced with:
\par
{\tt\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps,height=1.5in\}\}}
\par
The {\tt height} option specifies how tall the figure should be on the
page. Since no {\tt width} was specified, the figure was scaled equally
in both dimensions.
By listing both a {\tt height} and a {\tt width}, figures can be scaled 
disproportionatly, with interesting results.
\par
For example:
\par
\centerline{\hbox{
\psfig{figure=figs/rosette.ps,height=.8in,width=.15in}
\psfig{figure=figs/rosette.ps,height=.8in,width=.35in}
\psfig{figure=figs/rosette.ps,height=.8in}
\psfig{figure=figs/rosette.ps,height=.8in,width=1.2in}
\psfig{figure=figs/rosette.ps,height=.8in,width=1.5in}
}}
\par
was produced with:
\begin{quote}
\tt\verb+\+centerline\{\verb+\+hbox\{ \\
\verb+\+psfig\{figure=rosette.ps,height=.8in,width=.15in\} \\
\verb+\+psfig\{figure=rosette.ps,height=.8in,width=.35in\} \\
\verb+\+psfig\{figure=rosette.ps,height=.8in\} \\
\verb+\+psfig\{figure=rosette.ps,height=.8in,width=1.2in\} \\
\verb+\+psfig\{figure=rosette.ps,height=.8in,width=1.5in\}\}\} 
\end{quote}
\par
\subsection{Caveats}
For psfig to find the natural size of a figure, the figure must have a
proper bounding box comment; see section 5 below. Draft mode (also 
detailed below) should be used liberally to speed throughput. 
Also, some versions
of \LaTeX\ will fail to properly center a lone figure in a centering 
environment;
a good work-around is to precede the figure with a hard space. On very large documents with many figures, the printer memory
allocated to dvips may have to be limited. 
 Finally, the
\verb+\psfig+ macro will be confused by extra white space or newlines in its
argument.
\par
\section{Generating PostScript}
Before you can include a figure, however, you must create
the \Ps\ file that describes it.
The most common methods for creating a \Ps\ figure are to 
use either a drawing application such as MacDraw, an image-to-ps or
textronix-to-ps translator, or to 
directly code \Ps\ by hand. A brief \Ps\ tutorial is included as an
appendix.
\begin{figure}
\centerline{\psfig{figure=figs/pathtext.ps,height=2in}}
\centerline{Figure 1. a \Ps\ figure}
\end{figure}
\par
\subsection{Macintosh files}
Using a Macintosh (or any other system that supports mouse-based drawing
utilities that use \Ps) is one of the easiest ways of creating
a figure (figure 2a.)
MacDraw is the recommended tool, since
it produces code that is independent of scaling (as opposed to MacPaint,
which produces a bitmap of the figure.)
There are several known methods of capturing a MacDraw/MacWrite figure
in \Ps\ form and transferring to the \TeX\ host; most involve some
mucking about with tricky control sequences, one is detailed in the appendix.
\par 
MacDraw creates a output file in the form of `QuickDraw' calls, which are 
interpreted as a set of \Ps\ procedures. These procedures are defined
in what is called the `macintosh prolog', which must be prepended 
to any macintosh file
to be sent to the printer.
There is a {\tt 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 `/usr/lib/ps/mac.pro'.
For example, if you had a file `frog.mac' that contained the macintosh
code to draw kermit (figure 2b), he could be included with:
\begin{quote}
{\tt\verb+\+psfig\{figure=frog.mac,prolog=/usr/lib/ps/mac.pro\}\}}
\end{quote}
\begin{figure}
\centerline{
\vbox{\vss\psfig{figure=figs/lab.ps,prolog=figs/mac.pro,width=2.5in}\vss}
\hss\vbox{\vss\psfig{figure=figs/frogfill.mac,prolog=figs/mac.pro,width=2in}\vss}}
\par
\centerline{Figure 2a \& 2b: Macintosh figures.}
\end{figure}
If there are many such figures, it is probable that the repeated inclusion
of the mac.pro file will cause a significant increase in file size and
transmission time. An alternative method is to load the mac.pro file
once globally, so that it will be available throughout the rest of the
document. Use {\tt \verb+\psglobal{\usr\lib\ps\mac.pro}+} at the
beginning of your document
to achieve this effect. For this to work properly, the \verb+\psglobal+ must 
be before any Macintosh figures, and the final output must not be page
reversed.
\footnote[1]{It is possible to use psglobal in
page reversed document; place it just before the last figure in
your document. This is living dangerously, and you do so at your own risk.}
\par
\subsection{Images (ph), plot, and other sources}
Any program that produces \Ps\ as output can be used for psfig figures.
For instance, the {\it ph} program will convert a bitmap image
to \Ps\ form and thus can be
used to include an image in a document (figure 3.)
\par
There are similar utilities that can convert files from unix plot(5)
or Textronix 4014 format into \Ps.
The Unix text processor {\it troff} produces \Ps, so one can slice a page
out of a Troff document and include it in a \TeX\ paper (figure 4.)
\begin{figure}
\psdraft %% delete me for full copy of paper
\centerline{
\vbox{\vss\psfig{figure=figs/fancyimage.ps,height=3in,width=2.25in,bbllx=72bp,bblly=72bp,bburx=540bp,bbury=540bp}\vss}
\hspace*{0.2in}\fbox{\psfig{figure=figs/psfig.ps.1,height=3in,width=2.25in,bbllx=1sp,bblly=1sp,bburx=8.5in,bbury=11in}}
}
\par
\centerline{Figure 3: A bitmap image.\hss Figure 4: Troff in \TeX}
\end{figure}
Note that the {\it troff} page was processed by 
the {\it troff} counterpart to psfig, and itself contains two images and several
\Ps\ tricks. 
\par
\section{Draft figures}
Certain \Ps\ figures (such as large bitmap images being transmitted at
9600 baud) can tie up a slower \Ps\ device such as an
Apple LaserWriter for quite some time.
To circumvent this, a figure
may be printed in draft mode, which will occupy the same space on the
page as far as
\TeX\ is concerened, but it will just print the name of the file from 
which the figure is derived, and will not actually include it.
The macro {\tt \verb+\+psdraft} will switch into draft mode, and all
subsequent psfig macros will produce draft figures. The macro {\tt
\verb+\+psfull} will switch out of draft mode. 
\section{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 {\it bounding box} of a \Ps\ 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'.
\footnote[2]{See `Appendix J: \Ps\ File Structuring Conventions' in
{\it The \Ps\ Language Reference Manual}}
This comment, which must be present in any file to be used as a psfig figure,
is a line of the form
\begin{quote}
\tt \verb+%%+BoundingBox: \it bbllx bblly bburx bbury
\end{quote}
All values are in \Ps\ points, relative to the {\it default}
transformation matrix. The only mandatory \Ps\ convention is
that the first line of the file should begin with the characters
`\verb+%+!' (a `\verb+%+' begins a comment in \Ps.) A good place for the
bounding box comment is as the second line of the file.
\par
There is a {\it bbfig} utility on systems to aid in calculating
the bounding box, refer to the {\it bbfig(l)} manual page for further information.
\section{Advanced topics}
\subsection{psfig internal structure}
In including a figure, the {\tt \verb+\psfig+} macro performs the following
operations:
First, if bounding box information (see below) is omitted from the list
of arguments, the
file containing the figure
is searched and the information recovered from the bounding box
comment. Then,
if both {\it height} and {\it width} are missing they are computed to
be the height and width of the bounding box. If only one is missing,
it is set to be the appropriate value such that there is no distorted
scaling.
If {\it rheight} or {\it rwidth} (see below) is missing it is presumed to
be the same as the height and width.
\par
 The {\tt\verb+\+psfig\{figure={\it input}\}} macro
uses a vbox in \TeX\ to reserve the space.
The actual inclusion of files is preformed with a  
{\tt \verb+\+special} command to the {\it dvips} postprocessor.
Presently, {\it dvips} is the only supported post-processor,
but it shouldn't be to difficult to port psfig to
a different postprocessor, presuming similar capabilities and/or
access to source code.
psfig depends on certain \Ps\ function calls; these are downloaded
with the \verb+\psfiginit+ macro. Do not use page-reversing on your
output if you are manually initializing psfig with \verb+\psfiginit+, or
are using \verb+\psglobal+.
It is possible to include these
definitions into the standard dvips (or whatever) header file; this
has been done on our systems and users need not do a 
\verb+\psfiginit+.
\subsection{Reserved size}
\psfig{figure=figs/box.ps,rheight=0bp,rwidth=0bp,height=1.25in,width=\textwidth}
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 {\it reserved size}, and is expressed as clauses of the form
``{\tt rheight={\it dimen}}''
and ``{\tt rwidth={\it 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.
\subsection{Clipping}
Normally a \Ps\ program can be expected to not mark the page 
outside its bounding box. If this is not the case, or if you
want to use the bounding box to isolate part of a larger figure,
there is an option that sets the \Ps\ clip path so that
no marks will show up outside the declared bounding box. Currently
this is invoked by adding a clause of the form ``{\tt 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.
\par
\centerline{\psfig{figure=figs/piechart.ps,height=2in,bbllx=306bp,bblly=396bp,bburx=486bp,bbury=546bp,clip=}}
\par
Some \Ps\ 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.
\par
\subsection{\Ps\ environment}
The \Ps\ environment within psfig is fairly robust. All of the
usual \Ps\ 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 {\it not} print or erase the current
page.
\par 
It is very possible, however, for a \Ps\ program to bypass the psfig
environment and disrupt a document. These cases are infrequent,
 and a `work-around' solution can usually be found. 
\par
\section{Acknowledgements}
Ned Batchelder co-developed the original {\it troff} version of this
program with the author, and was responsible for much of the overall design.
Greg Hager provided an initial \TeX\ implementation.
Figure 1 and the three broken out figures in 
the abstract were taken from examples in {\it The PostScript Language
Tutorial and Cookbook.} 
The image in figure 3 was designed by Kamran Manoochehri, rendered with
{\it CARICATURE}, by Cary Phillips.
\newpage
\appendix
\section*{Appendix A: \Ps\ Overview}
Coding \Ps\ by hand gives you the most control possible over the 
shape and appearance of the figure; for example, few conventional document
preparation packages could produce the graphic in figure 
\Ps\ is a stack-oriented language, very similar to Forth and RPN in the way
that arguments are handled, yet it features strong typing and higher
level control structures. It has an advanced imaging primatives, based on a
{\it stencil and paint} imaging model. Objects are rendered on the
page by applying {\it paint}, which can be any color or sampled image,
through a {\it stencil}, a closed geometric path that limits where the
paint should go. For example, a line can be described as applying black paint
through a long thin stencil. This generality is preserved throughout \Ps, 
including in its treatment of fonts, but that does not prevent \Ps\
implementations from taking advantage of special cases for efficiency
considerations. Rarely would an actual \Ps\ interpreter draw a line
by creating a thin rectangle and performing a fill operation;
what is important is that its
behavior can be perfectly characterised as if it had.
\par
\Ps\ has a full complement of data types, operators, and control structures.
In general, arguments are pushed on an operand stack, then popped off and acted on by an operator
or procedure. When \Ps\ encounters an object it can't execute immediately
(such as a number or a string),
it is pushed onto the operand stack. Thus, to provide parameters to an
operator, simply list them before the operator name. Thus \Ps\ (like
forth), is a prefix language. All expressions are thus unambiguous, and
the syntax is very efficient to interpret.
\par
For instance, arithmetic is easy:
\begin{quote}
\tt 2 2 add
\end{quote}
would leave a `4' on the operand stack. Similarly, to add
$\frac{1+2}{2+3} + 13 * 9$, you would type
\begin{quote}
\tt 1 2 add 2 3 add div 13 9 mul add
\end{quote}
\par
In addition to numbers and operators there are several different types 
of objects that \Ps\ supports. A string, for instance, is denoted by
text enclosed in parenthesis. An array of objects is denoted by
brackets, and a procedure by braces.
An identifier that is not a number, string, or composite object
is a {\it name} object. There are two types of name objects, {\it
executable}, meaning the value or procedure associated with the object will
be evaluated immediately, and {\it literal}, which is not evaluated.
A literal name has a `/` prepended to it,
and is pushed directly on the operand stack, while an executable name is
looked up on the {\it dictionary stack}, and its associated value placed
on the operand stack. 
A {\it dictionary} is a data
structure that associates {\it key} - {\it value} pairs.
All operators, variables, and procedures are referenced through the
dictionary stack, which essentially establishes the hierarchical naming
environment in \Ps.
\par
There are always at least two entries on the dictionary stack: the system dictionary and
the user dictionary. The system dictionary contains all the bindings for the
built-in operators, while the user dictionary holds user variables and
procedures. A \Ps\ program is free to modify the user dictionary (and to
add new entries on the stack), but can not write to the system dictionary.
\par
Assigment is with the {\tt def} operator, which takes a literal name and value
and stores it in the topmost dictionary; to initialize $\pi$ you
could say
\begin{quote}
\tt /pi 3.14 def
\end{quote}
After this {\tt def}, typing the executable name {\tt pi}
will cause \Ps\ to look up that name in the dictionary stack and place 3.14 on the operand stack. 
\footnote[3]{The value need not be numeric; it may be a string, array, or procedure, among other things.}
For instance,
\begin{quote}
\tt pi r 2 exp mul
\end{quote}
would evaluate $\pi r^2$ (of course, if {\tt r} had not been 
defined, an error would have been generated).
\par
\begin{figure}
\par
\begin{picture}(340,220)
\put(0,120){\tt newpath }
\put(0,110){\tt 50 50 moveto}
\put(0,100){\tt 150 50 lineto}
\put(0,90){\tt 100 150 lineto}
\put(0,80){\tt closepath stroke}
\put(0,70){\tt showpage}
\put(170,0){\fbox{\psfig{figure=figs/triangle.ps,width=162pt,bbllx=0sp,bblly=0sp,bburx=8.5in,bbury=11in}}}
\put(100,100){\vector(1,0){50}}
\end{picture}
\par
\centerline{Figure 5: a sample \Ps\ program.}
\end{figure}
The \Ps\ language has a rich collection of operators, including
the usual stack operators (pop, dup, exch, ...), arithmetic operators (add, mul,
sin, ...), and control operators (if, loop, for ...), as well as 
more advanced operators
for manipulating dictionaries, arrays, strings, and files. 
\par
While \Ps\ has all the capabilities of a general purpose language, it 
is first and foremost a page description language,
and as such has a whole range of operators that manipulate 
the graphics state and place marks on the page. 
All values given to graphic primitives in \Ps\ are transformed through the 
{\it current transformation matrix (CTM)} before any marks are made on the
page. Thus the CTM establishes the scale and orientation of the coordinate
system in which a program will run.
The default \Ps\ CTM produces a coordinate system in \Ps\ points (\Ps\ points
are the same as `big points' (bp) in \TeX - 72 to the inch)
with the origin in the lower left hand corner of the page.
The CTM can be scaled, rotated, or translated dynamically
by a \Ps\ program.
\par
An important object in the graphics environment is the {\it current
path}, an internal \Ps\ data structure that keeps
track of geometric shapes. The current path is composed of an arbitrary number 
of connected or disjoint line segments, curves, and Bezier cubics. 
\par
The {\tt newpath} operator clears the current path, and 
the {\tt moveto} operator will move the current point to an arbitrary location.
{\tt Moveto} takes two arguments, an x and y location on the page,
so to move to (307,397) you would say {\tt 307 397 moveto}.
Exactly where (307,397) is on the page depends on the CTM; with the
default matrix, it is roughly at the center of the page.
\par
From the current point, an {\tt x y lineto} will add a line
segment to {\it (x,y)} on the current path, or
a {\tt closepath} will add a segment back to the first 
point in the path.
To create arcs and circles, a {\tt x y r ang1 ang2 arc} will
add a counterclockwise segment from {\it ang1} to {\it ang2} of a circle of
radius {\it r} whose center is at {\it (x,y)}.
Note that none of these commands actually
mark the page; they just build up the path structure.
Two operators which will mark the page according to the
current path are:
{\tt stroke}, which will draw a line along the current path, and
{\tt fill}, which will paint the region enclosed by the current path.
Figure one depicts a sample \Ps\ program and its result.
\par
Text can be equally as simple; first, you must set up the current font.
\begin{quote}
\tt /Times-Roman findfont 10 scalefont setfont
\end{quote}
would set the current font to be ten point roman.  
A string can be printed at the current point using the {\tt show} operator.
In \Ps\, strings are delimited by parenthesis.
\par
When a \Ps\ program has completed putting all useful marks onto a page,
it should execute the 
{\tt showpage} operator, which causes the printer to print and eject the current page.
\par
Thus, to label the vertices in our triangle, we could modify our 
program as follows
\begin{quote}
\tt newpath \\
50 50 moveto \\
150 50 lineto \\
100 150 lineto \\
closepath stroke \\
/Times-Roman findfont 10 scalefont setfont \\
45 55 moveto (a) show \\
155 55 moveto (b) show \\
95 55 moveto (c) show \\
60 35 moveto \\
(The Triangle ABC) show \\
showpage
\end{quote}
which would produce:
\par
\psglobal{figs/mac.pro}
\centerline{\psfig{figure=figs/trianglev.ps}}
\par
This overview was only meant to give a flavor of the \Ps\ 
language, and therefore has only touched on the simplest 
of it's commands. For a more thorough introduction, 
consult the {\it PostScript Language Tutorial and Cookbook}
and {\it PostScript Language Reference Manual} from Adobe Systems.
\par
\section*{Appendix B: Capturing \Ps\ files from a Macintosh}
In general, a \Ps\ file can be transferred from a Macintosh to another host
using any of the popular terminal emulators and a serial line. We have used
MacTerminal and Kermit without any problems.
\par
Slightly trickier is getting the \Ps\ into a file on the Macintosh. For
MacDraw and MacWord (and perhaps others), there is an undocumented
``feature'' whereby the \Ps\ code can be diverted into a file rather than
being sent to a printer. Immediately after clicking `ok' from the print
menu, hit clover--F; the code will be placed in a file with the name 
``PostScript'' (there is no known way to change this). Clover-K will 
capture the file {\it and} the lengthy prolog mentioned above.
\end{document}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦437905e87⟧ TextFile

Derivation

TextFile
