pstool (11may14)

git-svn-id: svn://tug.org/texlive/trunk@34015 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 76 insertions, 27 deletions

diff --git a/Master/texmf-dist/source/latex/pstool/pstool.tex b/Master/texmf-dist/source/latex/pstool/pstool.tex
index 5941caf3a6e..3799d3a8893 100644
--- a/Master/texmf-dist/source/latex/pstool/pstool.tex
+++ b/Master/texmf-dist/source/latex/pstool/pstool.tex
@@ -19,14 +19,17 @@ except pstool.ins (and the PDF file, obviously).
 Please see the PDF documentation for further information.
 
 Will Robertson & Zebb Prime
-Copyright 2008-2013
+Copyright 2008-2014
 Distributed under the LaTeX Project Public License, "maintained" by Will Robertson.
 
 ____________________
 Brief change history
 
+v1.5c
+  - Documentation update; some minor cosmetic code changes.
+
 v1.5b
-  - Fix conflict with beamer, which resets the catcode of @ with \begin{document}
+  - Fix conflict with beamer, which resets the catcode of @ with \begin{document}.
 
 v1.5a, March 2013:
   - Fix bug introduced in last version in which plain LaTeX compilation
@@ -58,7 +61,7 @@ v1.3, July 2009:
 \begin{filecontents*}{pstool.sty}
 % TODO: convert this package into expl3 syntax (will save many lines of code).
 
-\ProvidesPackage{pstool}[2013/03/11 v1.5b
+\ProvidesPackage{pstool}[2014/05/11 v1.5c
   Wrapper for processing PostScript/psfrag figures]
 
 % External packages:
@@ -116,7 +119,19 @@ v1.3, July 2009:
 }
 \ExecuteOptionsX{mode=batch}
 
