\documentclass{article}
%\documentstyle{article}
\input psfig.sty
\begin{document}
\pssilent
%AO - the following 3 lines are specific to the Mac platform:
\psfigurepath{:figs}
\advance\hoffset-1in
\advance\voffset-1in
%
%AO - the following line is for Unix
%\psfigurepath{./figs}
%
\def\Ps{Post\-Script}
\title{Psfig/\TeX\ 1.10 Users Guide}
\author{Trevor Darrell \\ {\it trevor@media.mit.edu}}
\date{\ }
\maketitle

\section{Introduction}
Psfig/\TeX\ is a macro package for \TeX\ that facilitates the
inclusion of  \Ps\ figures into \TeX\ documents. With the
help of a compatible postprocessor,%
\footnote{The {\tt dvips} program developed by T. Rokicki 
has full psfig support; it is available via anonymous FTP from {\tt labrea.stanford.edu}. 
OzTeX also supports psfig and is available from various ftp sites. 
Textures 1.7 (available from Blue Sky Research {\tt help@bluesky.com}) supports psfig 1.10.
Psfig is available from {\tt whitechapel.media.mit.edu}.}
\Ps\ figures are automatically
scaled and positioned on the page, and the proper amount of space is
reserved.  
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, or figures can
be presented as traditional broken-out displays:
\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}}%
}%

\section{Simple figures}
%
To include a \Ps\ figure with psfig, include the psfig style at the top
of your document:
\begin{quote}
{\tt\verb+\documentstyle[psfig,...]{article}+}
\end{quote}
and then, when you wish to include a figure, invoke the macro
\begin{quote}
{\tt\verb+\+psfig\{figure={\it input}\}}
\end{quote}
where {\it input} is the name of a \Ps\ file.  Psfig will
automatically position the figure at the current point on the page,
and reserve the proper amount of space in \TeX\ so that it doesn't
block any other objects on the page.  For example, if we have a file
called `piechart.ps' which contains the \Ps\ code to draw the chart in
the introduction, we could use the commands
\begin{quote}
\tt
\verb+\+par \\
\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps\}\} \\
\verb+\+par
\end{quote}
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 \Ps\ printer.) The pie's natural size is several inches across, which
is a little large; the pie in the introduction was produced with:
\begin{quote}
\tt\verb+\+centerline\{\verb+\+psfig\{figure=piechart.ps,height=1.5in\}\}
\end{quote}
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. (This will also happen with a {\tt width}
but no {\tt height} option.)  By listing both a {\tt height} and {\tt
width}, figures can be scaled disproportionately, with interesting
results:
\par
\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}
}}
\par
\noindent This figure 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}
The \verb+\psfig+ macro is (unfortunately) sensitive to whitespace, and will be
confused by any extra spaces or newlines in its argument.
%
\section{Draft figures and Silent mode}
%
\begin{figure}
\centerline{
\psfig{figure=rosette.ps,height=2in}
\psdraft
\psfig{figure=rosette.ps,height=2in}
\psfull
}
\vspace{.25in}
\centerline{Figure 2: The rosette.ps figure, in non-draft and draft mode}
\end{figure}
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 {\tt \verb+\+pssilent}, and re-enabled with
{\tt \verb+\+psnoisy}.
\par
Some \Ps\ figures can 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 outlined box (Figure 2).  The macro {\tt
\verb+\+psdraft} will switch into draft mode, and all subsequent psfig
macros will produce draft figures until reaching the macro {\tt
\verb+\+psfull}, which switches out of draft mode.

No {\tt
\verb+\+special} commands are used in draft mode, so a draft document
can be previewed using any DVI viewer.  
%Psfig uses the \LaTeX\ {\tt
%\verb+\+fbox} command to produce the draft box; thus draft boxes will
%not work in plain \TeX. 
The printing of boxes in draft mode can be
disabled/enabled with {\tt
\verb+\+psnodraftbox} and {\tt
\verb+\+psdraftbox}. 

\section{Sources of figures}
\hbox{%
\vbox{\psfig{figure=trevor.ps,height=.85in}}%%BoundingBox: 72 72 432 525
\hspace{.15in}%
\vbox{\parbox{3.5in} {Any program that produces \Ps\ as output
can be used for psfig figures
as long as it adheres to the certain standards.
For instance, the sampled image
of the author was included as a figure at left.}\vspace{.2in}}}

%AO - substitute the following for the earlier outdated discussion:
Make sure that any application you use to generate \Ps\ graphics does so in 
compliance with the Adobe Encapsulation Standard.%
\footnote{See `Appendix J: \Ps\ File Structuring Conventions' in
{\it The \Ps\ Language Reference Manual}}
With most applications, this means selecting ``EPS'' as the file format.
The EPS standard provides for the very important ``Bounding Box'' comment (see Section~5).
Adobe also mandates standards for the \Ps\ code in the graphic: it must be ``well-behaved'' in some sense.
%For more information about EPS, see the \Ps\ Language Reference manual, 2nd. ed.

