psfig/tex 1.2 -- TeX macros for the inclusion of postscript figures

=====
All software, documentation, and related files in this distribution of
psfig/tex are Copyright (c) 1987 Trevor J. Darrell

Permission is granted for use and non-profit distribution of psfig/tex 
providing that this notice be clearly maintained, but the right to
distribute any portion of psfig/tex for profit or as part of any commercial
product is specifically reserved for the author.
=====

Psfig/tex uses \special calls to manipulate the PostScript environment
within a document and include figure files. Version 1.2 of psfig/tex
is supported for the following PostScript drivers:

	"dvips", a commercial product from ArborText
	"dvi2ps-svb"
		dvi2ps by Stephan Bechtolsheim, copyrighted but free
		**This version has not been generally released
		yet. Contact Stephan (if5@l.cc.purdue.edu) for
		availability**

	"dvi2ps-li"
		The common dvi2ps, modified for psfig by Tony Li
		(tli@sargas.usc.edu), originally by Mark Senn
		 and many others.

	"dvi2ps3.0"
		The common dvi2ps, various versions merged by Kevin
		Coombes (kevin@math.lsa.umich.edu). This re-distribution
		only includes psfig support for dvi2ps3.0. A full
		distribution can be obtained by anonymous ftp from
		linc.cis.upenn.edu.

====
Installation

Print a draft copy of the manual:	

% cd usrguide

Now make and print the document. If you do not yet have a version of
dvi2ps which supports psfig, you should make a draft copy. Make sure that
the fourth line of the document, namely,
%\psdraft
has not been commented out.  

% make
% lpr -Plw ug.ps

Now read the Appendix entitled "Installation."

====
Description

psfig.tex :
        the tex macros that are the backbone of psfig/tex.
        they should be included at the beginning of any
        document that intends to use psfig/tex

psfig.pro :
        the postscript support for psfig.tex. Here at upenn,
        we have inserted this into the dvips prolog, so it
        need not be included explicitly. If it is not included
        in the dvips prolog, it must be included with a 
        \psfiginit after \input{psfig}, and page-reversing
        will cause complications.

psfig.l :
	the unix manual page.

psfig.sty :
	a style file for using psfig with latex.

usrguide :
	a directory containing a manual written in latex.

====
Advice on debugging psfig/tex problems

In the ideal world, document debugging tools would be paid the same attention
as program debugging tools. In the real world, this is not the case, yet with
packages of ever increasing sophistication such as TeX debugging a docuement
is becoming no less problematic that debugging 'C'. Having experience in 
such matters I would say debugging 'C' (or most other programming enviorments)
is much more conducive to retaining one's sanity.

Anyway, with proper care and feeding psfig will grow up to be a well used
tool in your bag of tricks. It can be eased through the problem years with the
following hints on common problems:
-----

if a document crashes (stops printing and flushes the job) on or about
a figure, the figure probably has some illegal postscript in it, or
uses macintosh calls and the prolog was not properly loaded. Finding
the offending command by reading the error message from the printer or
using an error trapping utility is critical. Either use the error
handler distributed to the laser-lovers board some time ago, or
moniter the errors coming back from the printer. If the offending
command is "psu" you can bet your mac prolog is missing. Check for
problems with page reversing and psglobal (they dont mix well)

if a document stops printing at some random point (but may continue to
accept data) the printer memory may have been exceeded (VMErrors).
This usually becomes a factor on papers exceeding twenty pages (using
our installation). Use the printer memorysize option to dvips to
remedy this; the optiumum value is not yet known -- I use 60000 for
our laserwriter when I run into trouble, and it usually gets me out of
the woods. Some people have had rather severe problems printing the
documentation and have had to limit memory to <20000.

if a figure consistantly comes out at the same place on the page despite
psfig's valiant attemps to move it about, it is probably using the clippath
to decide where it should print. Use the clip option (see the manual)

if a figure is comming out out of position, it may be that the bounding box is
in error, test the bounding box by printing the figure alone and using a ruler

and last, but not least,
a lone psfig in a centering enviornment will be ignored by LaTeX; try
preceeding it by a hard space or some similar hack.

