⟦8b59dede8⟧

TextFile

% To generate this part of the document go to directory "doc"
% and make "make ../psfig/psfig.dvi".
\InputD{../psfig/psfig.tex}
\psfull

\chapter{Psfig 1.4}
% =================
\label{c-psfig}

\section{An Introduction before the Introduction}
% ===============================================
	Trevor Darrell (trevor@paddington.media.mit.edu), the author
of psfig, a macro package to include \PS{}
figures into \TeX{} gave me permission to directly include his
documentation into my document.
I edited the following documentation only to
accommodate my way of presenting things in this document. I also made some
small changes reflecting my changes I made to psfig. Those changes
are minor and there should be no problem using psfig with my driver.

	I also made some changes to more clearly explain some of the points
below.

	Observe that this part of the documentation as all the other parts of
the documentation serve as a testbed and a source for examples for you in
case you have difficulties applying those macros.

	Trevor Darrell's affiliation was Computer and Information Science, University of
Pennsylvania at the time these macros were developed. He is currently at
MIT (see above for the email address).

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

\hbox{
	\hspace{.3in}
	\vbox{% 
		\psfig{figure=../psfig/ps-ex/zip.ps}% 
		\vspace{.5in}%
	}% 
	\psfig{figure=../psfig/ps-ex/piechart.ps,height=1.5in}%
	\vbox{% 
		\psfig{figure=../psfig/ps-ex/starlines.ps}% 
		\vspace{.6in}% 
	}
}

By the way, the file {\tt zip.ps} looks as follows:

{\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/zip.ps}
}

And the file {\tt starlines.ps} looks as follows:

{\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/starlines.ps}
}
	Custom characters such as
``\psfig{figure=../psfig/ps-ex/pretzel.ps,height=8pt,silent=}'' and 
``\psfig{figure=../psfig/ps-ex/cm.ps,height=8pt,silent=}''
may be created and used freely throughout a document. 

By the way, the file {\tt cm.ps} looks as follows:

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/cm.ps}
}

And here is file {\tt prezel.ps}:

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/pretzel.ps}
}

\section{Simple Figures}
% ======================
	To include a \PS{} figure with psfig, first load the psfig macros at the 
beginning of your document with
\btex
	\input psfig.tex
\etex
\noindent 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.

	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
\btex
\centerline{\psfig{figure=piechart.ps}}
\etex
\noindent 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:
\btex
    \centerline{\psfig{figure=piechart.ps,height=1.5in}}
\etex
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.

	Note that the {\tt psfig} macros use the environment variable {\tt TEXINPUTS}
to locate the \PS{} files to be included because \TeX's \verb+\input+ command
is used to read in those files.

\begin{figure}
\centerline{
  \psfig{figure=../psfig/ps-ex/lab2.ps,width=3.25in,prolog=mac.pro}}
\vspace{.25in}
\caption{A figure produced by MacDraw}
\label{f-macdraw}
\end{figure}
For example:

\centerline{% 
    \hbox{% 
        \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=.15in}
        \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=.35in}
        \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in}
        \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=1.2in}
        \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=1.5in}
    }% 
}
\noindent was produced with:
\btex
    \centerline{% 
        \hbox{% 
            \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=.15in}
            \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=.35in}
            \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in}
            \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=1.2in}
            \psfig{figure=../psfig/ps-ex/rosette.ps,height=.8in,width=1.5in}
        }% 
    }
\etex

The file {\tt rosette.ps} reads as follows:

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/rosette.ps}
}

\section{{\tt figure=} and {\tt file=}}
% =====================================
Note that instead of {\tt figure=} you can use {\tt file=} in a
\verb+\psfig+ call. There is no difference among the two.

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

	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 file systems.)
 
	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
dialogue 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.

	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.

	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 \SectionRef{s-psfig-bb}, \page{}.

	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 (\FigRef{f-macdraw}, \page{}).
\btex
    \psfig{figure=lab.ps,prolog=mac.pro}
\etex

	Prologue files are ownly downloaded once. This is automatically
handled by the driver.

\section{Other Sources of Figures}
% ================================
\hbox{% 
	\vbox{\psfig{figure=../psfig/ps-ex/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 the left.}
		\vspace{.2in}
		}% 
}

\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 \verb+\pssilent+, and re-enabled with
\verb+\psnoisy+.

	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 \verb+\special+'s
are used in draft mode; thus any dvi processor can be used.

	The macro \verb+\psdraft+ will switch into draft mode, and all
subsequent psfig macros will produce draft figures until reaching the
macro \verb+\psfull+, which switches out of draft mode. 

