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