⟦ce8121423⟧

TextFile

\documentstyle{article}
\begin{document}
\input ../psfig.tex
\psdraft
\pssilent
\def\Ps{Post\-Script}
%
\title{Psfig/\TeX\ 1.2 Users Guide}
\author{Trevor Darrell\\
trevor@grasp.cis.upenn.edu\\
Computer and Information Science\\
University of Pennsylvania}
\date{\ }
\maketitle
%
\section{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 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 possible to merge graphics
directly into a document. 
Psfig/\TeX\ is a 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.
Some possible figures include:
\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,silent=}' and 
`\psfig{figure=figs/cm.ps,height=8pt,silent=}'
may be created and used freely throughout a document. 
%
\newpage
\section{Simple figures}
To include a \Ps\ figure with psfig, first load the psfig macros at the 
beginning of your document with
\begin{quote}
{\tt\verb+\input{psfig}+}
\end{quote}
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 conflict
with any other objects on the page.
\par
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.
By listing both a {\tt height} and a {\tt width}, figures can be scaled 
disproportionately, with interesting results.
\par
\begin{figure}
\centerline{
\psfig{figure=figs/lab2.ps,width=3.25in,prolog=figs/mac.pro}}
\vspace{.25in}
\centerline{Figure 1: A figure produced by MacDraw}
\end{figure}
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
\section{Macintosh files}
Since the
Macintosh drawing applications produce \Ps, 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.
\par
Before including a Macintosh figure in your \TeX\ document, it must be
created
on the Macintosh and moved to the host on which \TeX\ is running 
(assuming the two are not the same nor share filesystems.)
\par 
As of this writing,
it is possible to convince MacDraw to place a \Ps\ description of a
figure in a file
rather than sending it directly to a LaserWriter by
hitting clover-F { \it immediately } after clicking `OK' on the print
dialog box. The file is always called `PostScript' and is left in 
the folder MacDraw was started in. Use a communications program to 
move the file over to the host on which \TeX\ is running.
\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 we call the `Macintosh prolog', which must be prepended 
to any Macintosh file before being sent to the printer. 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.
\par
Some versions of MacDraw and the Macintosh LaserWriter driver do not
include a bounding box comment in the \Ps\ files they produce; figures
created by these systems will have to have their bounding box added manually
(see section 6.)
\par
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 a floor-plan (figure 1).
\begin{quote}
{\tt\verb+\+psfig\{figure=lab.ps,prolog=mac.pro\}\}}
\end{quote}
If there are many such figures, it is probable that the repeated inclusion
of the mac.pro file will cause a significant increase in 
transmission and printing time.
A better method is to load the mac.pro file once, concatenating it 
before the entire document (using {\tt psprint -m}, on our systems,) and 
ommiting the prolog clause from each psfig command.
\par
\section{Other sources of figures}
\hbox{
\vbox{\psfig{figure=figs/trevor.ps,height=1in}}
\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 bounding box comment convention (see below).
For instance, the {\it ph} program was used to convert a bitmap image
of the author into \Ps\ form and included as a figure at left.}\vspace{.2in}}}
\par
\section{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 {\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 intermediate versions of the document.
A figure printed in draft mode will occupy the proper space as far
as \TeX\ is concerned but no \Ps\ code will be executed to print it.
If psfig is not in silent mode, it will also print the name of the
\Ps\ file in the space reserved for the figure. No {\tt \verb+\+special}'s
are used in draft mode; thus any dvi processor can be used.
\par
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. 
\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[1]{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
The bounding box values may be specified directly on the psfig macro,
using clauses {\tt bbllx=\it bbllx},{\tt bblly=\it bblly},..., in
which case the file is not searched for the bounding box.
\section{Reserved size}
\par
\psfig{figure=figs/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 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.
\section{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 specify a bounding box so as 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{\protect\fbox{\psfig{figure=figs/piechart.ps,height=2in,bbllx=306bp,bblly=396bp,bburx=486bp,bbury=546bp,clip=}}}
\centerline{A piece of the pie.}
\vspace{.2in}
\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.
\section{\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.
\footnote[2]{For more detailed information about \Ps\ issues in the
internals of psfig, 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.}
\par 
It is very possible, however, for a \Ps\ program to bypass the psfig
environment and disrupt a document. 
\section{Caveats}
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 documents with complicated figures, the printer memory
allocated to dvips may have to be limited to avoid vmerrors.
\Ps\ files produced from Adobe's ps4014 need to have the clipping boundary set.
Finally, the
\verb+\psfig+ macro will be confused by white space or newlines in its
argument.
\section{Acknowledgements}
\par
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.
The three broken out figures in 
the introduction were taken from examples in {\it The PostScript Language
Tutorial and Cookbook.} Thanks to Ira Winston and the CIS department for
supporting this work.
\par 
\newpage
\appendix
\section{Installation, and Availability}
\par
Version 1.2 of psfig/tex is supported for the {\it dvips} and {\it dvi2ps}
\footnote[3]{Version 1.0BETA by Stephan Bechtolsheim (i5f@l.cc.purdue.edu)}
postprocessors. It is available via anonymous ftp from linc.cis.upenn.edu,
in the directory {\tt ~ftp/dist/psfig} as the file {\tt tex.tar.Z.}
\par
The first step to install psfig is to print out a draft copy of this
guide simply by running {\tt latex ug.tex},
which presumably you have already done. All {\it psfig} files mentioned are
relative to then {\tt psfig/tex} directory on the distribution.
\subsection{Install psfig.pro}
\sloppy
For {\it dvips}, append the file {\tt dvips/psfig.pro} to the end
of the {\tt dvips.pro} file that {\it dvips} includes each time it
processes a document.
\par
For {\it dvi2ps}, copy {\tt dvi2ps/psfig.pro} into the {\it dvi2ps}
\Ps\ driver directory (determined by the {\tt \verb+PS_DRIVER_DIR+}
variable in the
{\tt local-defs} file of the {\it dvi2ps} distribution).
\subsection{Install psfig.tex}
\sloppy
Copy {\tt dvips/psfig.tex} (for {\it dvips}), or {\tt 
dvi2ps/psfig.tex} (for {\it dvi2ps}), into a directory \TeX\ will
search when resolving {\tt \verb+\+input} commands.
\subsection{Print a full copy of this document}
Comment out the first line that contains {\tt \verb+\+psdraft } from the file
{\tt ug.tex}, then {\tt make}. Print {\tt ug.ps}.
\end{document}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦ce8121423⟧ TextFile

Derivation

TextFile
