%% pfgguide.dtx Copyright (c) 1995 Michael C. Grant and Craig Barratt
%%              All rights are reserved.
%%
%%            This system is distributed in the hope that it will be
%%            useful, but WITHOUT ANY WARRANTY; without even the 
%%            implied warranty of MERCHANTABILITY or FITNESS FOR A
%%            PARTICULAR PURPOSE. Don't come complaining to us if you
%%            modify this file and it doesn't work! If this file is
%%            modified by anyone but the authors, those changes and
%%            their authors must be explicitly stated HERE.
%%
\documentclass[11pt]{ltxguide}
\usepackage{graphicx,psfrag,shortvrb}

% I prefer more to a page.
\marginparsep 0pt \oddsidemargin 0pt \evensidemargin 0pt
\textwidth \paperwidth \advance \textwidth by-2in
\topmargin 0pt \headheight 0pt \headsep 0pt
\textheight \paperheight \advance \textheight by-2in

\let\package\textsf
\newcommand{\pfg}{\package{PSfrag}}
\newcommand{\eg}{\emph{e.g.}}
\newcommand{\etc}{\emph{etc.}}
\newcommand{\netaddress}[1]{\texttt{#1}}
\MakeShortVerb{\|}
\def\cs#1{%
  {\ttfamily\expandafter\string\csname #1\endcsname}}
\providecommand\marg[1]{%
  {\ttfamily\char`\{}{\em#1\/}{\ttfamily\char`\}}}
\providecommand\oarg[1]{%
  {\ttfamily[}{\em #1\/}{\ttfamily]}}
\providecommand\parg[1]{%
  {\ttfamily(}{\em #1\/}{\ttfamily)}}

\title{The \pfg\ system}
\author{Craig Barratt \thanks{This author is no longer participating in
        the development of \pfg.} \\ \netaddress{craig@arraycomm.com} \and
        Michael C. Grant \\ \netaddress{mcgrant@isl.stanford.edu}}
\date{10 March 1995}

\begin{document}

\maketitle
\tableofcontents

\section{What is \pfg?}

Many drawing and graphing packages produce output in
PostScript, but do not support the inclusion of equations and
other scientific text of which \LaTeX\ is capable. Likewise,
many \LaTeX\ users simply find the various \LaTeX\ graphics packages
too clumsy, and prefer the familiar GUI of a PostScript-generating
graphics tool. 

\pfg\ provides the best of both worlds, by allowing the user
to replace arbitrary text in Encapsulated PostScript (EPS) files with
arbitrary \LaTeX\ constructions. For example, one can place a
simple text ``anchor'' in the graphics file to denote the position
of a desired \LaTeX\ equation, and \pfg\ will automatically remove
that anchor and replace it with a properly sized, aligned, and
rotated \LaTeX\ equation.

\section{\pfg\ necessities}

In order to view documents whose figures have already been processed
by \pfg, then you must have the following tools:
\begin{itemize}
\item \LaTeXe\ and the \package{graphics} package. Note that to
      achieve the same functionality as found in the original
      \LaTeX\ 2.09 version of \pfg, it will be necessary to use
      |graphicx.sty|, or the |epsf.sty| or |epsfig.sty| wrappers
      for |graphicx.sty|. See section~\ref{sec:scaling} for a full explanation.
\item A DVI-to-PostScript driver. In this version, only |dvips| is
      supported; others will be added in the future.
\end{itemize}
If you wish to generate new \pfg\ figures, you will also need the
following utilities:
\begin{itemize}
\item Your favorite drawing or graphing program, which must be able to
      output your figures in Encapsulated PostScript format.
\item Perl 4.036 (or older) to run the |ps2frag| processing script
      supplied with \pfg. The Perl version was originally created by
      Piet Tutelars (\netaddress{rcpt@urc.tue.nl}), and greatly
      improved the portability of \pfg, since Perl is available for
      many platforms.\footnote{The C-version of \texttt{ps2frag} is not
      supported for \LaTeXe, because of the changes to the way the
      script must operate.} For MS-DOS users, a batch file
      |ps2frag.bat| is provided which will run the script for you.
\item Ghostscript, a PostScript interpreter which |ps2frag|
      uses to locate and document the positions of the
      text in an EPS file. It is free for personal use
      and available for most platforms.
\end{itemize}
The latest versions of \LaTeXe, the \package{graphics} package, \pfg,
and |dvips| can all be found on CTAN, the Comprehensive \TeX\ Archive
Network, composed of three FTP sites:
\begin{center}
  \begin{tabular}{lll}
    Name & IP address & Location \\ \hline
    |ftp.dante.de| & 129.206.100.192 & Germany \\
    |ftp.shsu.edu| & 192.92.115.10 & Texas, USA \\
    |ftp.tex.ac.uk| & 128.232.1.87 & England 
  \end{tabular}
\end{center}
Both Perl and GhostScript can be found at many of the major FTP sites,
probably including \texttt{gatekeeper.dec.com}, \texttt{ftp.uu.net},
\texttt{src.doc.ic.ac.uk}, and others.

\section{Installing \pfg}

Installing the various \pfg\ files is a bit more complicated than
installing most macro packages.
\begin{enumerate}
\item Run \LaTeX\ on |psfrag.ins| to extract |psfrag.sty|, |epsf.sty|,
      and |ps2frag.ps|. It will ask you a single question concerning 
      the way your system handles long file names.
\item Install |psfrag.sty| and |epsf.sty| in a standard location
      for \LaTeXe\ macros. |epsf.sty| will serve as a drop-in
      replacement for both |epsf.sty| and |epsfrag.sty| for \LaTeXe.
      (Actually, it does nothing more than load |epsfig.sty| from
      the \package{graphics} package.)
\item Install |ps2frag.ps| somewhere in your \TeX\ tree, preferably
      with your DVI-to-PostScript driver files (\eg,
      |/usr/local/lib/texmf/dvips|).
\item Edit the |ps2frag| script. You will need to change (or confirm
      the correctness of) the following things:
      \begin{itemize}
      \item the type of platform you have. Currently, the only
            two supported types are 'MSDOS' and 'UNIX'.
      \item the method the |&fragfile| command uses to determine
            the name of a \LaTeX\ 2.09 \pfg\ file. For example,
            the usual method in Unix is to simply add |frag| to
            the end of the name; in MS-DOS, the file extension
            is replaced with |.fra|.
      \item the value of the |$PS2FRAG| variable, which is the
            location of the file |ps2frag.ps|.
      \end{itemize}
      Reasonable defaults and customization instructions are provided
      in the script itself. You shouldn't need to be a Perl whiz
      to make these customizations.
\item If you are running UNIX, install |ps2frag| somewhere in your path,
      such as |/usr/local/bin|. If you are using MS-DOS, edit the 
      |ps2frag.bat| script to reflect the desired location of |ps2frag|
      and Ghostscript, and install |ps2frag.bat| somewhere in your path.
\item (optional) Install the |man| page for the |ps2frag| script, called
      |ps2frag.1|, into your local |man| tree (\eg, |/usr/local/man|).
\end{enumerate}
The |ps2frag| script supports the generation of old-style \LaTeX\ 2.09
\pfg\ information files through the |-209| command-line flag. So, it
is reasonable to completely replace the old versions of this script
and accompanying |ps2frag.ps| file, even if you need to support both
\LaTeXe\ and \LaTeX\ 2.09 documents.

\section{Usage}
Here is a quick summary of the usage of \pfg:
\begin{itemize}
\item |psfrag.sty| loads |graphics.sty| by default. If you prefer to
use another package, such as |graphicx.sty|, |epsfig.sty|, or
|epsf.sty|, load it with |\usepackage| in the preamble. Only packages
which use |graphics.sty| will work with \pfg, however.

\item Load |psfrag.sty| with a |\usepackage| command.

\item For each PostScript file you wish to include, run the |ps2frag| script:
\begin{quote}
   |ps2frag example.eps|
\end{quote}
This uses Ghostscript to generate the information necessary for 
\pfg\ processing, and embeds this information in the preamble of the
EPS file. This will not alter the appearance of the document in any
way, because this information appears as a comment to any PostScript
interpreter. Specifically, it is represented as an extended Document
Structuring Convention comment in the header of the EPS file, where
the |%%BoundingBox| comment is also located.

Every time an .eps is updated, |ps2frag| must be re-run.  Makefiles
can simplify this process! The |ps2frag| script will not re-process
any file that already contains \pfg\ comments (unless the |-f| flag is
supplied), so running |ps2frag *.eps| will process only those files in
the current directory which have not yet been processed.

\item Use one of following two methods for replacing PostScript text
with \LaTeX\ fragments. Both methods may be used in the same document.
Further description of the commands is given in Section~\ref{sec:pos}.
\begin{description}
\item[Method 1:] In the EPS figure, insert actual PostScript text that
looks like
\begin{quote}
    \cs{tex}\oarg{posn}\oarg{psposn}\oarg{scale}\oarg{rot}\marg{\LaTeX\ text}
\end{quote}
\pfg\ will replace this entire text with a typeset version of
\marg{\LaTeX\ text}. For example, you might place the text
\begin{quote}
    |\tex[bl][bl]{$\alpha$}|
\end{quote}
at a particular point in your PostScript file to have \LaTeX\ replace it
with $\alpha$. Explanation of the optional arguments
is deferred to Section~\ref{sec:pos}.
\item[Method 2:] In the EPS figure, place a simple ``tag'' word in
the same position in which you would like the \LaTeX\ replacement. In
your \LaTeX\ document, specify how this tag is to replaced, as follows:
\begin{quote}
    \cs{psfrag}\marg{tag}\oarg{posn}\oarg{psposn}\oarg{scale}\oarg{rot}\marg{\LaTeX\ text}
\end{quote}
The tag will be replaced by the \LaTeX\ text. Note that certain
complicated values for ``PS text'' might confuse \TeX\, so it's best
to use simple alphanumeric names. 

Example: in a drawing program like |xfig|, you place the text
\begin{quote}
    |xy|
\end{quote}
at a particular point. To replace this with $x+y$, one possible
macro would be
\begin{quote}
    |\psfrag{xy}{$x+y$}|
\end{quote}

All |\psfrag| calls that precede the \cs{includegraphics} (or
equivalent) in the same or surrounding environments will be utilized
for a given PostScript file. So, you can define global \cs{psfrag}s as
well as those that are local to a figure.
\end{description}
Method 2 has the distinct advantage that you can use EPS files which
were designed without consideration for \pfg. In addition, long
\cs{tex} macros embedded in an EPS file may distort the bounding box
of the figure. 
Using Method 1, on the other hand, allows text to be modified in the
EPS file without forcing changes in the \LaTeX\ source as well.

\item Any text that is not specified by a \cs{psfrag} or by 
\cs{tex} will not be replaced; hence, PostScript and \LaTeX\ 
text can be freely mixed.
\end{itemize}
Please see Section~\ref{sec:example} for illustrations of both
methods.

\section{Commands and Environments}\label{sec:pos}
\begin{decl}
\cs{tex}\oarg{posn}\oarg{psposn}\oarg{scale}%
        \oarg{rot}\marg{\LaTeX\ text}\\
\cs{psfrag}\marg{name}\oarg{posn}\oarg{psposn}%
        \oarg{scale}\oarg{rot}\marg{\LaTeX\ text}
\end{decl}
These macros declare the \LaTeX\ text to be placed at the same
position as the PostScript marker.  The first form is embedded
directly in a PostScript text command (|show|, |ashow|, |widthshow|,
|awidthshow|, |kshow|), and serves as its own marker. The second form
is placed in a surrounding \LaTeX\ environment before the
|\includegraphics| (or equivalent) call, and uses the text in
\marg{name} as the PostScript marker. (It matches \emph{all}
occurrences of \marg{name}, so multiple substitutions can take place.)

The optional positioning arguments \oarg{posn} and \oarg{psposn}
specify how the bounding box of the \LaTeX\ text and the bounding box 
of the PostScript text line up, respectively. Some drawing packages 
would refer to these as ``control points'' or ``alignment points.''
\begin{description}
\item{\oarg{posn}} the \LaTeX\ text reference point. The syntax of this
        argument is identical to that of the |\makebox| command. Up to two
        letters may be chosen, one from the list \{|t|,|b|,|B|\}, (top,
      bottom, baseline) and another from \{|l|,|r|\} (left, right).
      If a letter from either list is omitted, the behavior is to 
      place the point in the center of the appropriate direction; 
      Together, these specify one of 12 anchor points. If the argument
      is omitted altogether, then |[Bl]|, or left baseline positioning,
      is assumed; but note that supplying |[]| specifies centered 
        positioning.

      \emph{Note:} In the \LaTeX\ 2.09 version, the default was |[bl]|,
      and baseline alignment was not supported. For most text, however, this
      should not appreciably affect the output.
\item{\oarg{psposn}} The PostScript text reference point. The possible
        arguments are identical to that of \oarg{posn}, as is the default
        value, |[Bl]|.
\end{description}
The \LaTeX\ replacement text may be optionally scaled and rotated about
its reference point:
\begin{description}
\item{\oarg{scale}} Scaling factor (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]|.
\item{\oarg{rotn}} Extra rotation of the text around its reference point,
        in degrees. The nominal rotation of the \LaTeX\ text matches that
        of the PostScript text it replaces. The total rotation is this
        nominal value plus \oarg{rotn}. The default is |[0]|.
\end{description}
\begin{figure}[tbh]
\begin{center}
    \includegraphics[width=4in]{testfig.eps}
\end{center}
\caption{An illustration of various alignment, scaling, and rotation
         combinations for the \cs{psfrag} and \cs{tex} commands.}
\label{fig:argexam}
\end{figure}
Figure~\ref{fig:argexam} provides an illustration of the effects of
the use of various arguments above (and it happens to be a good exerciser
for the package, too). The graphical square denotes the bounding box,
center lines, and baseline of an exaxmple piece of replaced text. \pfg\
was used to place several LaTeX replacements. In each case, the replacing
\LaTeX\ code is actually the set of arguments to produce that particular
alignment, rotation, and scaling, encased in an \cs{fbox}.
\begin{decl}
\cs{begin}|{psfrags}|\\
\cs{end}|{psfrags}|
\end{decl}
The |psfrags| environment may be used, if necessary, to delimit the
scope of the \cs{psfrag} calls. As we said before, \cs{psfrag}
commands retain their effect until the most immediate surrounding
environment is exited.  \emph{Any} environment will do: |center|,
|figure|, \etc. Therefore, it may never be necessary to use this
environment, and the environment has no other effect on the document.

\section{Package Options}

There are only three package options for \pfg.
\begin{description}
\item[|209mode|] (\LaTeXe\ native mode only) forces \pfg\
to operate exactly as if \LaTeX\ 2.09 compatibility mode was
enabled. As a result, |bl| alignment is the default |Bl|, and \pfg\
expects to find the text positioning information in a separate -|frag|
file, instead of in the header of the EPS file itself.

This option simplifies the conversion of old documents to \LaTeXe,
allows for easy support of \LaTeXe\ documents that were created before
this package was released, or which share figures with \LaTeX\ 2.09
documents. However, it's also just as easy to re-run the |ps2frag|
processing script on all of the figures. Plus, the \pfg\ comments in
the header of the EPS file can easily coexist with those in the
-|frag| file, allowing both \LaTeXe\ and \LaTeX\ 2.09 documents to
access and support \pfg\ figures in their native mode.

\item[|2emode|] (\LaTeX\ 2.09 compatibility mode only) 
forces \pfg\ to remain in \LaTeXe\ mode, even in the presence of a
\LaTeX\ 2.09 document; this is the direct opposite of |209mode|.  When
enabled, the default alignment is |Bl|, and \pfg\ looks for text
positioning information in the header of the EPS file.

This option should allow people to use the new features of \pfg\ when
other factors prevent them from using native \LaTeXe\ mode, such as
the need to use old \LaTeX\ 2.09 style files. However, if you are
using \LaTeX\ 2.09 compatibility mode because you need to share your
document with someone who cannot run \LaTeXe, you must avoid using
this option!

\item[|showall|] disables the hiding of the \pfg\ tags in the
EPS files. This might be useful if you wanted to investigate a
potential bug in your \cs{psfrag} commands or in |psfrag.sty| itself
(perish the thought!). When the resulting document is viewed, both the
PostScript tags and \pfg\ replacements will appear.
\end{description}

\section{Examples}\label{sec:example}

A typical figure declaration might look like this:
\begin{verbatim}
    \begin{figure}[tbh]
    \begin{center}
        \psfrag{u}[b][tr]{$u = 1 + \gamma$}
        \psfrag{y}[]{$\hat{y}$}
        \psfrag{z}[][]{output $z$}
        \includegraphics[width=4in]{example.eps}
    \end{center}
    \caption{This is an example.}
    \end{figure}
\end{verbatim}
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, center of the $\hat{y}$ is aligned with the left of the
baseline of the PostScript text "y" (the default for psposn), and the
center of $z$ is aligned with the center of the PostScript text "z".
The PostScript file is centered with an x width of 4 inches.

Embedded replacements can be performed in MATLAB (for example) with:
\begin{verbatim}
    t = 0:.1:10;
    plot(t,sin(t),t,cos(t));
    axis('square'); grid;
    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');
    tt=text(t(50),cos(t(50)),'p3');
    set(tt,'HorizontalAlignment','center','VerticalAlignment',...
        'bottom','Rotation',atan2(-sin(t(50))*10,2)*180/pi);
    print -deps example
\end{verbatim}
In MATLAB, the 'text' command defaults to a left-center alignment,
corresponding to a \oarg{psposn} argument of |[l]|. The embedded
\cs{tex} commands specify alignment points appropriate for each
label. The \LaTeX\ file might say:
\begin{verbatim}
    \documentclass[12pt]{article}
    \usepackage[showall]{psfrag}
    \begin{document}
        This is a test.
        \unitlength=1in
        \begin{center}
            \psfrag{p1}[l]{\begin{picture}(0,0)
                \put(0.15, 0.2){\makebox(0,0)[l]{$\sin(t)$}}
                \put(0.1,0.2){\vector(-1,-2){0.1}}
                \end{picture}}
            \psfrag{p2}[c][l]{$\ast$}
            \psfrag{p3}[B][B]{$\cos(t)$}
              \includegraphics[width=3.5in]{example.eps}
         \end{center}
    \end{document}
\end{verbatim}
\begin{figure}[tbh]
    \unitlength=1in
    \begin{center}
        \psfrag{p1}[l]{\begin{picture}(0,0)
            \put(0.15,0.2){\makebox(0,0)[l]{$\sin(t)$}}
            \put(0.1,0.2){\vector(-1,-2){0.1}}
            \end{picture}}
        \psfrag{p2}[c][l]{$\ast$}
        \psfrag{p3}[Bl][Bl]{$\cos(t)$}
        \includegraphics[width=3.5in]{example.eps}
   \end{center}
   \caption{A \pfg\ example.}\label{fig:example1}
\end{figure}
This replaces ``p1'' with a small picture, ``p2'' with an asterisk,
and ``p3'' with some text. The output of this example looks something
like Figure~\ref{fig:example1}.

\section{Using the \texttt{ps2frag} script}\label{sec:script}
\begin{decl}
|ps2frag [-f] [-209] [-2e] [-x |\emph{pts}|] [-y |\emph{pts}|]| \emph{files...}
\end{decl}
The |ps2frag| script is relatively simple to use. Its default behavior
will be almost always sufficient.  |ps2frag| does have several
command-line options, however, which enable you to modify the behavior
of the script.

\begin{description}
\item[|-f|] forces |ps2frag| to update the information in all of the
            named EPS files, even if they have already been processed.
            If you have hand-modified an EPS file, you will need
            to use this option to force |ps2frag| to process it again.
\item[|-209|] invokes \LaTeX\ 2.09 mode. In this mode,
              the text information extracted from the EPS file is
              placed in a separate \pfg\ file with the same base name,
              as was done in the \LaTeX\ 2.09 version of \pfg. This option
              is supplied to allow old documents to be maintained with
              the same script.
\item[|-2e|] disables \LaTeX\ 2.09 mode. If |ps2frag| has been configured
             to run in \LaTeX\ 2.09 mode by default, this option will 
             provide \LaTeXe\ behavior. You can determine the default
             behavior by running |ps2frag| with no arguments; if 
             \LaTeX 2.09 mode is the default, it will respond with
\begin{verbatim}
    This is ps2frag, version 2.0
    LaTeX 2.09 compatibility mode enabled.
    usage: /local/bin/ps2frag -209 [-f] [-209] [-2e] [-x <pts>] [-y <pts>] files...
\end{verbatim}
\item[|-x|,|-y|] specify displacements, in points, in the X and Y
                 directions that you wish to add to each text
                 fragment.  Some drawing programs add small offsets
                 that cause the actual positions of the text to differ
                 from that which was specified by the user. For
                 example, when |idraw| is used with ``grid gravity''
                 turned on, it shifts 12-point text upwards by 8.33
                 points; so, for such files, you might want to specify
                 -y -8.33.
\end{description}
You may supply as many file names to a single |ps2frag| command as you
wish. By default, it will processs only those files which do not
already have \pfg\ information in their headers, quickly skipping over
the rest. This allows you to update an entire directory of figures
very quickly by simply running |ps2frag *.eps|.

If you are running |ps2frag| on a system which can handle long file
names, consider linking or copying the script to the name |ps2psfrag|
as well.  By default, if |ps2frag| is run under the name |ps2psfrag|,
it activates \LaTeX\ 2.09 compatibility mode. For many sites, this
will allow for smooth support of both modes.

\section{Deviations from \LaTeX\ 2.09}

Because so many things are changing with \LaTeX\ these days, what with
the release of \LaTeX2e\ and its enhanced \package{graphics} package,
I felt that a major rehaul of \pfg\ was justified. Almost all of the
internals have been completely rewritten, and much of the external
interface has changed.

\subsection{Comment-based fragment information}

One significant difference is that |ps2frag| now deposits the fragment
information into the document structuring comments of the EPS file
itself, instead of placing them in a separate file.  They have been
structured to appear as comments to PostScript (and to any
standards-conforming viewer/processor), but are in fact embedded \pfg\
commands. I hope people find this convenient, after an inevitable
initial ``shock.''

Of course, if one must use the old method for some documents, the
|209mode| package option is provided. I do believe that it should be
used only as an exception to the rule, however.

\subsection{Using the new \package{graphics} package}

Because of the \LaTeXe\ upgrade, the the graphics calls used to load
the figures have completely changed. In \LaTeX\ 2.09, a modified
version of |dvips|'s \package{epsf} macros were used; this limited its
usefulness to |dvips| users, and proved a maintenance hassle, since
new versions of |dvips| with clean copies of |epsf.sty| were released
much more frequently than updates to \pfg.

This version of \pfg\, however, attempts to be well-integrated with
the standard \package{graphics} package. Currently, it does require
the ability to pass direct PostScript; since |graphics.sty| does not
provide a standard way to perform this, |dvips| is the only
DVI-to-PostScript driver that \pfg\ currently supports.

In the future, when |graphics.sty| provides a "raw PostScript" macro,
\pfg\ should work on a much wider variety of dvi-to-PostScript
drivers.

\subsection{Figure scaling and resizing}
\label{sec:scaling}

There is one important caveat that must be heeded when using the 
|graphics.sty| package, especially if you have used \pfg\ before.

In the past, when using the \package{epsf} macros \cs{epfxsize},
\cs{epsfysize}, \emph{etc.} to resize the EPS figure, the \pfg\ text
did not scale with it. If you use the \cs{scalebox} or \cs{resizebox}
macros of |graphics.sty|, then the \pfg\ replacments \emph{will} scale
with the figure.

\begin{figure}[tbh]
    \unitlength=1in
    \begin{center}
        \psfrag{p1}[l]{\begin{picture}(0,0)
            \put(0.15, 0.2){\makebox(0,0)[l]{$\sin(t)$}}
            \put(0.1,0.2){\vector(-1,-2){0.1}}
            \end{picture}}
        \psfrag{p2}[c][l]{$\ast$}
        \psfrag{p3}[B][B]{$\cos(t)$}
        \resizebox{3.5in}{!}{\includegraphics{example.eps}}
   \end{center}
   \caption{The same \pfg\ example as Figure~\ref{fig:example1}, using
            \cs{resizebox} to set the width.}
   \label{fig:example2}
\end{figure}
If this distinction isn't clear, consider Figure~\ref{fig:example2},
which imports the same EPS file as Figure~\ref{fig:example1}, but uses
the command
\begin{verbatim}
    \resizebox{3.5in}{!}{\includegraphics{example.eps}}
\end{verbatim}
to resize the figure. For comparison, Figure~\ref{fig:example1} uses
\begin{verbatim}
    \includegraphics[width=3.5in]{\includegraphics{example.eps}}
\end{verbatim}
As you can see, the text in the second figure is decidedly smaller
than the first. The |\resizebox| command uses PostScript tricks to
scale \emph{all} of the contents of its argument. Since the |\psfrag|
commands are not actually typeset until \emph{within} the
|\includegraphics| command, they are resized as well.

The |graphicx.sty| key-value pairs |width=|, |height=|, and |scale=|
will all scale the figure without scaling the replacement text, as
long as they are supplied \emph{before} an |angle=| rotation key.
figure. Of course, the \cs{resizebox} and \cs{scalebox} macros are
still available in |graphicx.sty|, so you can mix and match both
behaviors as you see fit. See the \package{graphics} documentation for
more details.

I suspect that everyone who prefers the behavior of the old \pfg\ will
be quite happy simply using the key-value options in
|graphicx.sty|. Some may suggest, however, that the text scaling
produced by \cs{scalebox} and \cs{resizebox} is \emph{precisely} the
way \pfg\ should have always behaved. Now, \emph{both} behaviors are
supported.

\subsection{The \texttt{ps2frag} script}

In previous versions of \pfg, the processing script was called
|ps2psfrag| and was written in the UNIX C-Shell. In order to support
non-Unix platforms, the script was re-written in Perl, and its name
shortened to |ps2frag|.

The |ps2frag| script supports both \LaTeX\ 2.09- and \LaTeX2e-style
processing, so you can safely use it for both old and new documents.
If you are running |ps2frag| on Unix, you may wish to symbolically
link it to |ps2psfrag| as well. The script will recognize that it is
being called by the old name, and automatically invoke \LaTeX 2.09
compatibility features. Otherwise, the |-209| option will enable these
features. See Section~\ref{sec:script} for details.

\section{Bugs}

The PostScript text must be displayed using a single call to
|show|, |ashow|, |kshow|, |widthshow|, or |awidthshow|. More esoteric
methods employed by some PostScript-generating programs will
not work with psfrag.

This is not a problem with MATLAB, Xmath, xfig, and idraw, which
all use |show|. Aldus Freehand uses |awidthshow|, so it is also fine.

\LaTeX\ fragments always appear on top of the EPS file. 

Some of the improvements in bounding-box handling may affect the way
\LaTeX\ 2.09 documents are processed. In addition, a rare bugs in the
old |ps2frag.ps| file have been corrected, which will change the way
some EPS files are proceesed.

\section{The \pfg\ mailing list}
There is a Majorodomo mailing list for purposes of \pfg\ maintenance. 
It is NOT intended for instructional questions,
but only for bug reports and development ideas. Anyone who
wishes to assist in PSfrag's evolution may subscribe; to do
so, just send mail to
\begin{quote}
 \netaddress{psfrag-request@rascals.stanford.edu}
\end{quote}
with the single word |subscribe| in the \emph{body} of the text.

Bug supports, ideas, etc. should go to 
\netaddress{psfrag@rascals.stanford.edu}. 
If you have a bug to report, please try to provide us with an 
example that we can run \LaTeX\ on it ourselves! Drop us a line first.

\end{document}