diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/psfrag/pfgguide.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/psfrag/pfgguide.tex | 695 |
1 files changed, 695 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/psfrag/pfgguide.tex b/Master/texmf-dist/doc/latex/psfrag/pfgguide.tex new file mode 100644 index 00000000000..7e7d68c6a1e --- /dev/null +++ b/Master/texmf-dist/doc/latex/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} |