path: root/support/easylatex/psfrag/pfgguide.tex

%% 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{11 April 1998}

\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 \TeX\ is so capable. On the other hand, many
\LaTeX\-based drawing packages are not as expressive or easy-to-use as these
stand-alone tools.

\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. \pfg\ also allows the user to place \LaTeX\ constructs directly into
the EPS file itself.

Dr.\ Craig Barratt wrote the original version of \pfg\ as a graduate student at
Stanford University. The interface has changed very little since then, but the
internals have been completely re-written. The current version of PSfrag is
maintained by Michael Grant and David Carlisle. Many thanks go to the members
of the \pfg\ mailing list, and to everyone who has submitted a bug report or
suggestion.

\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.
\item If you wish to use the \pkg{seminar} package with \pfg, you
	  should make sure you have the 1997/10/13 version or later (see
	  section \ref{sec:sem-bug}).
\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 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 &
fully compatible
\end{tabular}
\end{center}
Please help us add entries to this list! If \pfg\ works with your driver,
please let us know, so we can add it to the list. If possible, test your \pfg\
output on both Level 1 and Level 2 printers, so we can make a distinction here
if necessary.If \pfg\ does \emph{not} work, please submit a bug report; consult
section \ref{sec:mail} for contact information. unfortunately, we cannot
promise a fix for everyone, but we would like to insure that the most popular
drivers remain compatible.

\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 like
      \pkg{te\TeX}, 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
	  like \pkg{te\TeX}, 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 Use the \cs{includegraphics} command defined by the \pkg{graphics}
      and \pkg{graphicx} packages to add EPS figures to your new documents.
	  If you must use the \cs{epsfbox} command from \fname{epsf.sty} for
	  old documents, then \fname{epsf.sty} must be loaded \emph{before}
	  \fname{psfrag.sty}. Other packages based on \fname{graphics.sty},
	  such as \pkg{graphicx} or \pkg{epsfig}, do not suffer this restriction.

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

\item Make sure that your EPS figures contain a simple ``tag'' word in
	  each position that you would like a \LaTeX\ replacements. Use
	  a \emph{single} word, composed of unaccented letters and numbers. 
	  Some effort has been made to allow for more arbitrary tag text, 
	  but the mechanism is not infallible; see section \ref{sec:tags}.

\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.
	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}
\end{itemize}

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.

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

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 a \LaTeX-typeset \marg{replacement} to be placed
at the same position as a PostScript \marg{tag}. The command should be placed
before the call to \cs{includegraphics}, or equivalent. It matches \emph{all}
occurrences of \marg{tag} in the figure.

A \cs{psfrag} command 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 a |figure| environment (for
example) 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|,|c|\}, (top, bottom, baseline, center) and another from
\{|l|,|r|,|c|\} (left, right, center). If either letter is omitted, then |c|
(center) is assumed. 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. Usually this should
not make a significant 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 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} illustrates various combinations of the arguments. If
you're viewing this with a DVI previewer such as \pkg{xdvi}, the \pfg\
replacements should be 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 it with a PostScript viewer like GhostView, then the
replacements should 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. Used properly, this is a powerful tool, 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, titles, and legends 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}

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{psfragscanon}.
	  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!

\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{Common mistakes, known problems, and bugs}

\pfg\ is bug-free.

Well, of course we're kidding. \pfg\ uses some tricky PostScript hacks to
achieve its goals. So it really would not surprise us if you find bugs, If you
find any problems, please confirm they are not mentioned below; and, if not,
report them to te \pfg\ mailing list (see below).

\subsection{Using \pfg\ tags properly}
\label{sec:tags}

One of the more frequent problems that people encounter with \pfg\ is that it
replaces \emph{some} of their tags properly, but not all of them. Whenever
possible, you should design your figures \emph{with \pfg\ in mind}, by
following this rule:
\begin{quote}
	When adding a piece of text (a \emph{tag}) in a figure for \pfg\ to
	replace, use a \emph{single word}, containing only unaccented letters
	and numbers.	
\end{quote}
This is the way that \pfg\ is intended to be used; doing so will almost
guarantee that \pfg\ works as advertised. Of course, one cannot always follow
this rule; and a small handful of drawing packages consistently cause problems.
Invariably, these problems can be resolved by understanding how \pfg\ looks for
these tags.

