⟦f400452d6⟧

TextFile

%
% NB: I have made some changes to this document.
% 29 Aug 1989, Chris Torek
%
\documentstyle[12pt,psfig]{article}
%\psdraft
\pssilent

\newenvironment{smallquote}{\begin{quote}\small}{\end{quote}}

\begin{document}
\def\ps{{\sc Post\-Script}}

\title{Psfig/\TeX\ 1.1 Users Guide}
\author{Trevor Darrell\\
trevor@grasp.cis.upenn.edu\\
Computer and Information Science\\
University of Pennsylvania}
\date{July 1987}
\maketitle

\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/\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:

\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}}
}

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.

\section{Including a Figure}
You first must load the psfig macros at the 
beginning of your document.
In \TeX, add the line
\verb+\input psfig+
at the top of your file;
for \LaTeX, use the {\tt psfig} \verb+\documentstyle+ option.
Then, to include a \ps\ figure with psfig,
simply invoke the macro
\begin{smallquote}
\verb+\psfig{figure=+{\it input\/}\verb+}+
\end{smallquote}
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.

For example, if we have a file called `piechart.ps' which contains the
\ps\ code to draw the chart in the introduction, and it was the first figure
in our document, we might use the commands
\begin{smallquote}
\begin{verbatim}
\input psfig
\centerline{\psfig{figure=piechart.ps}}
\end{verbatim}
\end{smallquote}
or, for \LaTeX,
\begin{smallquote}
\begin{verbatim}
\documentstyle[psfig]{article}
\begin{document}
\centerline{\psfig{figure=piechart.ps}}
\end{verbatim}
\end{smallquote}
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{smallquote}
\begin{verbatim}
\psfig{figure=piechart.ps,height=1.5in}
\end{verbatim}
\end{smallquote}

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.

For example:\\
\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}
}}
was produced with:
\begin{smallquote}
\begin{verbatim}
\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}
}}
\end{verbatim}
\end{smallquote}

\subsection{Caveats}\label{sec:caveats}
For psfig to find the natural size of a figure, the figure must have a
proper bounding box comment; see Section~\ref{sec:bb} below.
Draft mode (also 
detailed below) should be used liberally to speed throughput. 
Also, sometimes
\LaTeX\ will fail to properly center a lone figure in a centering 
environment;
this can be fixed by preceding the figure with \verb+\leavevmode+.
On very large documents with many figures, the printer memory
allocated to {\tt pstex} may have to be limited. 
\ps\ files produced with ps4014 need to have the clipping boundary set;
see Section~\ref{sec:clipping} below.
Finally, the
\verb+\psfig+ macro will be confused by extra white space or newlines in its
argument.

\section{Generating \ps}
Before you can include a figure, 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, as in Figure~\ref{fig:wa}.
\begin{figure}
\centering
\leavevmode\psfig{figure=figs/pathtext.ps,height=2in}
\caption{A \ps\ Figure}\label{fig:wa}% `Woody Allen'
\end{figure}

\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~\ref{fig:mac}, left.)
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 such is detailed in \ref{app:mactohost}.

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 \verb+\psfig+ macro
to specify a file that
should be prepended to the figure.
The name of the prolog is, of course, site dependent;
the recommended location
is {\tt /usr/local/lib/tex/ps/mac.pro}.
For example, if you had a file {\tt frog.mac} that contained the Macintosh
code to draw Kermit (Figure~\ref{fig:mac}, right),
he could be included with:
\begin{smallquote}
\begin{verbatim}
\psfig{figure=frog.mac,prolog=/usr/local/lib/tex/ps/mac.pro}
\end{verbatim}
\end{smallquote}
\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}}
\caption{Macintosh figures.}\label{fig:mac}
\end{figure}
If there are many such figures,
the repeated inclusion of {\tt mac.pro}
will cause a significant increase in file size and
transmission time.
A better method is to load {\tt mac.pro} file once,
before the entire document,
e.g., by running {\tt pstex -I mac.pro \it myfile}.

\subsection{Images, Plot, and Other Sources}
Any program that produces \ps\ as output can be used for psfig figures.
For instance, the {\it ph} program\footnote
{Not included in this distribution.}
will convert a bitmap image
to \ps\ form, and thus can be
used to include an image in a document (Figure~\ref{fig:self}.)
There are similar utilities that can convert files
from {\sc unix} {\it plot\/}(5)
or Textronix~4014 format into \ps.

