.\" PSTEX.1
.\"
.\" $Log:	pstex.1,v $
.\" Revision 1.4  89/07/28  10:01:34  neil
.\" Removed some old references to .tps files.
.\" 
.\" Revision 1.3  89/07/28  09:50:55  neil
.\" Cleaned up, and removed some references to spar in pathnames.
.\" 
.\" Revision 1.2  88/09/09  10:48:22  hunt
.\" {file.ps} has been corrected to {file} in three places.
.\" 
.\" Revision 1.1  88/08/04  14:02:12  hunt
.\" Initial revision
.\" 
.TH PSTEX 1 "8 September 1988"
.CM 3
.SH "NAME"
pstex \- convert LaTeX figures.
.SH "SYNOPSIS"
.B
pstex
[ options ] file[\.tex]
.SH "DESCRIPTION"
\fIPstex\fP
is a BiBTeX-like processor for including figures into LaTeX documents.
Figures are included using the ``\\psbox'' macro;
this macro causes LaTeX to make entries in the ``.aux'' file(s) for the job.
\fIPstex\fP
finds these entries, locates the corresponding PostScript files
(which should be in EPSF format as appropriate for
\fIdvips\fP),
and determines how to size the figure according to the
options specified in the macro in the LaTeX, and
according to the nominal size and shape of the PostScript.
It creates a ``.psz'' file containing entries indicating
the sizes which it has determined to be appropriate for each figure.
When LaTeX starts up on subsequent passes, this ``.psz'' file is
read, and LaTeX is then able to leave the correct amount of space
for each figure as it encounters them in the text.
.PP
The ``postscript'' macro file must be included in the list
of options in the documentstyle command.
This defines the necessary macros.
.PP
The primitive which is used by \fIpstex\fP is
``\\postscriptbox{width}{height}{file}''.
This causes the postscript of file.ps to be included into the document
so that its bounding box exactly fills the width and height specified.
This creates a box, which is just like a character,
and can be placed anywhere in the document.
Typically it is included within a figure environment and a center environment,
and is associated with a caption.
.PP
The higher level macro which is provided by \fIpstex\fP
is ``\\psbox[options]{file}''.
.PP
If the options string is omitted completely,
the figure is included at its natural, or design size,
as specified in the bounding box data of the PostScript.
.PP
Combinations of four options can be specified, separated by commas:
\fIwidth=<width>\fP,
\fIheight=<height>\fP,
\fIaspect=<aspect>\fP, and
\fIscale=<scale>\fP
The keyword can be abbreviated, and spaces are allowed.
The width and height options can be any valid TeX or LaTeX which expands
into a dimension when placed as the argument to a
setlength macro.
For example, \fIwidth=\\columnwidth\fP is a common specification.
The aspect ratio and scale parameters must be floating point constants,
or must expand to such at the time the macro is first invoked,
for example \fIscale=0.7\fP.
.PP
If one of width or height is specified,
the figure is scaled to that size, keeping its natural aspect ratio,
unless that is overridden by the aspect parameter.
.PP
If both of width and height are specified, the figure is made
to fit the specification exactly, if necessary changing its aspect ratio.
In this mode, the aspect ratio parameter is ignored.
.PP
In any mode, the scale parameter multiplies all of the dimensions.
This is especially useful to include a figure at some fixed fraction
of its natural size, specifying only a scale factor in the options.
.PP
Note that the dimensions can be TeX rubber dimensions
so as to fit into the page layout in the best possible manner,
if desired.
.SH EXAMPLES
(Note that the slash characters below represent backslashes,
which are hard to include in troff text!)
.IP "\fI/psbox{file}\fP"
Include file.ps at natural size.
.IP "\fI/psbox[s=0.7]{file}\fP"
Include the document at natural size scaled down to 70%.
.IP "\fI/psbox[w=/columnwidth, scale=/mydocscale]{file}\fP"
Stretch the figure to the width of the column,
but scale it down to /mydocscale (which might be defined as 0.9 for example).
.SH "OPTIONS"
.IP "\fB\-z\fR \fIpsdirs\fR" 1.0i
Specify different area for postscript files to be included.
\fIPsdirs\fR will be  searched for all
postscript files, instead of the path specified in the environment variable.
.SH "ENVIRONMENT"
.IP "DVIPSPATH" 1.0i
A list of colon-separated directories where PostScript files may be found for
insertion.    It  defaults  to  ``:/usr/spar/font/ps''  which  means that the
current directory will be searched first and then the default directory.
.SH "FILES"
.IP "postscript.sty"
Macro file defining the macros for LaTeX.
.IP "jobname.aux"
contains pointers to \fIpstex\fP.
.IP "file.ps"
EPSF PostScript picture files.
.IP "file.psz"
File generated by \fIpstex\fP and read in by LaTeX to afford
communication.
.SH "SEE ALSO"
dvips(1), tex(1).
.SH "BUGS"
LaTeX forces a cumbersome interface on its preprocessors,
such as BiBTeX and \fIpstex\fP.
After adding a new figure, or changing the specification in the LaTeX,
you need to run LaTeX, then \fIpsbox\fP, then LaTeX again
to see the update results.
After a change to the PostScript, only the final LaTeX step is required.
.PP
It is very hard to get troff to put in backslashes in the documentation
in all the right places.  Some are missing, others are replaced by slashes.
.SH AUTHOR
\fIPstex\fP was written by Neil Hunt at Schlumberger Palo Alto Research,
now at Teleos Research:
Neil%Teleos.com@ai.sri.com