%% 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{shortvrb,psfrag,graphicx}

% 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\pkg\textsf
\let\fname\texttt
\let\pscom\texttt
\newcommand{\pfg}{\pkg{PSfrag}}
\newcommand{\ie}{\emph{i.e.\@}}
\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, version 3}
\author{Michael C. Grant and David Carlisle\\
        \netaddress{psfrag@rascals.stanford.edu}}
\date{26 November 1996}

\begin{document}

\maketitle
\tableofcontents

\section{What is \pfg?}

Many drawing and graphing packages produce output in the Encapsulated
PostScript (EPS) format, but few can easily produce the equations and
other scientific text of which \LaTeX\ is capable. On the other hand,
many \LaTeX\-based drawing packages are not as expressive or
easy-to-use as the many advanced drawing packages that produce
EPS output.

\pfg\ provides the best of both worlds by allowing the user to
precisely overlay Encapsulated PostScript (EPS) files with arbitrary
\LaTeX\ constructions. In order to accomplish this, the user places
a simple text ``tag'' in the graphics file, as a ``position marker''
of sorts. Then, using simple \LaTeX\ commands, the user
instructs \pfg\ to remove that tag from the figure, and replace it
with a properly sized, aligned, and rotated \LaTeX\ equation.

This version of \pfg\ is significantly easier to use than
previous versions, because it eliminates the
preprocessing step required in those versions.
As a result, the new \pfg\ should also prove to be significantly more
portable, reliable, and flexible.

Veteran \pfg\ users need to know that the \cs{tex} command, while
still supported, has been deprecated. For details, consult section
\ref{sec:texcomm}. In addition, because the engine is so new, its
compatibility with many DVI-to-PostScript drivers has yet to be
determined; consult section \ref{sec:compat} for details.

Dr.\ Craig Barratt wrote the original
version of \pfg\ as a student at Stanford University.%
\footnote{Craig no longer participates in the development of \pfg;
however, heaps of praise may still be sent to him at
\netaddress{psfrag@rascals.stanford.edu}!}
The interface has deviated very little since then,
but the internals have been completely re-written.
The current version of PSfrag is maintained by Michael C. Grant
and David Carlisle. Many thanks go to Ted Stern, who also
provides diligent assistance.

\section{\pfg\ necessities}

In order to use \pfg, you will need the following tools:
\begin{itemize}
\item A recent version of \LaTeXe\ and the \pkg{graphics} package.
\pfg\ currently requires the 1995/12/01 version or later of these
packages, but it is always best to have the most recent release.
\pfg\ will now work with the old \pkg{epsf} macros, but the
\pkg{graphics} package is still used internally.
\item A compatible DVI-to-PostScript driver (see below). \pkg{dvips} is
the primary choice of the \pfg\ developers, and is certainly the
most widely-used.
\end{itemize}

The latest versions of \LaTeXe, the \pkg{graphics} package, \pfg,
and \pkg{dvips} can all be found on CTAN, the
Comprehensive \TeX\ Archive Network. The CTAN cites, and their mirrors,
include:
\begin{center}
  \begin{tabular}{lll}
    Name & IP address & Location \\ \hline
    |ftp.dante.de| & 129.206.100.192 & Germany \\
    |ftp.tex.ac.uk| & 128.232.1.87 & England \\
    |ftp.cdrom.com| & 165.113.58.253 & USA \\
  \end{tabular}
\end{center}

\subsection{Choosing a PostScript driver}
\label{sec:compat}

\pfg\ relies on some sensitive PostScript tricks to accomplish
its goals. Due to limited and time and resources, the authors
could not confirm that \pfg\ works properly on every available
PostScript driver. We have attempted to insure
that it will \emph{eventually} work on every driver that is fully
comaptible with the \pkg{graphics}
package (\ie, one for which a \fname{.def} file is provided.)

The drivers which have been confirmed to work with \pfg\ are:
\begin{center}
\begin{tabular}{lll}
Driver & Tested by & Compatibility \\ \hline
Thomas Rokicki's \pkg{dvips} & the authors &
fully compatible \\
Y\&Y's \pkg{DVIPSONE} & the authors &
\emph{Level 2 printers only}.
\end{tabular}
\end{center}
As the table shows, some drivers, like \pkg{DVIPSONE}, will
work properly with \pfg\ but will produce output that prints
properly only on newer, \emph{Level 2} PostScript printers.
If you try to print such a document on a Level 1 printer using
one of these drivers, the replacements will not show up. Hopefully,
the incidence of Level 1 printers is diminishing, especially with
the emergence of Level 3 PostScript on the horizon.