-\DeclareOptionX{cleanup}{\def\pstool@rm@files{#1}}
+\DeclareOptionX{cleanup}{%
+  \edef\pstool@rm@files{\zap@space #1 \@empty}%
+  \@for\@ii:=\pstool@rm@files\do{%
+    \edef\@tempa{\@ii}%
+    \def\@tempb{.aux}%
+    \ifx\@tempa\@tempb
+      \PackageWarning{pstool}{^^J\space\space%
+      You have requested that ".aux" files be deleted.^^J\space\space
+      Cross-referencing within pstool graphics therefore disabled.^^J%
+      This warning occurred}
+    \fi
+  }
+}
 \ExecuteOptionsX{cleanup={.tex,.dvi,.ps,.pdf,.log}}
 
 \DeclareOptionX{suffix}{\def\pstool@suffix{#1}}
@@ -223,6 +238,18 @@ v1.3, July 2009:
   }{}%
 }
 
+% Copy a file if it exists:
+% #1: path
+% #2: filename
+% #3: new filename
+\newcommand\pstool@cp[3]{%
+  \IfFileExists{#1#2}{%
+    \immediate\write18{%
+      cd "#1"\pstool@cmdsep\pstool@cp@cmd "#2" "#3"
+    }%
+  }{}%
+}
+
 % Generic function to execute a command on the shell and pass its exit status back into \LaTeX. Any number of \cmd\pstool@exe\ statements can be made consecutively followed by \cmd\pstool@endprocess, which also takes an argument. If \emph{any} of the shell calls failed, then the execution immediately skips to the end and expands \cmd\pstool@error\ instead of the argument to \cmd\pstool@endprocess.
 % #1: `name' of process
 % #2: relative path where to execute the command
@@ -502,9 +529,9 @@ v1.3, July 2009:
 % We need to cache the aux file, so here goes.
 % This is because the aux file is cleared for writing after \cs{begin{document}}.
 \ifpdf
-  \IfFileExists{\jobname.oldaux}{\immediate\write18{\pstool@rm@cmd \jobname.oldaux}}{}
-  \immediate\write18{\pstool@cp@cmd \jobname.aux \jobname.oldaux}
-  \AtEndDocument{\immediate\write18{\pstool@rm@cmd \jobname.oldaux}}
+  \pstool@rm{}{\jobname.oldaux}
+  \pstool@cp{}{\jobname.aux}{\jobname.oldaux}
+  \AtEndDocument{\pstool@rm{}{\jobname.oldaux}}
 \fi
 
 \edef\pstool@auxmarker#1{\string\@percentchar\space <#1PSTOOLLABELS>}
@@ -517,13 +544,9 @@ v1.3, July 2009:
   \edef\pstool@label{pstool-\pstool@path\pstool@filestub}%
   \protected@write\@auxout{}%
     {\string\newlabel{\pstool@label}{{\@currentlabel}{\the\c@page}}}%
-% And copy the main file's bbl file too: (necessary only for biblatex)
-  \IfFileExists{\jobname.bbl}{%
-    \IfFileExists{\pstool@path\pstool@jobname.bbl}{%
-      \immediate\write18{\pstool@rm@cmd \pstool@path\pstool@jobname.bbl}%
-    }{}%
-    \immediate\write18{\pstool@cp@cmd \jobname.bbl \pstool@path\pstool@jobname.bbl}%
-  }{}%
+% And copy the main file's bbl file too: (necessary only for biblatex but do it always)
+  \pstool@rm{\pstool@path}{\pstool@jobname.bbl}%
+  \pstool@cp{}{\jobname.bbl}{\pstool@path\pstool@jobname.bbl}%
 % Scan the main document line by line; print preamble into auxiliary file until the document begins or \cs{EndPreamble} is found:
   \endlinechar=-1
   \def\@tempa{\pdfoutput=0\relax}% 
@@ -784,7 +807,8 @@ The disadvantage with this method is that for every document compilation, \emph{
 
 At present this package is designed solely as a replacement for \pkg{pst-pdf} in the r\^ole of supporting the \pkg{psfrag} package (which it loads) in pdf\/\LaTeX. 
 
-More flexible usage to provide a complete replacement for \pkg{pst-pdf} (e.g., supporting the \cs{begin\{postscript\}} environment) is planned for a later release. If you simply need to automatically convert plain \EPS\ files to \PDF, I recommend using the \pkg{epstopdf} package with the \pkgopt{update,prepend} package options (\pkg{epstopdf} and \pkg{pstool} should be completely compatible).
+More flexible usage to provide a complete replacement for \pkg{pst-pdf} (e.g., supporting the \cs{begin\{postscript\}} environment) is planned for a later release.
+If you simply need to automatically convert plain \EPS\ files to \PDF, I recommend using the \pkg{epstopdf} package with the \pkgopt{update,prepend} package options (\pkg{epstopdf} and \pkg{pstool} are compatible, but \textbf{only} if \pkg{epstopdf} is loaded first).
 
 \section{Getting started}
 
@@ -829,7 +853,7 @@ It is useful to define higher-level commands based on \cmd\pstool\ for including
 This catch-all macro is designed to support a wide range of graphics naming schemes. It inserts an \EPS\ file named either \meta{filename}|-psfrag.eps| or \meta{filename}|.eps| (in that order of preference), and uses \pkg{psfrag} definitions contained within either \meta{filename}|-psfrag.tex| or \meta{filename}|.tex|. 
 The \cs{psfragfig} 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 \meta{suffix} \oarg{opts} \marg{filename} \marg{input definitions}}] 
+\item[{\cmd\psfragfig~\meta{suffix} \oarg{opts} \marg{filename} \marg{input definitions}}] 
 \end{description}
 The command behaves as above, but also inserts the arbitrary code \meta{input definitions} into the processing stage; this additional code will usually be used to define new or override existing \pkg{psfrag} commands.
 
@@ -848,7 +872,7 @@ If they change, these macro files can trigger a pre-compilation of the graphics.
 While usually the macro files will be defined per-graphic (such as \texttt{foo.eps} having a \texttt{foo-psfrag.tex} file), \pkg{pstool} will also load a `master' macro file for each graphic if it exists.
 
 \begin{description}
-  \item[\pkgopt{macro-file=...}]
+  \item[\pkgopt{macro-file = ...}]
 \end{description}
 The default is \pkgopt{macro-file=\meta{jobname}\texttt{-pstool.tex}}; if this file does not exist then no macro file is loaded.
 That is, if your document is called \texttt{thesis.tex}, the master macro file will be loaded in each graphic as \texttt{thesis-pstool.tex}, if it exists.
@@ -889,26 +913,26 @@ Each graphic echoes the output of its auxiliary process to the console window; u
 \begin{description}
 \item[\pkgopt{mode=batch}] hide almost all of the \LaTeX\ output (\emph{default});
 \item[\pkgopt{mode=nonstop}] echo all \LaTeX\ output but continues right past any errors; and 
-\item[\pkgopt{mode=errorstop}] prompt for user input when errors in the source are encountered.
+\item[\pkgopt{mode=errorstop}] prompt for user input when errors are encountered.
 \end{description}
 These three package options correspond to the \LaTeX\ command line options \texttt{-interaction=batchmode}, \texttt{=nonstopmode}, and \texttt{=errorstopmode}, respectively. When \pkgopt{mode=batch} is activated, then \pkg{dvips} is also run in `quiet mode'.
 
 \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=...}] (if applicable).
