summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/psfrag/pfgguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/psfrag/pfgguide.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/psfrag/pfgguide.tex')
-rw-r--r--macros/latex/contrib/psfrag/pfgguide.tex695
1 files changed, 695 insertions, 0 deletions
diff --git a/macros/latex/contrib/psfrag/pfgguide.tex b/macros/latex/contrib/psfrag/pfgguide.tex
new file mode 100644
index 0000000000..7e7d68c6a1
--- /dev/null
+++ b/macros/latex/contrib/psfrag/pfgguide.tex
@@ -0,0 +1,695 @@
+%% 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}