Please help us add entries to this compatibility list! If \pfg\ works
with your driver, please let us know, so we can add it to the list.
If \pfg\ does \emph{not} work, please submit a bug report. Consult
section \ref{sec:mail} for contact information.
If possible, test your \pfg\ output on both Level 1
and Level 2 printers, so we can make a distinction here if necessary.

\section{Installing \pfg}

Installing the various \pfg\ files is quite simple:
\begin{enumerate}
\item Run \LaTeX\ on \fname{psfrag.ins} to extract
      \fname{psfrag.sty} and \fname{psfrag.pro}.
\item Install \fname{psfrag.sty} in a standard location for
      \LaTeXe\ macros. For \pkg{kpathsea}-based systems such as
      \pkg{teTeX}, this path is determined by the
      \texttt{TEXINPUTS} variable.
\item Install \fname{psfrag.pro} wherever your PostScript driver
      looks for header files. For \pkg{kpathsea}-based systems,
      this is determined by the \texttt{DVIPSHEADERS} varaible.
      For \pkg{dvips} in particular, the most logical choice would
      be the same directory in which \fname{tex.pro} and
      \fname{special.pro} are located.
\item If you have an older version of \pfg, you may delete the
   following files, if they exist: \fname{ps2frag.ps}, \fname{ps2frag}
   or \fname{ps2psfrag} (the processing scripts),
   and \fname{epsf.sty} (the one provided by \pfg,
   \emph{not} the \pkg{dvips} version!). System managers may wish to
   replace \fname{ps2frag} with a script which notifies users of the
   upgrade.
\end{enumerate}

\section{Usage}
Here is a quick summary of the usage of \pfg:
\begin{itemize}

\item Make sure that your EPS figure contains simple ``tag'' words
in the same positions in which you would like the \LaTeX\ replacements.
Some effort has been made to allow for more arbitrary tag text;
but it is still more reliable to use simple, short, alphanumeric tags.

\item If you wish to use \fname{epsf.sty} to include EPS files,
it must be loaded with the \cs{usepackage} command \emph{before}
\fname{psfrag.sty}. Other packages that are based upon
\fname{graphics.sty}, such as \fname{graphicx.sty} or \fname{epsfig.sty},
can be loaded before or after \fname{psfrag.sty}.

\item Load \fname{psfrag.sty} with a \cs{usepackage} command.

\item For each tag word in your EPS file, add a command to your
your \LaTeX\ document to 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. Certain complicated
values for the tag word might confuse \TeX\, so it's best to use
simple alphanumeric names.

Example: in a drawing program like \pkg{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}
    \cs{psfrag{xy}{$x+y$}}
\end{quote}