+\item[\pkgopt{latex-options~~~= ...}]
+\item[\pkgopt{dvips-options~~~= ...}]
+\item[\pkgopt{ps2pdf-options~~= ...}] and,
+\item[\pkgopt{pdfcrop-options~= ...}] (if applicable).
 \end{description}
-For the most part these will be unnecessary, although passing the correct options to |ps2pdf| can sometimes be a little obscure.\footnote{The manual is here: \url{http://pages.cs.wisc.edu/~ghost/doc/cvs/Ps2pdf.htm}} For example, I use the following for generating figures in my thesis:%
+For the most part these will be unnecessary, although passing the correct options to |ps2pdf| can sometimes be a little obscure.\footnote{The manual is here: \url{http://pages.cs.wisc.edu/~ghost/doc/cvs/Ps2pdf.htm}} For example, I used the following for generating figures in my thesis:%
 \par{\centering|ps2pdf-options={-dPDFSETTINGS=/prepress}|\par}
 This forces the `base fourteen' fonts to be embedded within the individual figure files, without which some printers and \textsc{pdf} viewers have trouble with the textual labels. In fact, from v1.3 of \pkg{pstool}, this option is now the default.
 Note that subsequent calls to \pkgopt{ps2pdf-options=...} will override the \pkg{pstool} default; use |ps2pdf-options={}| to erase |ps2pdf|'s defaults if necessary.
 
 \textbf{New in 1.5}: recently, the behaviour of |ps2pdf| has changed under Windows.
 In the past, options to |ps2pdf| needed to be quoted and use |=| to assign its options.
-Something about this has now changed, and it appears the best way to set |ps2pdf| options to use the |#| character instead; therefore, \pkg{pstool} attempts to be clever and replaces all instances of |=| within a |ps2pdf| option into |#| (under Windows only).
+Something about this has now changed, and it appears the best way to set |ps2pdf| options to use the |#| character instead. Therefore, \pkg{pstool} attempts to be clever and replaces all instances of |=| within a |ps2pdf| option into |#| (under Windows only).
 No quotes are added.
 Windows uses can therefore continue to use |=| to set |ps2pdf| options and allow \pkg{pstool} to make the substitution; their documents will still compile correctly on Mac OS X or Linux platforms.
 
@@ -924,6 +948,27 @@ Note that the |auto| and |lossy| outputs differ in quality; |lossy| is lower qua
 
 \section{Miscellaneous details}
 
+\subsection{Conditional preamble or setup commands}
+
+It can be necessary to use a slightly different preamble for the main document compared to the auxiliary file used to process each graphic individually.
+To have preamble material be directed at only one or the other, use the \cs{ifpdf} command (automatically loaded from the \pkg{ifpdf} package) as follows:
+\begin{list}{}\item{}
+|  \ifpdf|\\
+|    %| \emph{main preamble only}\\
+|  \else|\\
+|    %| \emph{graphics preamble only}\\
+|  \fi|
+\end{list}
+For example, when using \pkg{beamer} and showing navigation symbols on each slide, you want to suppress these in the \pkg{pstool}-generated graphics (else they'll show up twice!).
+In this case, the preamble snippet would look something like:
+\begin{list}{}\item{}
+|  \ifpdf\else|\\
+|    \setbeamertemplate{navigation symbols}{}|\\
+|  \fi|
+\end{list}
+It would be possible to provide specific \pkg{pstool} commands or environments to do this; let me know if the \cs{ifpdf} approach doesn't work for you.
+For larger amount of preamble material that should be omitted for each graphic, the \cmd{\EndPreamble} command (see next) might also help.
+
 \subsection{The \cmd\EndPreamble\ command}
 
 The \pkg{pstool} package scans the beginning of the main document to insert its preamble into each graphic that is converted.
@@ -938,7 +983,7 @@ This is also handy to bypass anything in the preamble that will never be require
 \textbf{New in v1.5}: \pkg{pstool} now supports cross-referencing within graphics.
 That is, you can use |\ref| and |\cite|, etc., within \pkg{psfrag} commands.
 In fact, references to page numbers within an external figure should now resolve correctly; e.g., you can use |\thepage| within a \pkg{psfrag} command.
-(I haven't really tested, but this should allow any package that writes information to the |.aux| file and refers to the page number to work correctly.)
+(I haven't really tested, but this should allow any package that writes information to the |.aux| file to work correctly.)
 
 The implementation to achieve this is somewhat convoluted and difficult to extend, but the user interface should work just as you would expect, mostly.
 The main gotcha to keep in mind is that when cross-referencing is used, the graphics will need multiple compilations to resolve all the cross-references properly.
@@ -947,7 +992,7 @@ Alternatively, don't worry about the resolving of the cross-references until the
 
 \subsection{A note on file paths}
 
-\pkg{pstool} tries to ensure that you can put image files in subdirectories of the main document and the auxiliary processing will still function correctly. In order to ensure this,  the external |pdflatex| compilation uses the |-output-directory| feature of pdf\/\TeX. This command line option is definitely supported on all platforms from TeX~Live~2008 and MiKTeX~2.7 onwards, but earlier distributions may not be supported.
+The \pkg{pstool} package tries to ensure that you can put image files in subdirectories of the main document and the auxiliary processing will still function correctly. In order to ensure this,  the external |pdflatex| compilation uses the |-output-directory| feature of pdf\/\TeX. This command line option is definitely supported on all platforms from TeX~Live~2008 and MiKTeX~2.7 onwards, but earlier distributions may not be supported.
 
 One problem that \pkg{pstool} does not solve on its own is the inclusion of images that do not exist in subdirectories of the main document. For example, |\pstool{../Figures/myfig}| can not process by default because pdf\/\TeX\ usually does not have permission to write into folders that are higher in the heirarchy than the main document. This can be worked around presently in two different ways: (although maybe only for Mac~OS~X and Linux)
 \begin{enumerate}
@@ -992,7 +1037,7 @@ This package is freely modifiable and distributable under the terms and conditio
 
 \section{Code}
 
-Note that the following code is typeset in a non-verbatim manner; indentation is controlled automatically by some hastily written macros (and will sometimes not indent as might be done manually). Furthermore, spaces before comment signs are lost---when in doubt, consult the source directly!
+Note that the following code is typeset in a non-verbatim manner; indentation is controlled automatically by some hastily written macros (and will sometimes not indent as might be done manually). When in doubt, consult the source directly!
 
 \parindent=0pt
 
@@ -1088,6 +1133,9 @@ Note that the following code is typeset in a non-verbatim manner; indentation is
 
 \int_new:N \g_pstool_docline_int
 \ior_open:Nn \pstool_doc_ior {pstool.sty}
+
+\cs_set_eq:NN \___tl_trim_spaces:n \tl_trim_spaces:n
+\cs_set_eq:NN \tl_trim_spaces:n \use:n % avoid space trimming inside \seq_set_split:n following (MAJOR SIDE-EFFECTS OF COURSE)
 \ior_str_map_inline:Nn \pstool_doc_ior
  {
   \int_gincr:N \g_pstool_docline_int
@@ -1104,6 +1152,7 @@ Note that the following code is typeset in a non-verbatim manner; indentation is
      }
    }
  }
+\cs_set_eq:NN \tl_trim_spaces:n \___tl_trim_spaces:n
 
 \ExplSyntaxOff