summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/pstool
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-07-06 00:13:51 +0000
committerKarl Berry <karl@freefriends.org>2009-07-06 00:13:51 +0000
commite651b058802905949b57e67c813f83a01d29eb34 (patch)
tree3519e0529f47a10c89808d4d9e636ac1dcab8eaf /Master/texmf-dist/source/latex/pstool
parented098f056f74e731d05b63d13b3c494395ded8bd (diff)
-mpstool 1.2b (4jul09)
git-svn-id: svn://tug.org/texlive/trunk@14130 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/pstool')
-rw-r--r--Master/texmf-dist/source/latex/pstool/pstool.tex74
1 files changed, 38 insertions, 36 deletions
diff --git a/Master/texmf-dist/source/latex/pstool/pstool.tex b/Master/texmf-dist/source/latex/pstool/pstool.tex
index d7159547dc4..d4b434b399f 100644
--- a/Master/texmf-dist/source/latex/pstool/pstool.tex
+++ b/Master/texmf-dist/source/latex/pstool/pstool.tex
@@ -2,7 +2,7 @@
\begin{filecontents*}{README.txt}
__________________
The pstool package
-v1.2a
+v1.2b
A package like "pst-pdf" for processing PostScript graphics
with psfrag labels within pdfLaTeX documets. The difference
@@ -22,7 +22,7 @@ Copyright 2008
\end{filecontents*}
\begin{filecontents}{pstool.sty}
-\ProvidesPackage{pstool}[2009/05/25 v1.2a
+\ProvidesPackage{pstool}[2009/07/03 v1.2b
Wrapper for processing PostScript/psfrag figures]
% External packages
@@ -221,8 +221,8 @@ Copyright 2008
}
\def\pstool@stripEPS#1.eps#2\@nil{#1}
-% |test.eps\@nil|->|test|\\
-% |test.eps.eps\@nil|->|test|
+% |test.eps\@nil| $\to$ |test| (|#2| $\to$ \<empty>)\\
+% |test.eps.eps\@nil| $\to$ |test| (|#2| $\to$ |.eps|)
% \section{Command parsing}
% User input is \cmd\pstool\ (with optional |*| or |!| suffix) which turns into one of the following three macros depending on the mode.
@@ -233,7 +233,7 @@ Copyright 2008
\ifpdf
\newcommand\pstool@neverprocess[3][]{%
- \pstool@includegraphics[#1]{#2}}
+ \pstool@includegraphics{#2}}
\else
\newcommand\pstool@neverprocess[3][]{%
\begingroup
@@ -250,7 +250,7 @@ Copyright 2008
\pstool@IfnewerEPS{% needs info from |\pstool@getpaths|
\pstool@process{#1}{#3}%
}{%
- \pstool@includegraphics[#1]{#2}%
+ \pstool@includegraphics{#2}%
}%
}{%
\pstool@process{#1}{#3}%
@@ -297,7 +297,7 @@ Copyright 2008
-interaction=\pstool@mode\space
\pstool@latex@opts\space
"\pstool@jobname.tex"}%
-% Execute dvips in quiet mode if latex is not run in (non/error)stop mode:
+% Execute |dvips| in quiet mode if |latex| is not run in (non/error)stop mode:
\pstool@exe{dvips}{\ip@directpath}{%
dvips \if@pstool@verbose@\else -q \fi -Ppdf
\pstool@dvips@opts\space "\pstool@jobname.dvi"}%
@@ -315,7 +315,7 @@ Copyright 2008
\fi
\pstool@endprocess{%
\pstool@cleanup
- \pstool@includegraphics[#1]{%
+ \pstool@includegraphics{%
\ip@directpath\ip@lastelement}%
}%
\pstool@echo@verbose{^^J=== pstool: end processing ===^^J}%
@@ -371,8 +371,12 @@ Copyright 2008
% for EPS figures with psfrag:
\newcommand\psfragfig[2][]{\pstool@psfragfig{#1}{#2}{}}
-\WithSuffix\newcommand\psfragfig*[2][]{\pstool@psfragfig{#1}{#2}{*}}
-\WithSuffix\newcommand\psfragfig![2][]{\pstool@psfragfig{#1}{#2}{!}}
+\WithSuffix\newcommand\psfragfig*[2][]{%
+ \pstool@psfragfig{#1}{#2}{*}%
+}
+\WithSuffix\newcommand\psfragfig![2][]{%
+ \pstool@psfragfig{#1}{#2}{!}%
+}
% Parse optional \<input definitions>
\newcommand\pstool@psfragfig[3]{%
@@ -387,10 +391,10 @@ Copyright 2008
%
% |#1|: possible graphicx options\\
% |#2|: graphic name (possibly with path)\\
-% |#3|: |\pstool| suffix (i.e., |!| or |*| or empty\\
-% |#4|: possible \pkg{psfrag} macros
+% |#3|: |\pstool| suffix (i.e., |!| or |*| or \<empty>)\\
+% |#4|: possible \pkg{psfrag} (or other) macros
\newcommand\pstool@@psfragfig[4]{%
- % Find the.eps file to use.
+ % Find the .eps file to use.
\IfFileExists{#2-psfrag.eps}{%
\edef\pstool@eps{#2-psfrag}%
\OnlyIfFileExists{#2.eps}{%
@@ -444,6 +448,7 @@ Copyright 2008
}%
}
+% That's it.
\end{filecontents}
%%%%%%%%%1%%%%%%%%%2%%%%%%%%%3%%%%%%%%%4%%%%%%%%%5
@@ -472,7 +477,7 @@ Copyright 2008
\usepackage[rm,medium]{titlesec}
-\usepackage{bigfoot,xcolor}
+\usepackage{xcolor}
\usepackage[colorlinks,linktocpage]{hyperref}
\usepackage{gmdoc}
\usepackage{gmverb}
@@ -480,6 +485,9 @@ Copyright 2008
\stanzaskip=\bigskipamount
\CodeSpacesGrey
+\usepackage{enumitem}
+\setlist{noitemsep}
+
\usepackage{tocloft,varwidth}
\setcounter{tocdepth}{1}
\def\tocwidthA{0.45}
@@ -542,13 +550,13 @@ More flexible usage to provide a complete replacement for \pkg{pst-pdf} (e.g., s
\section{Getting started}
-Load the package as usual; no package options are required by default, but there are a few useful options described later in section~\ref{pkgopt}. Note that you do not need to load \pkg{psfrag} separately.
+Load the package as usual; no package options are required by default, but there are a few useful options described later in section~\ref{pkgopt}. Note that you do not need to load \pkg{psfrag} separately. You also do not need to load \pkg{graphicx} separately, but if you do so, ensure that you do \emph{not} include driver information (such as |[pdftex]|); this will play havoc with \pkg{pstool}'s automatic processing stage.
-The generic command provided by this package is
-\begin{center}
+The generic command provided by this package is\par
+{\centering
\cmd\pstool\ \arg[graphicx options] \arg{filename} \arg{input definitions}
-\end{center}
-It converts the graphic \<filename>|.eps| to \<filename>|.pdf| through a unique \DVI$\to$\PS$\to$\PDF\ process for each graphic, using the preamble of the main document. The resulting graphic is then inserted into the document, with optional \<graphicx options>. The third argument to \cmd\pstool\ allows arbitrary \<input definitions> (such as \cmd\psfrag\ directives) to be inserted before the figure as it is processed.
+\par}
+It converts the graphic \<filename>|.eps| to \<filename>|.pdf| through a unique \DVI$\to$\PS$\to$\PDF\ process for each graphic, using the preamble of the main document. The resulting graphic is then inserted into the document, with optional \<graphicx options>. Note that these optional arguments take effect in the \emph{processing stage}; if you change the \<options>, you must re-process the figure. The third argument to \cmd\pstool\ allows arbitrary \<input definitions> (such as \cmd\psfrag\ directives) to be inserted before the figure as it is processed.
The command \cmd\pstool\ can take an optional |*| or |!| suffix to change the behaviour of the command:
\begin{description}
@@ -562,9 +570,9 @@ It is useful to define higher-level commands based on \cmd\pstool\ for including
\begin{description}
\item[{\cmd\psfragfig\arg[opts]\arg{filename}}]
This is the catch-all macro to support a wide range of graphics naming schemes. It inserts an \EPS\ file named either \<filename>|-psfrag.eps| or \<filename>|.eps| (in that order of preference), and uses \pkg{psfrag} definitions contained within either \<filename>|-psfrag.tex| or \<filename>|.tex|.
-
-This command can be used to insert figures produced by the \textsc{Mathematica} package \pkg{MathPSfrag} or the \textsc{Matlab} package \pkg{matlabfrag}. \cmd\psfragfig\ also accepts an optional braced argument as shown next.
-
+\end{description}
+This command can be used to insert figures produced by the \textsc{Mathematica} package \pkg{MathPSfrag} or the \textsc{Matlab} package \pkg{matlabfrag}. \cmd\psfragfig\ also accepts an optional braced argument:
+\begin{description}
\item[{\cmd\psfragfig\arg[opts]\arg{filename}\arg{input definitions}}]
As above, but inserts the arbitrary code \<input definitions>, which will usually be used to define new or override existing \pkg{psfrag} commands.
\end{description}
@@ -575,23 +583,19 @@ As above, but inserts the arbitrary code \<input definitions>, which will usuall
\subsection{Forcing/disabling graphics processing}
\label{process}
-While the suffixes |*| and |!| can be used to force or disable (respectively) the processing of each individual graphic, sometimes we want to do this on a global level. The following package options override \emph{all} \cmd\pstool\ (and related) macros:
+While the suffixes |*| and |!| can be used to force or disable (respectively) the processing of each individual graphic, sometimes we want to do this on a global level. The following package options override \emph{all} \pkg{pstool} macros:
\begin{description}
\item[\pkgopt{process=auto}] This is the default mode as described in the previous section, in which graphics with suffixes are only (re-)processed if the \EPS\ file is newer or the \PDF\ file does not exist;
\item[\pkgopt{process=all}] Suffixes are ignored and all \cmd\pstool\ graphics are processed;
\item[\pkgopt{process=none}] Suffixes are ignored and no \cmd\pstool\ graphics are processed.\footnote{If \pkg{pstool} is loaded in a \LaTeX\ document in \DVI\ mode, this is the option that is used since no external processing is required for these graphics.}
\end{description}
-Also note that it would be nice to detect the age of files other than the \EPS\ and \PDF\ graphics in order to affect the processing decisions. This is planned for a possible future release.
-
\subsection{Cropping graphics}
The default option \pkgopt{crop=preview} selects the \pkg{preview} package to crop graphics to the appropriate size for each auxiliary process.
However, when an inserted label protrudes from the natural bounding box of the figure, or when the original bounding box of the figure is wrong, the \pkg{preview} package will not always produce a good result (with parts of the graphic trimmed off the edge). A robust method to solve this problem is to use the \pkg{pdfcrop} program instead.%
\footnote{\pkg{pdfcrop} requires a Perl installation under Windows, freely available from \url{http://www.activestate.com/Products/activeperl/index.plex}} This can be activated in \pkg{pstool} with the \pkgopt{crop=pdfcrop} package option.
-In the future I plan to also support \pkg{epstool} for doing the same thing.
-
\subsection{Temporary files \& cleanup}
Each figure that is processed spawns an auxiliary \LaTeX\ compilation through \DVI$\to$\PS$\to$\PDF. This process is named after the name of the figure with an appended string suffix; the default is \pkgopt{suffix=\{-pstool\}}. All of these suffixed files are ``temporary'' in that they may be deleted once they are no longer needed.
@@ -611,10 +615,10 @@ These three package options correspond to the \LaTeX\ command line options \text
\subsection{Auxiliary processing command line options}
The command line options passed to each program of the auxiliary processing can be changed with the following package options:
\begin{description}
-\item[\pkgopt{latex-options}] ;
-\item[\pkgopt{dvips-options}] ;
-\item[\pkgopt{ps2pdf-options}] ; and,
-\item[\pkgopt{pdfcrop-options}] .
+\item[\pkgopt{latex-options=...}];
+\item[\pkgopt{dvips-options=...}];
+\item[\pkgopt{ps2pdf-options=...}]; and,
+\item[\pkgopt{pdfcrop-options=...}].
\end{description}
For the most part these will be unnecessary, although passing the correct options to |ps2pdf| can sometimes be a little obscure. For example, I use the following for generating figures in my thesis:\par
{\centering|ps2pdf-options={-dCompatibilityLevel=1.4 -dPDFSETTINGS=/prepress}|\par}
@@ -630,7 +634,7 @@ where-ever you'd like the preamble in the auxiliary processing to end (although
\subsection{Cross-reference limitations}
-The initial release of this package does not support cross-references within the \pkg{psfrag} labels of the included graphics. (If, say, you wish to refer to an equation number within a figure.) A future release of \pkg{pstool} will hopefully lift this limitation.
+The initial release of this package does not support cross-references within the \pkg{psfrag} labels of the included graphics. (If, say, you wish to refer to an equation number or a citation within a figure.)
\subsection{A note on file paths}
@@ -642,18 +646,16 @@ One problem that \pkg{pstool} does not (currently) solve on its own is the inclu
|openout_any=a pdflatex ...|
\item Create a symbolic link in the working directory to a point higher in the path: |ln -s ../../PhD ./PhD|, for example, and then refer to the graphics through this symbolic link.
\end{enumerate}
-I hope to directly solve this problem in the future by using a caching folder for the auxiliary processing in such cases.
\section{Package information}
The most recent publicly released version of \pkg{pstool} is available at \textsc{CTAN}:\\
\centerline{\url{http://tug.ctan.org/pkg/pstool/}}\\
Historical and developmental versions are available at GitHub:\\ \centerline{\url{http://github.com/wspr/pstool/}}\\
-While general feedback at \url{wspr81@gmail.com} is welcomed, specific bugs should be reported through the bug tracker at FogBugz: \url{https://wspr.fogbugz.com/} (click `\textsc{tasks}: Enter a New Case').
+While general feedback at \url{wspr81@gmail.com} is welcomed, specific bugs should be reported through the issue tracker at GitHub: \url{http://github.com/wspr/pstool/issues}.
\subsection{Licence}
-This package is freely modifiable and distributable under the terms and conditions of the \LaTeX\ Project Public Licence, version 1.3c or greater (your choice). The latest version of
-this license is available at: \url{http://www.latex-project.org/lppl.txt}. This work is maintained by \textsc{Will Robertson}.
+This package is freely modifiable and distributable under the terms and conditions of the \LaTeX\ Project Public Licence, version 1.3c or greater (your choice).\footnote{\url{http://www.latex-project.org/lppl.txt}} This work consists of the files |pstool.tex| and the derived files |pstool.sty|, |pstool.ins|, and |pstool.pdf|. This work is maintained by \textsc{Will Robertson}.
{\addtocontents{toc}{\protect\end{varwidth}\protect\hfill}}
{\addtocontents{toc}{\protect\begin{varwidth}[t]{\protect\tocwidthB\protect\linewidth}}}