All \cs{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.

\item Any text that is not mentioned in a \cs{psfrag} command
will not be replaced; hence, PostScript and \LaTeX\
text can be freely mixed.
\end{itemize}

When viewing the output with a DVI previewer such as \pkg{dviwin} or
\pkg{xdvi}, a vertical list of the replacements will be placed on the
left side of each figure. This list allows you to check the
typesetting of your replacements; it disappears in the final
PostScript version. Unfortunately, DVI drivers are incapable of
\emph{placing} the \pfg\ replacements on top of the figure, so
for that you will need to print it out or use a PostScript
previewer like GhostView.

This version of \pfg\ \emph{should} run properly in the compatibility
mode of \LaTeX2.09. Let us know if you find otherwise (see section
\ref{sec:mail}).

\section{Commands and Environments}\label{sec:pos}

\begin{decl}
\cs{psfrag}\marg{tag}\oarg{posn}\oarg{psposn}%
        \oarg{scale}\oarg{rot}\marg{replacement}\\
\cs{psfrag*}\marg{tag}\oarg{posn}\oarg{psposn}%
        \oarg{scale}\oarg{rot}\marg{replacement}
\end{decl}

The \cs{psfrag} macro defines which \LaTeX-typeset text
\marg{replacement} is to be place at the same position as the
PostScript \marg{tag}. The command should be placed
before the call to \cs{epsfbox}, \cs{includegraphics}, or equivalent.
It matches \emph{all} occurrences of \marg{tag} in the figure.

A \cs{psfrag} replacement will remain in effect until its surrounding
environment is exited. Therefore, you can define global \cs{psfrag}s
which will apply to every figure, or define \cs{psfrag}s inside a
single environment (\emph{e.g.}, a |figure| environment) which apply
to a single EPS file.

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

When running in \LaTeX\ 2.09 compatibility mode, the default alignment
is |[bl]|, in order to support legacy documents. For most text,
however, this should not make an appreciable difference.
\item{\oarg{psposn}}
the PostScript text reference point. The possible arguments are
identical to that of \oarg{posn}, as is the default value, |[Bl]|
(|[bl]| in \LaTeX\ 2.09 compatibility mode.)
\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]
\psfragdebugon
\begin{center}
     \psfrag{gA}[br][br]{|[br][br]|}
     \psfrag*{gA}[Br][b ][2]{|[Br][b][2]|}
     \psfrag*{gA}[ r][bl]{|[r][bl]|}
     \psfrag*{gA}[tr][Bl]{|[tr][Bl]|}
     \psfrag*{gA}[b ][B ]{|[b][B]|}
     \psfrag*{gA}[B ][Br]{|[B][Br]|}
     \psfrag*{gA}[  ][ r]{|[][r]|}
     \psfrag*{gA}[t ][  ][0.75][45]{|[t][][0.75][45]|}
     \psfrag*{gA}[bl][ l][1.5][30]{|[bl][l][1.5][30]|}
     \psfrag*{gA}[Bl][tl]{|[Bl][tl]|}
     \psfrag*{gA}[bl][Bl]{~~~~~(baseline)}
     \psfrag*{gA}[bl][l]{~~~~~(center line)}
     \psfrag*{gA}[bl][t][1][-90]{~~~~~(center line)}
     \psfrag*{gA}[ l][t ]{|[l][t]|}
     \psfrag*{gA}[tl][tr][1][180]{|[tl][tr][1][180]|}
     \resizebox{4in}{!}{\includegraphics[angle=30]{testfig.eps}}
\end{center}
\caption{An illustration of various options for the \cs{psfrag} command.}
\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). If you're viewing the DVI file
with a previewer such as \pkg{xdvi}, you should see the \pfg\
replacements lined up to the left of the figure; and, if your
previewer can display EPS files, a large, rotated |gA|. If you
have printed this out, or are viewing the PostScript file with
a viewer like GhostView, then the replacements should be properly
superimposed on a graphical representation of the
bounding box, center lines, and baseline of the tag |gA|.
(This graphical box is provided only in debug mode.)

If a replacement for \marg{tag} already exists, the unstarred
command \cs{psfrag} will replace it without warning. The starred
version \cs{psfrag*}, however, will \emph{add} the new replacement
to a list. Using the starred command, a single piece of PostScript
text could trigger several replacements. I can't think of a reason
why most users would use the starred version, but it was used in
Figure~\ref{fig:argexam} above.

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

\subsection{Embedding \pfg\ operations into EPS files}
\label{sec:texcomm}

\begin{decl}
\cs{tex}\oarg{posn}\oarg{psposn}\oarg{scale}%
        \oarg{rot}\marg{\LaTeX\ text}\\
\cs{psfragscanon}~~~\cs{psfragscanoff}
\end{decl}

\pfg\ 3.0 supports the embedded \cs{tex} commands found in previous
release of \pfg, but it has been deprecated somewhat because of its
reliance on a pre-processing step. Unlike previous versions of \pfg,
support for the \cs{tex} command must be \emph{explicitly requested},
as described below.

As you can see, the syntax of the \cs{tex} command is very similar
to the \cs{psfrag} command. However, instead of adding the \cs{tex}
command to your \LaTeX\ file, the \cs{tex} command is \emph{embedded
in the EPS file itself}. In other words, the command becomes its
own replacement tag.

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$. Many \pfg\ users find this feature useful for the axis
labels and titles of MATLAB graphs.

