%
% psfrag.sty:  LaTeX style file for overlaying postscript text in a postscript
%              file (included via \epsfbox or \special) with arbitrary
% 	       fragments of LaTeX.
%
% Requirements:
%
%   You'll need the shell script ps2psfrag (which uses ghostscript from
%   the gnu distribution) and dvips (from Radical Eye Software, and
%   widely available at many TeX installations).  Other dvi to postscript
%   drivers will *not* work.  Do yourself a favor and get/use dvips.
%
% Usage:
%
%   - Include both the epsf and psfrag document style options.
%
%   - For each postscript file you should run the ps2psfrag script:
%
%           ps2psfrag example.ps
%
%     This uses ghostscript to generate the file example.psfrag (which
%     contains LaTeX source that describes all the postscript text that
%     example.ps places).  Since you'll need to run ps2psfrag every time
%     example.ps is modified, a makefile will save typing, eg:
%
%	# makefile for creating .psfrag files from .ps files
%	
%	.SUFFIXES: .ps .psfrag
%	
%	all:	example.psfrag another.psfrag andagain.psfrag
%	
%	.ps.psfrag:
%		ps2psfrag $*.ps
%
%   - There are two methods to replace postscript text with LaTeX fragments
%     (they can be mixed):
%
%     + Embedded (method 1): postscript text that looks like the macro
%
%	  \tex[posn][psposn][scale][rot]{LaTeX text}
%
%       is replaced by the LaTeX text in the argument.  The four optional
%       arguments are the same as for \psfrag and are explained below.
%
%	Note that if this string is too long it could affect the postscript
%	file's bounding box.  You should use method 2 if the LaTeX text is
%	long or if having "\tex[]...{}" appear all over your picture clutters
%	things up too much.
%
%     + Replacement (method 2): in your LaTeX source specify how each piece
%       of postscript text should be replaced:
%
%	  \psfrag{name}[posn][psposn][scale][rot]{LaTeX text}
%
%       The "name" argument is the postscript text to replace.  Make the
%       name alphanumeric and short (don't use braces, backslashes etc!).
%
%	All the \psfrag calls that apply to a particular postscript file
%	should immediately precede the file's \epsfbox or \special.
%	The whole thing should be enclosed in a psfrags environment
%	(this environment simply delimits the scope of the fragments
%	defined with \psfrag, so any enclosing environment (like figure etc)
%	will do instead).
%
%   - There are two ways to include the postscript file:
%
%     + \epsfbox: you can use \epsfbox in the usual way (together with its
%	usual scaling options).
%
%     + \special: if you insist on directly calling \special yourself,
%       then you should call the macro \psfragspecial instead:
%
%         \psfragspecial{psfile}{hscale}{vscale}{hoffset}{voffset}{otherArgs}
%
%       (eg: \psfragspecial{example.ps}{80}{80}{23}{-10}{})
%
%       This \inputs the fragment file (<psfile> + "frag") if it exists,
%	and then it does a normal \special by concatenating the arguments.
%	The first five arguments are exactly the arguments to dvips'
%	\special ([hv]scale are in percent, and [hv]offset are in bpoints).
%	Any extra \special arguments can be passed in using otherArgs.
%
%   - Postscript text that is replaced (or starts with "\tex") will not be
%     shown when the dvi file is printed with dvips.  For debugging purposes
%     you may wish to still show the replaced postscript text.  Two macros
%     enable and disable showing of replaced postscript text:
%
%	   \psfragshowall     - show all postscript text
%	   \psfragshowdefault - don't show postscript text that is replaced
%
%     Each declaration stay in effect until the next.  The default is
%     \psfragshowdefault.
%
% Position options:
%
%   The \tex "macro" and \psfrag macro take four optional positioning
%   arguments:
%
%	In postscript:    \tex[posn][psposn][scale][rot]{LaTeX text}
%	In LaTeX source:  \psfrag{name}[posn][psposn][scale][rot]{LaTeX text}
%
%   The first two positioning arguments specify how the bounding box of
%   the LaTeX text and bounding box of the postscript text line up.
%   By default, the bottom-left corner of the LaTeX text is placed at the
%   bottom-left corner of the postscript text:
%
%    <posn>   - LaTeX text reference point.  Up to two letters from the set
%	        {tblr} (as per LaTeX's \makebox position argument).
%	        Specifies one of 9 anchor points for the LaTeX text
%	        (eg: [tl] top left, [t] middle top, [] overall center etc).
%	        Default is [bl].
%
%    <psposn> - Where the LaTeX text's reference point is attached to the
%	        PostScript text.  Up to two letters from the set {tblr}.
%	        Default is [bl].
%
%   The LaTeX text may be optionally scaled and rotated about its reference
%   point:
%
%    <scale>  - LaTeX text size scale (default 1).  It's best if you use font
%	        size changes in the LaTeX text rather than scale, but you can
%               use the scale to tweak its size.  Default is [1].
%
%    <rotn>   - Extra rotation of LaTeX text about its reference point in
%	        degrees.  Nominal rotation of LaTeX text matches the postscript
%	        text that it is replacing.  The total rotation is the nominal
%	        rotation plus <rotn>.  Default is [0].
%
% Example:
%
%   - A typical figure might look like:
%
%	\begin{figure}
%	\begin{center}
%	\begin{psfrags}
%	    \psfrag{u}[b][tr]{$u = 1 + \gamma$}
%	    \psfrag{y}[][bl]{$\hat{y}$}
%	    \psfrag{z}[][]{output $z$}
%	    \epsfxsize=4in\leavevmode\epsfbox{example.ps}
%	\end{psfrags}
%	\end{center}
%	\caption{This is an example.}
%	\end{figure}
%
%     This replaces the postscript text "u" with $u = 1 + \gamma$.  The
%     middle-bottom of $u = 1 + \gamma$ is placed at the top-right of "u".
%     Similarly, the overall middle of $\hat{y}$ is placed at the bottom
%     left of the postscript text "y", and the overall middle of $z$ is
%     placed at the overall middle of the postscript text "z".  The
%     postscript file is centered with an x width of 4 inches.
%
%   - Embedded replacements can be performed in matlab with:
%
%	t = 0:.1:10;
%	plot(t, sin(t));
%	title('\tex[b][b]{Plot of $\sin(t)$}');
%	xlabel('\tex[t][t]{$t$}');
%	ylabel('\tex[b][b]{$\sin(t)$}');
%	text(t(30), sin(t(30)), 'p1');
%	text(t(60), sin(t(60)), 'p2');
%	special('example');
%
%     The middle-bottoms of the title and y axis label are aligned, as well
%     as the middle-top of the x axis label.  A suitable source file is:
%
%	\documentstyle[12pt,epsf,psfrag]{article}
%	\begin{document}
%	
%	This is a test.
%	\unitlength=1in
%	\begin{psfrags}
%	    \psfrag{p1}{\begin{picture}(0,0)
%		    \put(0.25, 0.1){\makebox(0,0)[l]{$\sin(t)$}}
%		    \put(0.2, 0.1){\vector(-2,-1){0.2}}
%		\end{picture}}
%	    \psfrag{p2}{\begin{picture}(0,0)
%		    \put(0,0){\circle*{0.05}}
%		\end{picture}}
%	    \epsfbox{example.ps}
%	\end{psfrags}
%	\end{document}
%
%     This replaces "p1" with a picture that includes a vector and some
%     text, and "p2" with a small circle.
%
%     (Note that matlab shifts text shown with text() up by 2.28 points
%     (4 * 0.57) relative to plot(), so you should use the command
%
%	ps2psfrag -dy -2.28 example.ps
%
%     to create the example.psfrag file.  Otherwise the circle and vector
%     above won't quite line up with the plotted curve.)
%
% Bugs:
%
%   - Everything relies on the program generating the postscript to use a
%     single postscript "show" for each piece of text displayed.  If this
%     program splits strings into lots of smaller shows, then try mono-spaced
%     fonts, and shorter strings.  If this program strokes out the characters
%     or uses other methods to draw text then you are SOL.
%
%   - The LaTeX fragments always appear on top of the postscript graphics.
%     Even if part of the original postscript text was covered by postscript
%     graphics, the LaTeX fragment will be on top.
%
%   - If the first thing in a LaTeX document is a float (eg: figure) the
%     preamble \special{}s in psfrag.sty don't make it into the dvi file.
%     This causes everything to break: you will see a wierd errors from
%     ghostscript or your print daemon.  The solution is to make sure that
%     you always have something (even an empty box) between your
%     \begin{document} and your first float (eg: figure).
%
% Written by Craig Barratt, Sat Feb 29 16:35:50 PST 1992
% (craig@isl.stanford.edu)