PostScript has five commands to display text---|show|, |ashow|, |kshow|,
|widthshow|, and |awidthshow|---although, in many cases, an EPS file will
define abbreviations of these commands. \pfg\ actually \emph{intercepts} these
commands and checks them for the tags to replace. When the string matches a
known tag, \pfg\ figures out where the tag \emph{would} have been displayed,
and inserts its replacement there. When it doesn't, \pfg\ lets the |*show|
command proceed normally.

The strings that these |*show| display are delimited with parentheses, much
like the \fname{C} language uses double quotes. For example:
\begin{quote}
	|(This is a test.) show| ~~~~~~~~~~~~displays~~~~~~~~~~~~|This is a test.|
\end{quote}
Unmatched parentheses and
certain other special characters must be preceded by a backslash in a
PostScript string. For example:
\begin{quote}
	|(x = \(0,1]) show| ~~~~~~~~~~~~displays~~~~~~~~~~~~|x = (0,1]|
\end{quote}

With this in mind, here is the rule about \pfg\ tags:
\begin{quote}
	The tag supplied to the \cs{psfrag} command must be typed \emph{exactly
	as it appears in the EPS file's |*show| command}, without the surrounding
	parentheses.
\end{quote}
In other words, \pfg\ will work only if the string in the \cs{psfrag} command
exactly duplicates what is found in the EPS file. If your strings have
backslashes added to them, as in the |x = \(0,1]| example, then you will have
to add that backslash to the \cs{psfrag} command as well. And \pfg\ can only
replace \emph{entire} strings, not just parts of one. So if your EPS file
contains
\begin{quote}
	|(I want to replace the XXX here) show|
\end{quote}
then the \cs{psfrag} command will fail if you supply just the |XXX|.

You can use a simple text editor to check things, if you like; EPS files are
(almost always) just simple ASCII files.

Unfortunately, some drawing packages display text by sending each character
\emph{individually} to a |show| command. In other words, if you use the
drawing tool to put the string ``test'' in your figure, it will do something like this:
\begin{quote}
	|(t) show (e) show (s) show (t) show |
\end{quote}
If this is true in your case, we apologize; it makes using \pfg\ much more
inconvenient---you will be limited to single-character tags. Such tools
also prevent the use of the \cs{tex} command.

\subsection{Problems using some \pkg{xfig} figures}

\pfg\ does not work with \pkg{xfig} figures that use ``pattern fills.'' When
painting/filling a polygon, \pkg{xfig} provides a number of choices: simple
colors or grey levels, or a number of patterns like cross-hatches, checkers,
\etc\ Unfortunately, using a pattern fill in a figure processed by \pfg\ results
in PostScript files that will not print.

Fortunately, there are workarounds:
\begin{enumerate}
	\item Avoid pattern fills in your \pkg{xfig} figures; use simple
		  colors (or greys) instead. Consult the \pkg{xfig} documentation
		  for details.
	\item Open the offending \fname{.eps} file (generated by \pkg{fig2dev}
		  or \pkg{xfig}'s ``export'' command) with your favorite text editor.
		  Look for the definition \pscom{PATfill} command; inside this 
		  subroutine, replace \pscom{show} with \pscom{oldshow} (there is only
		  one occurrence).
\end{enumerate}
For those PostScript hackers out there: both \pfg\ and \pkg{xfig} redefine the
PostScript \pscom{show} command. \pscom{oldshow} is where \pkg{xfig} stores the
``old'' version of the command. If you can determine why this fix works, and
convince the \pkg{xfig} maintainers to make the change; or, if you can suggest
a fix for \pfg, please do.

\subsection{Problems using old versions of the \pkg{seminar} package}
\label{sec:sem-bug}

The popular \pkg{seminar} package was, for awhile, incompatbile with PSfrag
3.0. This is due to the fact that PSfrag relies on certain features of the
\LaTeXe\ output routine, while \pkg{seminar} still uses one largely borrowed
from \LaTeX\ 2.09.

The best solution for this problem is to make sure that you have the latest
version of the \pkg{seminar} package, which can be retrieved from any CTAN
site, likely from the same place you found \pfg. A web page for \pkg{seminar}
can be found at \fname{http://www.tug.org/applications/Seminar/}. The
1997/10/13 version seems to have corrected the problem.

If for some reason you are forced to use an older version, there is a
temporary, \pkg{dvips}-specific fix: add the command
|\special{header=psfrag.pro}| just before |\begin{document}| in your \LaTeX\
file.

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