The advantage to this approach is that changes can be made to the
EPS file without having to modify any \cs{psfrag} commands in the
\LaTeX\ file. (It is still necessary to \emph{re-compile} the
\LaTeX\ file in such cases, however.)

There are cautions and disadvantages to this approach, including:
\begin{itemize}
\item Changing the labels created by \cs{tex} commands requires editing
the figure; if you use \cs{psfrag} instead, you need only to edit the
document, which might be less cumbersome. (You must
run \LaTeX\ again in both cases.)
\item Because \cs{tex} commands are long strings, they can extend
past the other graphics in your EPS file. As a result, they can modify
the EPS bounding box in an undesired way. This problem can be mitigated by
reducing the font size of the \cs{tex} string, since this does not affect
the size of its \pfg\ replacement.
\item The \cs{tex} command is not supported in compressed PostScript files.
\item The \TeX\ engine must scan the PostScript file for these strings,
which can add to the processing time of your document. (To be honest,
we have yet to encounter a case where this is a significant concern.)
\item \emph{Important!} Whenever a file is scanned by \pfg,
it generates a file with the name \cs{jobname}\fname{.pfg}, where \cs{jobname}
is the base name of the master \LaTeX\ file. It will overwrite, without
warning, any file with that name.
\end{itemize}

Since it was impossible to improve the \cs{tex} command in the same
way as the \cs{psfrag} command, this feature is no longer enabled
automatically except in \LaTeX\ 2.09 compatibility mode. So, for
\LaTeXe\ documents, you must activate it in one of two ways:
\begin{itemize}
\item To turn on scanning for a single figure, precede the \cs{epsfbox}
or \cs{includegraphics} command with a call to the command \cs{psfragon}.
Scanning will be turned off again when the surrounding environment is
exited; or, you can turn it off explicity with a call to \cs{psfragscanoff}.
\item To turn on scanning for the entire document, pass the option
|scanall| to \fname{psfrag.sty} in the \cs{usepackage} command.
\end{itemize}
The \cs{tex} scanner will continue to be supported in this form. So, if you
do find applications where you prefer the \cs{tex} command, do not hesitate
to use it! For best results, however, we recommend that you use \cs{psfrag}
exclusively instead.

\section{Package Options}

There are only four package options for \pfg. Any other options
that are not handled by \pfg\ will be forwarded to
\fname{graphics.sty}.
\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, and
\cs{tex} scanning is enabled for all EPS files. This option is
useful if you are trying to convert old \LaTeX\ 2.09 documents
to \LaTeXe.

The \LaTeX 2.09 version of \pfg\ generated an auxiliary
file for each EPS figure containing important replacement information.
These files are no longer used and can be deleted.

\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 \cs{tex} scanning is turned
off by default.

\item[|scanall|] turns on \cs{tex} scanning by default. Use this
option if most your figures use embedded \cs{tex} commands.

\item[|debug|] turns on some of the debugging features of PSfrag. It
inserts extra code into the PostScript file that draw the bounding boxes
of each piece of text that is replaced. It is probably not useful to anyone
but the developers of \pfg.
\end{description}

\section{An Example}\label{sec:example}