With Adobe Illustrator, for instance, you save your document ``with EPSF header''.
If you are using the Macintosh LaserWriter 8 print driver, 
you can ``print'' a single page of your document to a file in EPS format.
Under MS-Windows, you can either save your graphic to EPS format or print to EPS
format. 
Refer to your application's documentation or your system documentation for more details.

\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 an 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's Encapsulation Standard provides for the bounding box of a program
to be 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
\begin{quote}
{\verb+%%BoundingBox: +}{\it bbllx bblly bburx bbury}
\end{quote}
All values are in \Ps\ points, relative to the {\it default}
transformation matrix. 
\par
If you are putting the bounding box comment in by hand, be sure
that the first line of the file begins with the characters
`\verb+%+!' (a `\verb+%+' begins a comment in \Ps.) 
Psfig will give a warning message if the file does not start with these two characters.
A good place for the bounding box comment is as the second line of the file.
\par
If a bounding box comment is present in the figure file, psfig will
extract its values.  The bounding box values may instead be specified
directly in the {\tt \verb+\+psfig} argument, using clauses of the
form {\tt bbllx=}{\it bbllx},{\tt bblly=}{\it bblly},\dots, in which case
the figure file is not searched for the bounding box.

%AO added the following caution:
Note that many applications that purport to create EPS files include a BoundingBox
statement with very inaccurate values. In particular few Unix-based graphics applications
do an accurate job, and Macintosh and Windows print drivers will always state that the
bounding box of a ``print-to-disk'' file is the full page size.
Most all Adobe applications, Altsys FreeHand, and Blue Sky Research Textures are happy exceptions
to this unsatisfactory pattern: their BoundingBox statements are generally accurate.

\section{Reserved size}
%
\psfig{figure=box.ps,rheight=0bp,rwidth=0bp,height=1.25in,width=\textwidth,silent=}
\par
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 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 the grey
box enclosing
this paragraph.

\section{Clipping}
%
%AO - copy and examples revised
Some PostScript graphics make marks outside of the bounding box, 
such as this Adobe Illustrator with cropmarks set {\it left below}).
You may use psfig's clip option to cause the image to be clipped to its bounding box ({\it right, below}).
\par
\vskip.2in
\centerline{%
 \psfig{figure=smallrose,height=1.9375in}%%BoundingBox:  48 67 146 188
 \hfill
 \psfig{figure=smallrose,height=1.9375in,clip=}%%BoundingBox:  48 67 146 188
 }%
\centerline{A flower.}
\vskip.2in
\par
By specifying a smaller bounding box with psfig's bbllx, etc, parameters, you can zoom in on a portion of the artwork.
Temporarily preview the effect of the clip option by using the stroke option ({\it below left}).
At the center, we've added the clip option, and the right the complete effect is shown by using the only the clip option.
\par
\vskip.2in
\centerline{%
 \psfig{figure=smallrose,height=1in,bbllx=85bp,bblly=140bp,bburx=145bp,bbury=185bp,stroke=}%%BoundingBox:  48 67 146 188
 \hfill
 \psfig{figure=smallrose,height=1in,bbllx=85bp,bblly=140bp,bburx=145bp,bbury=185bp,stroke=,clip=}%%BoundingBox:  48 67 146 188
 \hfill
 \psfig{figure=smallrose,height=1in,bbllx=85bp,bblly=140bp,bburx=145bp,bbury=185bp,clip=}%%BoundingBox:  48 67 146 188
 }%
\centerline{A piece of the flower.}
\vskip.2in
Note that some \Ps\ programs use the current clipping path to position their output on the page; 
if your graphic is being drawn at its natural size and position despite psfig commands to the contrary, 
you may need to employ the clip option as a workaround.

%\newpage
\section{Rotating figures}
%
Figures can be rotated by psfig using the {\tt angle={\it degrees}}
clause. For example, here is the rosette and its 90 degree rotation:

\centerline{\hbox{
\psfig{figure=rosette.ps,height=1.0in}
\psfig{figure=rosette.ps,height=1.0in,angle=90}
}} 

By default psfig scales the figure so that its rotated bounding box
fits within the desired size. This can lead to counterintuitive results
when rotating to angles which are not multiples of 90 degrees. Here
is the rosette rotated to 0,20,40, and 60 degrees.

\centerline{\hbox{
\psfig{figure=rosette.ps,height=1.0in}
\psfig{figure=rosette.ps,height=1.0in,angle=20}
\psfig{figure=rosette.ps,height=1.0in,angle=40}
\psfig{figure=rosette.ps,height=1.0in,angle=60}
}} 