\begin{figure}
\centerline{
\vbox{\vss\psfig{figure=figs/trevor.ps,height=2in}\vss}
\hspace*{0.2in}{\psdraft\psfig{figure=figs/trevor.ps,height=2in}}
}
\caption{The author's image and draft equivalent}\label{fig:self}
\end{figure}

\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 concerned, but will just print the name of the file from 
which the figure is derived, and will not actually include it
(as in the right half of Figure~\ref{fig:self}).
The macro \verb+\psdraft+ will switch into draft mode, and all
subsequent \verb+\psfig+ macros will produce draft figures.
The macro \verb+\psfull+ will switch out of draft mode. 
These macros obey the usual \TeX\ grouping rules, as well.

\section{Bounding boxes}\label{sec:bb}
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 has defined a convention whereby the bounding box of a program
is contained in a `bounding box comment'.\footnote
{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{smallquote}
\tt \%\%BoundingBox:\ \it bbllx bblly bburx bbury
\end{smallquote}
All values are in \ps\ points (\TeX\ `big 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.

\section{Advanced Topics}
Casual users can safely skip this material unless they have run into 
one of the issues in Section~\ref{sec:caveats}.

\subsection{Internal Structure}
In including a figure, the \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 taken from
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.

The {\verb+\psfig{figure=+\it input\verb+}+} macro
uses a \verb+\vbox+ in \TeX\ to reserve the space for a figure.
The transformation of the \ps\ environment needed to
cause the figure to be printed at its desired location is 
done using \ps\ functions called with 
{\tt \verb+\special+}, as is the literal inclustion of the
text of the figure.\footnote
{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 Revew.}

\subsection{Reserved Size}
{\psfull%%%%% Temporary
\setbox0=\vbox
{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
`{\small\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.}
\dimen0=\ht0 \advance\dimen0\dp0 \advance\dimen0 2pt \dimen1=\wd0
\psfig{figure=figs/box.ps,rheight=0pt,rwidth=0pt,height=\dimen0,width=\dimen1}
\box0

}%%%%%% Temporary

The above was produced by putting the paragraph into a \TeX\ box
and finding its size automatically.
The commands used were:
\begin{smallquote}
\begin{verbatim}
\setbox0=\vbox{There are two ... this paragraph.}
\dimen0=\ht0 \advance\dimen0\dp0 \dimen1=\wd0
\psfig{figure=box.ps,rheight=0pt,rwidth=0pt,%
height=\dimen0,width=\dimen1}
\box0
\end{verbatim}
\end{smallquote}
The \ps\ code in {\tt box.ps} simply filled a grey box
whose lower left corner was $(0,0)$
and whose upper right corner was $(1,1)$.
(Note that the problem with newlines in the argument to \verb+\psfig+
can be circumvented by ending lines with `{\tt \%}', as above.)

\subsection{Clipping}\label{sec:clipping}
Normally a \ps\ program can be expected not to 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.
This is done by adding a clause of the form `{\tt clip=true}'.
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{\psfig{figure=figs/piechart.ps,height=2in,bbllx=306bp,bblly=396bp,bburx=486bp,bbury=546bp,clip=}}

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.

\subsection{Verbosity}
Normally \verb+\psfig+ prints messages about what it is doing.
These can be suppressed per invocation by the {\tt silent=} option,
or globally with the \verb+\pssilent+ declaration.
The latter form of silence
remains in effect until undone by \TeX\ grouping,
or until countermanded with \verb+\psverbose+.

\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.

It is very possible, however, for a \ps\ program to bypass the psfig
environment and disrupt a document. 

\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~\ref{fig:wa} and the three broken out figures in 
the introduction were taken from examples in {\it The PostScript Language
Tutorial and Cookbook.} 

\appendix

\def\thesection{Appendix \Alph{section}}% NB: cannot use subsections now!
					% (i.e., this is a hack)

\newpage
\section{\ps\ from a Macintosh}
\label{app:mactohost}
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.

Slightly trickier is getting the \ps\ code 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.

\newpage
\section{Installation}
This version of psfig/tex was written to use certain {\tt \verb+\special+}
calls implemented in ArborText's {\it dvips}
and in the MC-\TeX\ {\tt pstex} program.
It should be relatively
simple to port psfig to other {\tt DVI}-to-\ps\ programs
that support file inclusion.

The first step is to print out a draft copy of this
guide simply by running {\tt latex ug.tex},
which presumably you have already done. 
The rest are:
\begin{itemize}
\item
	Add the psfig \ps\ functions to the {\tt DVI}-to-\ps\ prolog,
	if necessary.
	They are already present in the prolog file
	included with {\tt pstex}.
\item
	Print a full copy of this document,
	by commenting out the \verb+\psdraft+ line
	near the top of this document,
	if it is not already commented out.
\item
	Copy {\tt psfig.tex} and {\tt psfig.sty}
	to well known locations,
	preferably in the \TeX\ and \LaTeX\ search paths,
	so everyone can find them.
\end{itemize}
For MC-\TeX, installation can be done simply by running {\tt make}
and then \mbox{\tt make install},
but be sure to check the {\tt Makefile} (or run \mbox{\tt make -n})
first.

\newpage
\section{Summary}
The following global \TeX\ or \LaTeX\ commands
are defined and/or used by {\tt psfig}:
\begin{center}
\begin{tabular}{ll}
\tt\string\psdraft & Sets draft mode \\
\tt\string\psfull & Sets full mode \\
\tt\string\pssilent & Turns off commentary \\
\tt\string\psverbose & Turns on commentary \\
\tt\string\typeout & Prints a message to the screen and to the log file \\
\tt\string\psfig & Includes a figure \\
\end{tabular}
\end{center}

The argument to \verb+\psfig+ is a comma-separated list containing
one or more of the following:
\begin{center}
\begin{tabular}{ll}
\tt figure=\it file & Defines the file to be included \\
\tt file=\it file & An alias for \tt figure \\
\tt clip=\it any & Clips to the bounding box \\
\tt bbllx=\it dim & Sets bb lower left x coordinate \\
\tt bblly=\it dim & Sets bb lower left y coordinate \\
\tt bburx=\it dim & Sets bb upper right x coordinate \\
\tt bbury=\it dim & Sets bb upper right y coordinate \\
\tt height=\it dim & Sets the height \\
\tt width=\it dim & Sets the width \\
\tt prolog=\it file & Defines a prolog file (to be included first) \\
\tt postlog=\it file & Defines a postlog file (to be included after) \\
\tt silent=\it any & Turns off commentary for this figure
\end{tabular}
\end{center}
Only the {\tt figure} (or {\tt file}) option is required.
The {\it any\/} arguments to {\tt clip} and {\tt silent}
are ignored;
the mere presence of the keyword (with equal sign)
is all that is necessary.

The \verb+\psverbose+ and \verb+\pssilent+ macros
are peculiar to the MC-\TeX\ version of psfig.
The {\tt silent} option is not,
but has no effect in some versions of psfig.

\end{document}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦f400452d6⟧ TextFile

Derivation

TextFile