In the following example, we demonstrate how to use \pfg\ with
the MATLAB package. The following MATLAB commands generate a
plot of both a sine wave and a cosine wave, places both simple
tags and \cs{tex} replacements into the figure, and saves the
result as an EPS file \fname{example.eps}.
\begin{verbatim}
    t = 0:.1:10;
    plot(t,sin(t),t,cos(t));
    axis('square'); grid;
    title('\tex[B][B]{Plot of $\sin(t)$ and $\cos(t)$}');
    xlabel('\tex[t][t]{$t$}');
    ylabel('\tex[B][B]{$\sin(t)$, $\cos(t)$}');
    text(t(30),sin(t(30)),'p1');
    text(t(60),sin(t(60)),'p2');
    text(t(90),sin(t(90)),'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 code below includes \fname{example.eps} into the current document,
resizing it to a width of 3.5 inches. Several \cs{psfrag}
commands are used to replace the tags |p1|, |p2|, and |p3| in
the figure, and the command \cs{psfragscanon} command is used to
notify \pfg\ that it must scan \fname{example.eps} for the
\cs{tex} tags.
\begin{verbatim}
    \begin{figure}[tbh]
        \unitlength=1in
        \begin{center}
            \psfragscanon
            \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*{p1}[][l]{$\ast$}
            \psfrag{p2}[][l]{$\ast$}
            \psfrag{p3}{$\cos(t)$}
            \includegraphics[width=3.5in]{example.eps}
         \end{center}
         \caption{A \textsf{psfrag} example.}
    \end{figure}
\end{verbatim}
Note the use of a |picture| environment within the replacement
for |p1|.

\begin{figure}[tbh]
    \unitlength=1in
    \begin{center}
        \psfragscanon
        \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*{p1}[][l]{$\ast$}
        \psfrag{p2}[][l]{$\ast$}
        \psfrag{p3}{$\cos(t)$}
        \includegraphics[width=3.5in]{example.eps}
   \end{center}
   \caption{A \pfg\ example.}
   \label{fig:example1}
\end{figure}
The result of these two steps is shown in Figure~\ref{fig:example1}.

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

There are two ways to resize EPS figures with the \pkg{graphics}
package, and each has as different effect on \pfg\ replacements. If you
are used to using \fname{epsf.sty}, you will be accustomed to only one
such behavior.

If you use the \cs{scalebox} or \cs{resizebox} macros of \fname{graphics.sty},
then the \pfg\ replacments \emph{will} scale with the figure. This
effect is illustrated in \ref{fig:example2} below.
\begin{figure}[tbh]\unitlength=1in
    \begin{center}
        \psfragscanon
        \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*{p1}[][l]{$\ast$}
        \psfrag{p2}[][l]{$\ast$}
        \psfrag{p3}{$\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}
Figure~\ref{fig:example2} uses the following command to scale the figure
to 3.5 inches in width:
\begin{verbatim}
\resizebox{3.5in}{!}{\includegraphics{example.eps}}
\end{verbatim} This
is in direct contrast to Figure~\ref{fig:example1}, which uses the
|width=| keyword from the \fname{graphicx.sty}, as follows:
\begin{verbatim}
\includegraphics[width=3.5in]{\includegraphics{example.eps}}
\end{verbatim}
Figure~\ref{fig:example1} also reflects the behavior that
you would see when using the \fname{epsf.sty} macros \cs{epfxsize},
\cs{epsfysize}, \emph{etc}. In these cases, the \pfg\ text does not
scale with it. to resize the figure.

As you can see, the text in the second figure is decidedly smaller
than the first. This is because \cs{resizebox} uses PostScript tricks to
scale \emph{all} of the contents of its argument. Since the \cs{psfrag}
commands are not actually typeset until \emph{within} the
\cs{includegraphics} command, they are resized as well.

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

If you are still unsure about these distinctions, then try both
methods for scaling your figures until you find a convention that
works best for you.

\section{Known problems}

\pfg\ is bug-free.

Well, of course we're kidding. If you find any problems, please
confirm they are not mentioned below; and, if not, report them to
te \pfg\ mailing list (see below).

The PostScript text must be displayed using a single call to |show|,
|ashow|, |kshow|, |widthshow|, or |awidthshow|.
Some programs, however, place each character individually, with
individual calls to |show|. This technique is incompatible with \pfg,
and always will be. Experience has shown that this excludes only a very
small number of drawing packages.

The \LaTeX\ replacements are rendered after the figure has been drawn;
therefore, effects such as partial obscuring are not possible.

\section{The \pfg\ mailing list}
\label{sec:mail}

There is a Majorodomo mailing list for purposes of \pfg\ maintenance.
It \emph{is not} intended to replace this manual or a small amount of
educated guesswork. But, it \emph{is} the perfect place for bug reports,
development ideas, and so forth. Anyone who wishes to assist in
\pfg's evolution may subscribe; to do so, just send mail to
\begin{quote}
 \netaddress{majordomo@rascals.stanford.edu}
\end{quote}
with the line |subscribe psfrag| in the \emph{body} of the text.

Bug supports, ideas, \emph{etc.} should go to
\begin{quote}
    \netaddress{psfrag@rascals.stanford.edu}.
\end{quote}
If you have found a bug to report, please provide us with the
necessary files (a \LaTeX\ file, the EPS figures, \etc) so we can
test it out ourselves! Try to provide us with the shortest
self-contained example that demonstrates your bug. If this is not
possible, drop us a line first.

\end{document}