With autoscaling, some rotated figures come out smaller because the
diagonal of their bounding box is of course longer than their height
or width alone.  This behavior can be disabled with {\tt
\verb+\+psscalefirst}, and re-enabled with {\tt
\verb+\+psrotatefirst}. With {\tt \verb+\+psscalefirst} a new
height and width is computed after the bounding box;
the previous figure would now look like:

\psscalefirst
\centerline{\hbox{
\psfig{figure=rosette.ps,height=1.0in}
\psfig{figure=rosette.ps,height=1.0in,angle=20}
\psfig{figure=rosette.ps,height=1.0in,angle=40}
\psfig{figure=rosette.ps,height=1.0in,angle=60}
}} 

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.

\section{Compressed Figures}
%
On Unix platforms with dvips,
psfig allows the inclusion of compressed \Ps\ files.
The shell script {\tt pscompress} is used to compress figures, and 
produces two files: {\it filename}{\tt .bb} and {\it filename}{\tt .Z}.
The first file contains the bounding box comment only, while the second
file contains the actual compressed PostScript file. Usage:
\begin{quote}
\tt \verb+%+ pscompress \it filename
\end{quote}
When psfig searches for a figure, if it fails to find 
{\it filename}, it then searches for {\it filename}{\tt .bb}.
If that file exists, it is used for bounding box processing,
and a command to  decompress and include the file {\it filename}{\tt .Z}
is issued to dvips.

\section{Figure search path}
%
%AO - completely rewritten
When attempting to locate the figure you specify,
psfig by default searches in the current directory 
(or in the specified directory if given an explicit path). 
You can optionally direct psfig to  search
a list of figure directories for the artwork you specify.
To give the list of figure search paths under Unix, use
\begin{quote}
\verb+\psfigurepath{+{\it dir1}{\tt:}{\it dir2}{\tt:}\dots{\tt:}{\it dirn}\verb+}+
\end{quote}
where {\it dir1},\dots,{\it dirn} are the directories figures are to be found in,
and each directory in the list is separated from the next by a colon ({\tt:}).

Note that you {\em must not} specify a path with the trailing slash {\tt/} (Unix) or colon {\tt:} (Macintosh).
Psfig supplies that for you, and is not able to deal with your including it on your own.

\subsection{Unix paths}
Under Unix, to include the current directory in the search path, you supply a dot ({\tt.}) in the
list of search paths. 
Unix paths are fully explained in your Unix system documentation.

\subsection{Macintosh paths}
On Macintosh, you use a semicolon({\tt;}) instead of a colon to separate the elements in the list:
\begin{quote}
\verb+\psfigurepath{+{\it dir1}{\tt;}{\it dir2}{\tt;}\dots{\tt;}{\it dirn}\verb+}+
\end{quote}
Furthermore, you specify a Macintosh path by giving a colon-separated list of folder names.
For instance, to point to a folder named ``figs'' in the current folder, you
would give {\tt :figs} in your list.
A Macintosh volume name, on the other hand, is never preceded by a colon, thus
to search a folder called ``illustrations'' in the root folder of a volume called ``Graphics'', 
you give {\tt Graphics:illustrations}.
Finally, the parent of the current folder is indicated by double colons,
so to look in a folder called ``figs'' in a folder called ``doc'' in the parent of the current folder, 
you give {\tt ::doc:figs}.
A \verb+\psfigurepath+ command collecting all of the above together along with
specifying the current folder at the head of the list would read:
\begin{quote}
\verb+\psfigurepath{;:figs;Graphics:illustrations;::doc:figs}+
\end{quote}
A bit of Macintosh aracana: to instruct psfig to search for files in the parent of the current
folder, give the command \verb+\psfigurepath{:}+.
The Macintosh path is a feature of the file system that is not meant for general users, 
so documentation in it is to be found in programmer's reference manuals only.

\subsection{MS/DOS paths}
Under DOS, you will use a semicolon to separate paths in the list.
Also, the directory separator under DOS is the slash ({\tt/}), not the backslash (\verb+\+).
Full documentation of DOS paths is to be found in your DOS manual.
A \verb+\psfigurepath+ example similar to that given for Macintosh is:
\begin{quote}
\verb+\psfigurepath{;./figs;/Graphics/illustrations;../doc/figs}+
\end{quote}

\section{\Ps\ Prolog and Postlog}%
You can specify the inclusion of a prolog file just ahead of your EPS graphic with
the {\tt prolog=} option to the \verb+\psfig+ command. 
Note that this file must be valid \Ps, need not have any sort of bounding box, 
and is isolated by the same \Ps\ {\tt save}/{\tt restore} as your EPS file.
Also, the \verb+\psfigurepath+ does not pertain to the prolog file.
In a similar way, you can include a file immediately following your EPS graphic.
Use the {\tt postlog=} option; the same restrictions apply.