\section{Bounding Boxes}
% ======================
\label{s-psfig-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 conforming \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{See ``Appendix J: PostScript File Structuring Conventions' in
{\it The PostScript 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.

	The bounding box values may be specified directly calling \verb+\psfig+,
using clauses {\tt bbllx=\it bbllx}, {\tt bblly=\it bblly}, \dots, in
which case the file is not searched for the bounding box.

\section{Bounding Boxes Example}
% ==============================
	Here is a brief example which should explain the bounding box idea
once more. First of all here is the \PS{} code of the example used (file
{\tt boxbbex.ps}):

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/boxbbex.ps}
}

	Now note the definition of the bounding box in this case. The \PS{}
program draws a diagonal line with a rectangle with a rectangle hanging
off the right upper end of this diagonal line. The bounding box is
defined in such a way that it sourrounds the rectangle with a 10~pt wide
strip between the rectangle and the bounding box. Note that the bounding
box does {\it not\/} include the part from (0,~0) to (90,~90) of the
diagonal line (therefore strictly spoken the bounding box comment is
incorrect). Therefore the space reserved by the psfig macros do not
include that part of the diagonal line.

	Here now is the figure generated by the following macro call:
\btex
	\centerline{\HboxR{\psfig{figure=../psfig/ps-ex/boxbbex.ps}}}
\etex
	\centerline{\HboxR{\psfig{figure=../psfig/ps-ex/boxbbex.ps}}}

\section{Reserved Size}
% =====================
	The following text was generated using the following instruction: 
\btex
\psfig{figure=../psfig/ps-ex/box.ps,rheight=0bp,rwidth=0bp,% 
	height=63pt,width=\textwidth,silent=}
\etex

\vbox{% Prevent page breaks
	\psfig{figure=../psfig/ps-ex/box.ps,rheight=0bp,rwidth=0bp,% 
		height=63pt,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 {\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.

}

	The file {\tt box.ps} looks as follows:

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/box.ps}
}

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

\centerline{\protect\fbox{\psfig{figure=../psfig/ps-ex/piechart.ps,% 
		height=2in,bbllx=306bp,bblly=396bp,bburx=486bp,bbury=546bp,clip=}}}
\centerline{A piece of the pie.}
\vspace{.2in}

	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.

	By the way, the file ``piechart.ps'' reads as follows:

{
	\VerbatimTab = 8
	\ListVerb{../psfig/ps-ex/piechart.ps}
}

\section{{\tt scale=}}
% ====================
\label{s-scale}
The {\tt scale} parameter in a \verb+\psfig+ call\footnote{Stephan
v.~Bechtolsheim added this feature to the psfig macros} scales X~and
Y~axis of a document by the same factor. This factor is not only applied
to the figure itself but also to the reserved size (in \TeX) for printing
the figure. For an application \see{s-xwindows}.

\section{Including \TeX{} Output}
% ===============================
	Using our driver and producing a \PS{} file with it it is actually
possible to include s \TeX{} document within a \TeX{} document.  If you
ever should be interested in that I recomment that you look into file {\tt
examples3.tex} of the sources. The related output appears in
Figs.~\ref{f-root-1.ps} through~\ref{f-root-4.ps},
pages~\pageref{f-root-1.ps}--\pageref{f-root-4.ps}.

\section{\protect\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{For more detailed information about PostScript 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.}
 
	It is very possible, however, for a \PS{} program to bypass the psfig
environment and disrupt a document. 

\section{Caveats}
% ===============
	\PS{} files produced from Adobe's ps4014 need to have the clipping boundary set.
The \verb+\psfig+ macro will be confused by white space or newlines in its
argument.

\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.
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.
 
\section{Copyright}
% =================
\label{s-copyright-psfig}
	The copyright applying to this macro package is identical to the
copyright applying to the \TeXPS{} package. The only exception is that
the person owning the copyright is Trevor Darrell, not Stephan
v.~Bechtolsheim.

\section{Installation, Availability}
% ==================================
	With the \TeXPS{} software I distribute version 1.3 of psfig. This
version is almost identical to version~1.2 except for some small
improvements and adoptions to the \TeXPS{} software package I made. One
of the changes I made was to systematically replace all dimension and
counter registers used. In the psfig 1.2 version counter registers were
addressed by numbers (like \verb+\count100+). I inserted a number of
\verb+\newcount+ (and \verb+\newdimen+) instructions and replaced these
explicit counter (and dimension) register numbers by the names of
allocated registers.

	There are three files to the psfig macros which are installed when
running {\tt make install} in the top level source directory.
\begin{enumerate}
	\item {\tt psfig.tex}. These macros can be found in directory {\tt psfig}
		and they are installed by running {\tt make install} in this directory.
	\item {\tt psfig.prs}. This prologue file can be found in {\tt
		dvitps/prs} and is installed by running {\tt make install} in
		this directory.
	\item {\tt mac.pro}. This prologue file can also be found in {\tt
		dvitps/prs} and is installed the same way.
\end{enumerate}

\section{Including a XWindow 11.3 Dump into a Document}
% =====================================================
\label{s-xwindows}
	Let me now discuss how the psfig macros can be used to include an XWindow
screen dump into a document. For the following you may look into
pages~66, 67 and 204--206 of the ``X~Window System Users Guide'' of
Volume Three.

\subsection{Basics}
% =================
Here is how you proceed to include an X~Window System screen dump into
your document:
\begin{enumerate}
	\item Use {\tt xwd} to generate the window dump, for instance,
		\verb+xwd > example.xwd+ generates such dump.
	\item Convert this dump into a \PS{} file using {\tt xpr} as follows:
		\verb+xpr -portrait -device psfig example.xwd > example.xps+.
		Note in particular:
		\begin{enumerate}
			\item The version of {\tt xpr} you are using for this
				operation must be patched. This will be discussed
				shortly.
			\item You must use portrait mode. Force portrait mode by
				using option {\tt -portrait} on the command line.
			\item You must use the device {\tt psfig}, which generates a
				suitable bounding box comment. This ``device'' is only
				understood by the patched {\tt xpr}.
		\end{enumerate}
	\item Now include this dump using \verb+\psfig+ as if it were a
		regular \PS{} figure. Note in particular:
		\begin{enumerate}
			\item The default size, unless the dump is scaled, is 1~bp to
				a pixel. That means a 1024 pixel wide dump will be
				${1024\over 72} \approx 14.25$~in wide. Too wide, of
				course, so you must use {\tt scale} to scale the dump
				down. {\tt scale = 30} means the width is reduced by a
				factor of 0.3, and the dump is now $\approx 4.3$~in wide.
				\See{s-scale}, for an explanation of the {\tt scale}
				parameter of \verb+\psfig+.
			\item There is no way around guessing this scaling factor,
				but for smaller windows a factor of 0.5 seems to be
				a good starting point. Note that you may want to keep
				this scaling factor the same throughout all dumps within
				one document, i.e., you may define a macro which sets
				this scaling factor.
		\end{enumerate}
\end{enumerate}

\subsection{Example of an X Window Screen Dump}
% =============================================
% Now let me see whether we can include the xwindow dump.
\input ../psfig/xwindows.tex
\ifnum\XWindowsAvailable = 0
	No XWindow dump was included here because you do not have XWindows available
	on your machine according to the settings of variables in {\tt local-defs}.
\else
	The following command generated the XWindow dump in \FigRef{f-wd},
	\page{}.
\btex
	\centerline{\psfig{figure=../psfig/example.xpr,scale=70}}
\etex
	
\begin{figure}
	\centerline{\psfig{figure=../psfig/example.xpr,scale=70}}
	\caption{X Window screen dump example}
	\label{f-xw}
\end{figure}
\fi

\subsection{The {\tt xpr} Patch}
% ==============================
I will now briefly list the patch which should be applied to {\tt xpr}.
I suggest that you proceed as follows:
\begin{enumerate}
	\item Go to the source directory of your X~Window System sources,
		find directory {\tt clients/src} and first recompile the
		standard {\tt xpr}, just to make sure that you can.
	\item Now apply the patch which can be found in directory {\tt
		psfig}, file {\tt xpr.patch}, and recompile {\tt xpr}.
	\item Now I recommend that you replace the {\tt xpr} you have
		installed by the new {\tt xpr}, because the new {\tt xpr} is
		upward compatible.
	\item Edit {\tt local-defs} to reflect the fact that you have now a
		patched version of {\tt xpr} available.
	\item Go into directory {\tt doc} of the \TeXPS{} software and do a
		{\tt make ../psfig/psfig-doc.ps} and print the resulting file.
\end{enumerate}

	Here is the patch, by the way:
\ListVerb{../psfig/xpr.patch}

\section{The Psfig Source Code}
% ===============================
	Let me reprint some of the psfig related source code here.

\subsection{The Psfig Macros}
% ===========================
Let me quickly reprint the Psfig \TeX{} macros here. Before I do this
some comments on some of the macros used internally. In the following
note that all dimensions are represented in {\it integers}, based on the
unit scaled points. Note though that the dimension unit is omitted, in
other words a dimension below is a pure integer.
\begin{enumerate}
	\item \verb+\@bbw+, \verb+\@bbh+: width and height of the bounding
		box, intermediate value.
	\item \verb+\@p@sbburx+, \verb+\@p@sbbury+, \verb+\@p@sbbllx+,
		\verb+\@p@sbblly+: coordinates of the corners of the bounding
		box.
	\item \verb+\@p@sheight+, \verb+\@p@swidth+: height and width as
		registered by the \PS{} printer. This is how much space should be
		used by the \PS{} code generating the figure.
	\item \verb+\@p@srheight+, \verb+\@p@srwidth+: amount of space saved
		in \TeX{} to include the figure later.
\end{enumerate}

Here is finally the reprint of the complete psfig macros:
\ListVerb{../psfig/psfig.tex}

\subsection{The Psfig \protect\PS{} Macros}
% =========================================
	Here is a listing of the prologue file loaded by the driver to include
\PS{} figures using psfig.
\ListVerb{../dvitps/psr/psfig.psr}
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦8b59dede8⟧ TextFile

Derivation

TextFile
