Debian Codegraph @

texmf-dist/doc/latex/psfrag/pfgguide.tex

raw
1 %% pfgguide.dtx Copyright (c) 1995 Michael C. Grant and Craig Barratt
2 %% All rights are reserved.
3 %%
4 %% This system is distributed in the hope that it will be
5 %% useful, but WITHOUT ANY WARRANTY; without even the
6 %% implied warranty of MERCHANTABILITY or FITNESS FOR A
7 %% PARTICULAR PURPOSE. Don't come complaining to us if you
8 %% modify this file and it doesn't work! If this file is
9 %% modified by anyone but the authors, those changes and
10 %% their authors must be explicitly stated HERE.
11 %%
12 \documentclass[11pt]{ltxguide}
13 \usepackage{shortvrb,psfrag,graphicx}
14
15 % I prefer more to a page.
16 \marginparsep 0pt \oddsidemargin 0pt \evensidemargin 0pt
17 \textwidth \paperwidth \advance \textwidth by-2in
18 \topmargin 0pt \headheight 0pt \headsep 0pt
19 \textheight \paperheight \advance \textheight by-2in
20
21 \let\pkg\textsf
22 \let\fname\texttt
23 \let\pscom\texttt
24 \newcommand{\pfg}{\pkg{PSfrag}}
25 \newcommand{\ie}{\emph{i.e.\@}}
26 \newcommand{\eg}{\emph{e.g.\@}}
27 \newcommand{\etc}{\emph{etc.\@}}
28 \newcommand{\netaddress}[1]{\texttt{#1}}
29 \MakeShortVerb{\|}
30 \def\cs#1{%
31 {\ttfamily\expandafter\string\csname #1\endcsname}}
32 \providecommand\marg[1]{%
33 {\ttfamily\char`\{}{\em#1\/}{\ttfamily\char`\}}}
34 \providecommand\oarg[1]{%
35 {\ttfamily[}{\em #1\/}{\ttfamily]}}
36 \providecommand\parg[1]{%
37 {\ttfamily(}{\em #1\/}{\ttfamily)}}
38
39 \title{The \pfg\ system, version 3}
40 \author{Michael C. Grant and David Carlisle\\
41 \netaddress{[email protected]}}
42 \date{11 April 1998}
43
44 \begin{document}
45
46 \maketitle
47 \tableofcontents
48
49 \section{What is \pfg?}
50
51 Many drawing and graphing packages produce output in the Encapsulated
52 PostScript (EPS) format, but few can easily produce the equations and other
53 scientific text of which \TeX\ is so capable. On the other hand, many
54 \LaTeX\-based drawing packages are not as expressive or easy-to-use as these
55 stand-alone tools.
56
57 \pfg\ provides the best of both worlds by allowing the user to precisely
58 overlay Encapsulated PostScript (EPS) files with arbitrary \LaTeX\
59 constructions. In order to accomplish this, the user places a simple text
60 ``tag'' in the graphics file, as a ``position marker'' of sorts. Then, using
61 simple \LaTeX\ commands, the user instructs \pfg\ to remove that tag from the
62 figure, and replace it with a properly sized, aligned, and rotated \LaTeX\
63 equation. \pfg\ also allows the user to place \LaTeX\ constructs directly into
64 the EPS file itself.
65
66 Dr.\ Craig Barratt wrote the original version of \pfg\ as a graduate student at
67 Stanford University. The interface has changed very little since then, but the
68 internals have been completely re-written. The current version of PSfrag is
69 maintained by Michael Grant and David Carlisle. Many thanks go to the members
70 of the \pfg\ mailing list, and to everyone who has submitted a bug report or
71 suggestion.
72
73 \section{\pfg\ necessities}
74
75 In order to use \pfg, you will need the following tools:
76 \begin{itemize}
77 \item A recent version of \LaTeXe\ and the \pkg{graphics} package.
78 \pfg\ currently requires the 1995/12/01 version or later of these
79 packages, but it is always best to have the most recent release.
80 \item If you wish to use the \pkg{seminar} package with \pfg, you
81 should make sure you have the 1997/10/13 version or later (see
82 section \ref{sec:sem-bug}).
83 \item A compatible DVI-to-PostScript driver (see below). \pkg{dvips} is
84 the primary choice of the \pfg\ developers, and is certainly the
85 most widely-used.
86 \end{itemize}
87
88 The latest versions of \LaTeXe, the \pkg{graphics} package, \pfg,
89 and \pkg{dvips} can all be found on CTAN, the
90 Comprehensive \TeX\ Archive Network. The CTAN cites, and their mirrors,
91 include:
92 \begin{center}
93 \begin{tabular}{lll}
94 Name & IP address & Location \\ \hline
95 |ftp.dante.de| & 129.206.100.192 & Germany \\
96 |ftp.tex.ac.uk| & 128.232.1.87 & England \\
97 |ftp.cdrom.com| & 165.113.58.253 & USA \\
98 \end{tabular}
99 \end{center}
100
101 \subsection{Choosing a PostScript driver}
102 \label{sec:compat}
103
104 \pfg\ relies on some sensitive PostScript tricks to accomplish its goals. Due
105 to limited time and resources, the authors could not confirm that \pfg\ works
106 properly on every available PostScript driver. We have attempted to insure that
107 it will \emph{eventually} work on every driver that is fully comaptible with
108 the \pkg{graphics} package (\ie, one for which a \fname{.def} file is
109 provided.)
110
111 The drivers which have been confirmed to work with \pfg\ are:
112 \begin{center}
113 \begin{tabular}{lll}
114 Driver & Tested by & Compatibility \\ \hline
115 Thomas Rokicki's \pkg{dvips} & the authors &
116 fully compatible \\
117 Y\&Y's \pkg{DVIPSONE} & the authors &
118 fully compatible
119 \end{tabular}
120 \end{center}
121 Please help us add entries to this list! If \pfg\ works with your driver,
122 please let us know, so we can add it to the list. If possible, test your \pfg\
123 output on both Level 1 and Level 2 printers, so we can make a distinction here
124 if necessary.If \pfg\ does \emph{not} work, please submit a bug report; consult
125 section \ref{sec:mail} for contact information. unfortunately, we cannot
126 promise a fix for everyone, but we would like to insure that the most popular
127 drivers remain compatible.
128
129 \section{Installing \pfg}
130
131 Installing the various \pfg\ files is quite simple:
132 \begin{enumerate}
133 \item Run \LaTeX\ on \fname{psfrag.ins} to extract
134 \fname{psfrag.sty} and \fname{psfrag.pro}.
135 \item Install \fname{psfrag.sty} in a standard location for
136 \LaTeXe\ macros. For \pkg{kpathsea}-based systems like
137 \pkg{te\TeX}, this path is determined by the
138 \texttt{TEXINPUTS} variable.
139 \item Install \fname{psfrag.pro} wherever your PostScript driver
140 looks for header files. For \pkg{kpathsea}-based systems
141 like \pkg{te\TeX}, this is determined by the \texttt{DVIPSHEADERS}
142 varaible. For \pkg{dvips} in particular, the most logical choice would
143 be the same directory in which \fname{tex.pro} and
144 \fname{special.pro} are located.
145 \item If you have an older version of \pfg, you may delete the
146 following files, if they exist: \fname{ps2frag.ps}, \fname{ps2frag}
147 or \fname{ps2psfrag} (the processing scripts),
148 and \fname{epsf.sty} (the one provided by \pfg,
149 \emph{not} the \pkg{dvips} version!). System managers may wish to
150 replace \fname{ps2frag} with a script which notifies users of the
151 upgrade.
152 \end{enumerate}
153
154 \section{Usage}
155 Here is a quick summary of the usage of \pfg:
156 \begin{itemize}
157
158 \item Use the \cs{includegraphics} command defined by the \pkg{graphics}
159 and \pkg{graphicx} packages to add EPS figures to your new documents.
160 If you must use the \cs{epsfbox} command from \fname{epsf.sty} for
161 old documents, then \fname{epsf.sty} must be loaded \emph{before}
162 \fname{psfrag.sty}. Other packages based on \fname{graphics.sty},
163 such as \pkg{graphicx} or \pkg{epsfig}, do not suffer this restriction.
164
165 \item Load \fname{psfrag.sty} with a \cs{usepackage} command.
166
167 \item Make sure that your EPS figures contain a simple ``tag'' word in
168 each position that you would like a \LaTeX\ replacements. Use
169 a \emph{single} word, composed of unaccented letters and numbers.
170 Some effort has been made to allow for more arbitrary tag text,
171 but the mechanism is not infallible; see section \ref{sec:tags}.
172
173 \item For each tag word in your EPS file, add a command to your
174 your \LaTeX\ document to specify how this tag is to replaced,
175 as follows:
176 \begin{quote}
177 \cs{psfrag}\marg{tag}\oarg{posn}\oarg{psposn}%
178 \oarg{scale}\oarg{rot}\marg{\LaTeX\ text}
179 \end{quote}
180 The tag will be replaced by the \LaTeX\ text.
181 Example: in a drawing program like \pkg{xfig}, you place the text
182 \begin{quote}
183 |xy|
184 \end{quote}
185 at a particular point. To replace this with $x+y$, one possible
186 macro would be
187 \begin{quote}
188 \cs{psfrag{xy}{$x+y$}}
189 \end{quote}
190 \end{itemize}
191
192 All \cs{psfrag} calls that precede the \cs{includegraphics} (or
193 equivalent) in the same or surrounding environments will be utilized
194 for a given PostScript file. So, you can define global \cs{psfrag}s as
195 well as those that are local to a figure.
196
197 Any text that is not mentioned in a \cs{psfrag} command
198 will not be replaced; hence, PostScript and \LaTeX\
199 text can be freely mixed.
200
201 When viewing the output with a DVI previewer such as \pkg{dviwin} or
202 \pkg{xdvi}, a vertical list of the replacements will be placed on the
203 left side of each figure. This list allows you to check the
204 typesetting of your replacements; it disappears in the final
205 PostScript version. Unfortunately, DVI drivers are incapable of
206 \emph{placing} the \pfg\ replacements on top of the figure, so
207 for that you will need to print it out or use a PostScript
208 previewer like GhostView.
209
210 This version of \pfg\ \emph{should} run properly in the compatibility
211 mode of \LaTeX2.09. Let us know if you find otherwise (see section
212 \ref{sec:mail}).
213
214 \section{Commands and Environments}\label{sec:pos}
215
216 \begin{decl}
217 \cs{psfrag}\marg{tag}\oarg{posn}\oarg{psposn}%
218 \oarg{scale}\oarg{rot}\marg{replacement}\\
219 \cs{psfrag*}\marg{tag}\oarg{posn}\oarg{psposn}%
220 \oarg{scale}\oarg{rot}\marg{replacement}
221 \end{decl}
222
223 The \cs{psfrag} macro defines a \LaTeX-typeset \marg{replacement} to be placed
224 at the same position as a PostScript \marg{tag}. The command should be placed
225 before the call to \cs{includegraphics}, or equivalent. It matches \emph{all}
226 occurrences of \marg{tag} in the figure.
227
228 A \cs{psfrag} command will remain in effect until its surrounding environment
229 is exited. Therefore, you can define global \cs{psfrag}s which will apply to
230 every figure, or define \cs{psfrag}s inside a a |figure| environment (for
231 example) which apply to a single EPS file.
232
233 The optional positioning arguments \oarg{posn} and \oarg{psposn} specify how
234 the bounding box of the \LaTeX\ text and the bounding box of the PostScript
235 text line up, respectively. Some drawing packages would refer to these as
236 ``control points'' or ``alignment points.''
237
238 \begin{description}
239 \item{\oarg{posn}}
240 the \LaTeX\ text reference point. The syntax of this argument is identical to
241 that of the \cs{makebox} command. Up to two letters may be chosen, one from the
242 list \{|t|,|b|,|B|,|c|\}, (top, bottom, baseline, center) and another from
243 \{|l|,|r|,|c|\} (left, right, center). If either letter is omitted, then |c|
244 (center) is assumed. Together, these specify one of 12 anchor points. If the
245 argument is omitted altogether, then |[Bl]|, or left baseline positioning, is
246 assumed---but note that supplying |[]| specifies centered positioning.
247
248 When running in \LaTeX\ 2.09 compatibility mode, the default alignment
249 is |[bl]|, in order to support legacy documents. Usually this should
250 not make a significant difference.
251 \item{\oarg{psposn}}
252 the PostScript text reference point. The possible arguments are
253 identical to that of \oarg{posn}, as is the default value, |[Bl]|
254 (|[bl]| in \LaTeX\ 2.09 compatibility mode.)
255 \end{description}
256
257 The \LaTeX\ replacement may be optionally scaled and rotated about
258 its reference point:
259 \begin{description}
260 \item{\oarg{scale}} Scaling factor (default 1). It's best if you
261 use font size changes in the \LaTeX\ text rather than scale, but
262 you can use the scale to tweak its size. Default is |[1]|.
263 \item{\oarg{rotn}} Extra rotation of the text around its reference
264 point, in degrees. The nominal rotation of the \LaTeX\ text matches
265 that of the PostScript text it replaces. The total rotation is this
266 nominal value plus \oarg{rotn}. The default is |[0]|.
267 \end{description}
268
269 \begin{figure}[tbh]
270 \psfragdebugon
271 \begin{center}
272 \psfrag{gA}[br][br]{|[br][br]|}
273 \psfrag*{gA}[Br][b ][2]{|[Br][b][2]|}
274 \psfrag*{gA}[ r][bl]{|[r][bl]|}
275 \psfrag*{gA}[tr][Bl]{|[tr][Bl]|}
276 \psfrag*{gA}[b ][B ]{|[b][B]|}
277 \psfrag*{gA}[B ][Br]{|[B][Br]|}
278 \psfrag*{gA}[ ][ r]{|[][r]|}
279 \psfrag*{gA}[t ][ ][0.75][45]{|[t][][0.75][45]|}
280 \psfrag*{gA}[bl][ l][1.5][30]{|[bl][l][1.5][30]|}
281 \psfrag*{gA}[Bl][tl]{|[Bl][tl]|}
282 \psfrag*{gA}[bl][Bl]{~~~~~(baseline)}
283 \psfrag*{gA}[bl][l]{~~~~~(center line)}
284 \psfrag*{gA}[bl][t][1][-90]{~~~~~(center line)}
285 \psfrag*{gA}[ l][t ]{|[l][t]|}
286 \psfrag*{gA}[tl][tr][1][180]{|[tl][tr][1][180]|}
287 \resizebox{4in}{!}{\includegraphics[angle=30]{testfig.eps}}
288 \end{center}
289 \caption{An illustration of various options for the \cs{psfrag} command.}
290 \label{fig:argexam}
291 \end{figure}
292 Figure~\ref{fig:argexam} illustrates various combinations of the arguments. If
293 you're viewing this with a DVI previewer such as \pkg{xdvi}, the \pfg\
294 replacements should be lined up to the left of the figure; and, if your
295 previewer can display EPS files, a large, rotated |gA|. If you have printed
296 this out, or are viewing it with a PostScript viewer like GhostView, then the
297 replacements should superimposed on a graphical representation of the bounding
298 box, center lines, and baseline of the tag |gA|. (This graphical box is
299 provided only in debug mode.)
300
301 If a replacement for \marg{tag} already exists, the unstarred
302 command \cs{psfrag} will replace it without warning. The starred
303 version \cs{psfrag*}, however, will \emph{add} the new replacement
304 to a list. Using the starred command, a single piece of PostScript
305 text could trigger several replacements. I can't think of a reason
306 why most users would use the starred version, but it was used in
307 Figure~\ref{fig:argexam} above.
308
309 \begin{decl}
310 \cs{begin}|{psfrags}|
311 \cs{end}|{psfrags}|
312 \end{decl}
313
314 The |psfrags| environment may be used, if necessary, to delimit the
315 scope of the \cs{psfrag} calls. As we said before, \cs{psfrag}
316 commands retain their effect until the most immediate surrounding
317 environment is exited. \emph{Any} environment will do: |center|,
318 |figure|, \etc. Therefore, it may never be necessary to use this
319 environment, and the environment has no other effect on the document.
320
321 \subsection{Embedding \pfg\ operations into EPS files}
322 \label{sec:texcomm}
323
324 \begin{decl}
325 \cs{tex}\oarg{posn}\oarg{psposn}\oarg{scale}%
326 \oarg{rot}\marg{\LaTeX\ text}\\
327 \cs{psfragscanon}~~~\cs{psfragscanoff}
328 \end{decl}
329
330 \pfg\ 3.0 supports the embedded \cs{tex} commands found in previous release of
331 \pfg. Used properly, this is a powerful tool, but it has been deprecated
332 somewhat because of its reliance on a pre-processing step. Unlike previous
333 versions of \pfg, support for the \cs{tex} command must be \emph{explicitly
334 requested}, as described below.
335
336 As you can see, the syntax of the \cs{tex} command is very similar to the
337 \cs{psfrag} command. However, instead of adding the \cs{tex} command to your
338 \LaTeX\ file, the \cs{tex} command is \emph{embedded in the EPS file itself}.
339 In other words, the command becomes its own replacement tag.
340
341 For example, you might place the text
342 \begin{quote}
343 |\tex[bl][bl]{$\alpha$}|
344 \end{quote}
345 at a particular point in your PostScript file to have \LaTeX\ replace it
346 with $\alpha$. Many \pfg\ users find this feature useful for the axis
347 labels, titles, and legends of MATLAB graphs.
348
349 The advantage to this approach is that changes can be made to the
350 EPS file without having to modify any \cs{psfrag} commands in the
351 \LaTeX\ file. (It is still necessary to \emph{re-compile} the
352 \LaTeX\ file in such cases, however.)
353
354 There are cautions and disadvantages to this approach, including:
355 \begin{itemize}
356 \item Changing the labels created by \cs{tex} commands requires editing
357 the figure; if you use \cs{psfrag} instead, you need only to edit the
358 document, which might be less cumbersome. (You must
359 run \LaTeX\ again in both cases.)
360 \item Because \cs{tex} commands are long strings, they can extend
361 past the other graphics in your EPS file. As a result, they can modify
362 the EPS bounding box in an undesired way. This problem can be mitigated by
363 reducing the font size of the \cs{tex} string, since this does not affect
364 the size of its \pfg\ replacement.
365 \item The \cs{tex} command is not supported in compressed PostScript files.
366 \item The \TeX\ engine must scan the PostScript file for these strings,
367 which can add to the processing time of your document. (To be honest,
368 we have yet to encounter a case where this is a significant concern.)
369 \item \emph{Important!} Whenever a file is scanned by \pfg,
370 it generates a file with the name \cs{jobname}\fname{.pfg}, where \cs{jobname}
371 is the base name of the master \LaTeX\ file. It will overwrite, without
372 warning, any file with that name.
373 \end{itemize}
374
375 This feature is no longer enabled automatically, except in \LaTeX\ 2.09
376 compatibility mode. So, for \LaTeXe\ documents, you must activate it in one of
377 two ways:
378 \begin{itemize}
379 \item To turn on scanning for a single figure, precede the \cs{epsfbox}
380 or \cs{includegraphics} command with a call to the command \cs{psfragscanon}.
381 Scanning will be turned off again when the surrounding environment is
382 exited; or, you can turn it off explicity with a call to \cs{psfragscanoff}.
383 \item To turn on scanning for the entire document, pass the option
384 |scanall| to \fname{psfrag.sty} in the \cs{usepackage} command.
385 \end{itemize}
386 The \cs{tex} scanner will continue to be supported in this form. So, if you do
387 find applications where you prefer the \cs{tex} command, do not hesitate to use
388 it!
389
390 \section{Package Options}
391
392 There are only four package options for \pfg. Any other options
393 that are not handled by \pfg\ will be forwarded to
394 \fname{graphics.sty}.
395 \begin{description}
396 \item[|209mode|] (\LaTeXe\ native mode only) forces \pfg\
397 to operate exactly as if \LaTeX\ 2.09 compatibility mode was
398 enabled. As a result, |bl| alignment is the default, and
399 \cs{tex} scanning is enabled for all EPS files. This option is
400 useful if you are trying to convert old \LaTeX\ 2.09 documents
401 to \LaTeXe.
402
403 The \LaTeX 2.09 version of \pfg\ generated an auxiliary
404 file for each EPS figure containing important replacement information.
405 These files are no longer used and can be deleted.
406
407 \item[|2emode|] (\LaTeX\ 2.09 compatibility mode only)
408 forces \pfg\ to remain in \LaTeXe\ mode, even in the presence of a
409 \LaTeX\ 2.09 document; this is the direct opposite of |209mode|. When
410 enabled, the default alignment is |Bl|, and \cs{tex} scanning is turned
411 off by default.
412
413 \item[|scanall|] turns on \cs{tex} scanning by default. Use this
414 option if most your figures use embedded \cs{tex} commands.
415
416 \item[|debug|] turns on some of the debugging features of PSfrag. It
417 inserts extra code into the PostScript file that draw the bounding boxes
418 of each piece of text that is replaced. It is probably not useful to anyone
419 but the developers of \pfg.
420 \end{description}
421
422 \section{An Example}\label{sec:example}
423
424 In the following example, we demonstrate how to use \pfg\ with
425 the MATLAB package. The following MATLAB commands generate a
426 plot of both a sine wave and a cosine wave, places both simple
427 tags and \cs{tex} replacements into the figure, and saves the
428 result as an EPS file \fname{example.eps}.
429 \begin{verbatim}
430 t = 0:.1:10;
431 plot(t,sin(t),t,cos(t));
432 axis('square'); grid;
433 title('\tex[B][B]{Plot of $\sin(t)$ and $\cos(t)$}');
434 xlabel('\tex[t][t]{$t$}');
435 ylabel('\tex[B][B]{$\sin(t)$, $\cos(t)$}');
436 text(t(30),sin(t(30)),'p1');
437 text(t(60),sin(t(60)),'p2');
438 text(t(90),sin(t(90)),'p2');
439 tt=text(t(50),cos(t(50)),'p3');
440 set(tt,'HorizontalAlignment','center','VerticalAlignment',...
441 'bottom','Rotation',atan2(-sin(t(50))*10,2)*180/pi);
442 print -deps example
443 \end{verbatim}
444 (In MATLAB, the 'text' command defaults to a left-center alignment,
445 corresponding to a \oarg{psposn} argument of |[l]|.)
446
447 The code below includes \fname{example.eps} into the current document,
448 resizing it to a width of 3.5 inches. Several \cs{psfrag}
449 commands are used to replace the tags |p1|, |p2|, and |p3| in
450 the figure, and the command \cs{psfragscanon} command is used to
451 notify \pfg\ that it must scan \fname{example.eps} for the
452 \cs{tex} tags.
453 \begin{verbatim}
454 \begin{figure}[tbh]
455 \unitlength=1in
456 \begin{center}
457 \psfragscanon
458 \psfrag{p1}[l]{\begin{picture}(0,0)
459 \put(0.15, 0.2){\makebox(0,0)[l]{$\sin(t)$}}
460 \put(0.1,0.2){\vector(-1,-2){0.1}}
461 \end{picture}}
462 \psfrag*{p1}[][l]{$\ast$}
463 \psfrag{p2}[][l]{$\ast$}
464 \psfrag{p3}{$\cos(t)$}
465 \includegraphics[width=3.5in]{example.eps}
466 \end{center}
467 \caption{A \textsf{psfrag} example.}
468 \end{figure}
469 \end{verbatim}
470 Note the use of a |picture| environment within the replacement
471 for |p1|.
472
473 \begin{figure}[tbh]
474 \unitlength=1in
475 \begin{center}
476 \psfragscanon
477 \psfrag{p1}[l]{\begin{picture}(0,0)
478 \put(0.15, 0.2){\makebox(0,0)[l]{$\sin(t)$}}
479 \put(0.1,0.2){\vector(-1,-2){0.1}}
480 \end{picture}}
481 \psfrag*{p1}[][l]{$\ast$}
482 \psfrag{p2}[][l]{$\ast$}
483 \psfrag{p3}{$\cos(t)$}
484 \includegraphics[width=3.5in]{example.eps}
485 \end{center}
486 \caption{A \pfg\ example.}
487 \label{fig:example1}
488 \end{figure}
489 The result of these two steps is shown in Figure~\ref{fig:example1}.
490
491 \subsection{Figure scaling and resizing}
492 \label{sec:scaling}
493
494 There are two ways to resize EPS figures with the \pkg{graphics}
495 package, and each has as different effect on \pfg\ replacements. If you
496 are used to using \fname{epsf.sty}, you will be accustomed to only one
497 such behavior.
498
499 If you use the \cs{scalebox} or \cs{resizebox} macros of \fname{graphics.sty},
500 then the \pfg\ replacments \emph{will} scale with the figure. This
501 effect is illustrated in \ref{fig:example2} below.
502 \begin{figure}[tbh]\unitlength=1in
503 \begin{center}
504 \psfragscanon
505 \psfrag{p1}[l]{\begin{picture}(0,0)
506 \put(0.15, 0.2){\makebox(0,0)[l]{$\sin(t)$}}
507 \put(0.1,0.2){\vector(-1,-2){0.1}}
508 \end{picture}}
509 \psfrag*{p1}[][l]{$\ast$}
510 \psfrag{p2}[][l]{$\ast$}
511 \psfrag{p3}{$\cos(t)$}
512 \resizebox{3.5in}{!}{\includegraphics{example.eps}}
513 \end{center}
514 \caption{The same \pfg\ example as Figure~\ref{fig:example1}, using
515 \cs{resizebox} to set the width.}
516 \label{fig:example2}
517 \end{figure}
518 Figure~\ref{fig:example2} uses the following command to scale the figure
519 to 3.5 inches in width:
520 \begin{verbatim}
521 \resizebox{3.5in}{!}{\includegraphics{example.eps}}
522 \end{verbatim} This
523 is in direct contrast to Figure~\ref{fig:example1}, which uses the
524 |width=| keyword from the \fname{graphicx.sty}, as follows:
525 \begin{verbatim}
526 \includegraphics[width=3.5in]{\includegraphics{example.eps}}
527 \end{verbatim}
528 Figure~\ref{fig:example1} also reflects the behavior that
529 you would see when using the \fname{epsf.sty} macros \cs{epfxsize},
530 \cs{epsfysize}, \emph{etc}. In these cases, the \pfg\ text does not
531 scale with it. to resize the figure.
532
533 As you can see, the text in the second figure is decidedly smaller
534 than the first. This is because \cs{resizebox} uses PostScript tricks to
535 scale \emph{all} of the contents of its argument. Since the \cs{psfrag}
536 commands are not actually typeset until \emph{within} the
537 \cs{includegraphics} command, they are resized as well.
538
539 The \fname{graphicx.sty} key-value pairs |width=|, |height=|,
540 and |scale=| scale the figure without scaling the replacement
541 text, as long as they are supplied \emph{before} an |angle=|
542 rotation key. Of course, the \cs{resizebox} and \cs{scalebox}
543 macros are still available in \fname{graphicx.sty}, so you can
544 mix and match both behaviors as you see fit. See the \pkg{graphics}
545 documentation for more details.
546
547 If you are still unsure about these distinctions, then try both
548 methods for scaling your figures until you find a convention that
549 works best for you.
550
551 \section{Common mistakes, known problems, and bugs}
552
553 \pfg\ is bug-free.
554
555 Well, of course we're kidding. \pfg\ uses some tricky PostScript hacks to
556 achieve its goals. So it really would not surprise us if you find bugs, If you
557 find any problems, please confirm they are not mentioned below; and, if not,
558 report them to te \pfg\ mailing list (see below).
559
560 \subsection{Using \pfg\ tags properly}
561 \label{sec:tags}
562
563 One of the more frequent problems that people encounter with \pfg\ is that it
564 replaces \emph{some} of their tags properly, but not all of them. Whenever
565 possible, you should design your figures \emph{with \pfg\ in mind}, by
566 following this rule:
567 \begin{quote}
568 When adding a piece of text (a \emph{tag}) in a figure for \pfg\ to
569 replace, use a \emph{single word}, containing only unaccented letters
570 and numbers.
571 \end{quote}
572 This is the way that \pfg\ is intended to be used; doing so will almost
573 guarantee that \pfg\ works as advertised. Of course, one cannot always follow
574 this rule; and a small handful of drawing packages consistently cause problems.
575 Invariably, these problems can be resolved by understanding how \pfg\ looks for
576 these tags.
577
578 PostScript has five commands to display text---|show|, |ashow|, |kshow|,
579 |widthshow|, and |awidthshow|---although, in many cases, an EPS file will
580 define abbreviations of these commands. \pfg\ actually \emph{intercepts} these
581 commands and checks them for the tags to replace. When the string matches a
582 known tag, \pfg\ figures out where the tag \emph{would} have been displayed,
583 and inserts its replacement there. When it doesn't, \pfg\ lets the |*show|
584 command proceed normally.
585
586 The strings that these |*show| display are delimited with parentheses, much
587 like the \fname{C} language uses double quotes. For example:
588 \begin{quote}
589 |(This is a test.) show| ~~~~~~~~~~~~displays~~~~~~~~~~~~|This is a test.|
590 \end{quote}
591 Unmatched parentheses and
592 certain other special characters must be preceded by a backslash in a
593 PostScript string. For example:
594 \begin{quote}
595 |(x = \(0,1]) show| ~~~~~~~~~~~~displays~~~~~~~~~~~~|x = (0,1]|
596 \end{quote}
597
598 With this in mind, here is the rule about \pfg\ tags:
599 \begin{quote}
600 The tag supplied to the \cs{psfrag} command must be typed \emph{exactly
601 as it appears in the EPS file's |*show| command}, without the surrounding
602 parentheses.
603 \end{quote}
604 In other words, \pfg\ will work only if the string in the \cs{psfrag} command
605 exactly duplicates what is found in the EPS file. If your strings have
606 backslashes added to them, as in the |x = \(0,1]| example, then you will have
607 to add that backslash to the \cs{psfrag} command as well. And \pfg\ can only
608 replace \emph{entire} strings, not just parts of one. So if your EPS file
609 contains
610 \begin{quote}
611 |(I want to replace the XXX here) show|
612 \end{quote}
613 then the \cs{psfrag} command will fail if you supply just the |XXX|.
614
615 You can use a simple text editor to check things, if you like; EPS files are
616 (almost always) just simple ASCII files.
617
618 Unfortunately, some drawing packages display text by sending each character
619 \emph{individually} to a |show| command. In other words, if you use the
620 drawing tool to put the string ``test'' in your figure, it will do something like this:
621 \begin{quote}
622 |(t) show (e) show (s) show (t) show |
623 \end{quote}
624 If this is true in your case, we apologize; it makes using \pfg\ much more
625 inconvenient---you will be limited to single-character tags. Such tools
626 also prevent the use of the \cs{tex} command.
627
628 \subsection{Problems using some \pkg{xfig} figures}
629
630 \pfg\ does not work with \pkg{xfig} figures that use ``pattern fills.'' When
631 painting/filling a polygon, \pkg{xfig} provides a number of choices: simple
632 colors or grey levels, or a number of patterns like cross-hatches, checkers,
633 \etc\ Unfortunately, using a pattern fill in a figure processed by \pfg\ results
634 in PostScript files that will not print.
635
636 Fortunately, there are workarounds:
637 \begin{enumerate}
638 \item Avoid pattern fills in your \pkg{xfig} figures; use simple
639 colors (or greys) instead. Consult the \pkg{xfig} documentation
640 for details.
641 \item Open the offending \fname{.eps} file (generated by \pkg{fig2dev}
642 or \pkg{xfig}'s ``export'' command) with your favorite text editor.
643 Look for the definition \pscom{PATfill} command; inside this
644 subroutine, replace \pscom{show} with \pscom{oldshow} (there is only
645 one occurrence).
646 \end{enumerate}
647 For those PostScript hackers out there: both \pfg\ and \pkg{xfig} redefine the
648 PostScript \pscom{show} command. \pscom{oldshow} is where \pkg{xfig} stores the
649 ``old'' version of the command. If you can determine why this fix works, and
650 convince the \pkg{xfig} maintainers to make the change; or, if you can suggest
651 a fix for \pfg, please do.
652
653 \subsection{Problems using old versions of the \pkg{seminar} package}
654 \label{sec:sem-bug}
655
656 The popular \pkg{seminar} package was, for awhile, incompatbile with PSfrag
657 3.0. This is due to the fact that PSfrag relies on certain features of the
658 \LaTeXe\ output routine, while \pkg{seminar} still uses one largely borrowed
659 from \LaTeX\ 2.09.
660
661 The best solution for this problem is to make sure that you have the latest
662 version of the \pkg{seminar} package, which can be retrieved from any CTAN
663 site, likely from the same place you found \pfg. A web page for \pkg{seminar}
664 can be found at \fname{http://www.tug.org/applications/Seminar/}. The
665 1997/10/13 version seems to have corrected the problem.
666
667 If for some reason you are forced to use an older version, there is a
668 temporary, \pkg{dvips}-specific fix: add the command
669 |\special{header=psfrag.pro}| just before |\begin{document}| in your \LaTeX\
670 file.
671
672 \section{The \pfg\ mailing list}
673 \label{sec:mail}
674
675 There is a Majorodomo mailing list for purposes of \pfg\ maintenance.
676 It \emph{is not} intended to replace this manual or a small amount of
677 educated guesswork. But, it \emph{is} the perfect place for bug reports,
678 development ideas, and so forth. Anyone who wishes to assist in
679 \pfg's evolution may subscribe; to do so, just send mail to
680 \begin{quote}
681 \netaddress{[email protected]}
682 \end{quote}
683 with the line |subscribe psfrag| in the \emph{body} of the text.
684
685 Bug supports, ideas, \emph{etc.} should go to
686 \begin{quote}
687 \netaddress{[email protected]}.
688 \end{quote}
689 If you have found a bug to report, please provide us with the
690 necessary files (a \LaTeX\ file, the EPS figures, \etc) so we can
691 test it out ourselves! Try to provide us with the shortest
692 self-contained example that demonstrates your bug. If this is not
693 possible, drop us a line first.
694
695 \end{document}