\section{Psfig reference}%
%
Table~1 contains a complete list of parameters to the \verb+\psfig+ command, and
table~2 a complete list of the ancillary Psfig commands.
%
\begin{table}%
\small
\def\blash{\char"5C\relax}%
\caption{Parameters to the {\tt\blash psfig} command.}%
\begin{center}%
\begin{tabular}{|l|l|p{222pt}|}%
\hline
\bf name&\bf value&\bf explanation\\\hline
\tt clip&flag&Set clipping path to the bounding box\\
\tt stroke&flag&Stoke the bounding box\\
\tt figure&filename&Specify the name of the graphic\\
\tt file&filename&Same as {\tt figure}\\
\tt bbllx&number&$X$-coordinate of the lower left  corner of the bounding box (in big points)\\
\tt bblly&number&$Y$-coordinate of the lower left  corner of the bounding box (in big points)\\
\tt bburx&number&$X$-coordinate of the upper right corner of the bounding box (in big points)\\
\tt bbury&number&$Y$-coordinate of the upper right corner of the bounding box (in big points)\\
\tt height &dimen&target   height of the graphic image\\
\tt width  &dimen&target   width  of the graphic image\\
\tt rheight&dimen&reserved height of the figure\\
\tt rwidth &dimen&reserved width  of the figure\\
\tt angle&angle&amount to rotate the graphic image (in degrees ccw)\\
\tt silent&flag&process without messages in \TeX\ log\\
\tt prolog &filename&Insert \Ps\ file just ahead of graphic image\\
\tt postlog&filename&Insert \Ps\ file just after of graphic image\\
\hline
\end{tabular}
\end{center}
Here, `flag' signifies that nothing is to appear to the right of the `{\tt=}`,
`filename' should be a valid filename on your file system,
`dimen' is a dimension expressed in \TeX\ units,
and `angle' is an amount in degrees counterclockwise.
\end{table}
%
%
\begin{table}
\small
\caption{Ancillary commands for Psfig.}%
\begin{center}
\begin{tabular}{|l|p{228pt}|}
\hline
\bf csname&\bf explanation\\[2pt]\hline
\verb+\psfigurepath{+{\em arg}\verb+}+&sets the list of paths to search for the figures. See the section ``Figure search paths'' for information about the argument.\\[2pt]
\verb+\psdraft+&draws an outline box, but doesn't include the figure	in the DVI file.  Useful for previewing.\\[2pt]
\verb+\psfull+ &includes the figure in the DVI file (default) by undoing the effect of \verb+\psdraft+.\\[2pt]
\verb+\psscalefirst+&The {\tt width=} or {\tt height=} parameter specifies the size of the figure	{\em before} rotation.\\[2pt]
\verb+\psrotatefirst+&The {\tt width=} or {\tt height=} specifies the size of the figure {\em after} rotation (default) by undoing the effect of \verb+\psscalefirst+.  Asymetric figures will appear to shrink.\\[2pt]
\verb+\psnodraftbox+&In draft mode, a no visible box is drawn in the reserved area.\\[2pt]
\verb+\psdraftbox+&In draft mode, a visible box is drawn in the reserved area (default), reversing the effect of \verb+\psnodraftbox+.\\[2pt]
\verb+\pssilent+&Process the \verb+\psfig+ command without putting messages in the \TeX\ log.\\[2pt]
\verb+\psnoisy+&Process \verb+\psfig+ with messages in the \TeX\ log (default), reversing the effect of \verb+\pssilent+.\\[2pt]
\hline
\end{tabular}
\end{center}
\end{table}
%

\section{Installation}%
%
To correctly install Psfig, put the file psfig.sty on your file system 
in a place where \TeX\ will find it, 
such as in the TeX inputs folder (Textures), 
or in a directory on the \verb+TEXINPUTS+ path under Unix.
Consult your \TeX\ application's documentation or your system administrator.

If you are using a DVI translator other than dvips/Unix, 
you must change the definition of \verb+\setDriver+ in psfig.sty
slightly to customize psfig for your installation.
Under Unix, the definition is:
\begin{center}\verb+\def\setDriver{\DvipsDriver}+\end{center}
while under Textures (Macintosh) the correct definition is:
\begin{center}\verb+\def\setDriver{\TexturesDriver}+\end{center}
and under OzTeX (Macintosh) the correct definition is:
\begin{center}\verb+\def\setDriver{\OzTeXDriver}+\end{center}

%\newpage
\section{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 {\it 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 \Ps\
see {\it Psfig -- A Ditroff Preprocessor for PostScript Figures} in
the USENIX 87 proceedings, or {\it 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.
\par 
\end{document}
