New version of pstool
New version of pstool
Somewhat to my surprise, I have a new version of pstool to release.
This is a LaTeX package I maintain that provide an easy workflow (I hope) for including psfrag graphics into pdfLaTeX documents.
This allows, say, graphs from Matlab or Mathematica to be presented with fonts matching your document and using macros defined in your main preamble.
For context below, here’s a brief run-down of how it works.
As a graphic is requested in the main document (using \psfragfig or similar), a check is made whether it has been converted into PDF in a previous compilation (and the source graphic hasn’t been updated in the mean time).
If so, it saves some time and simply loads that graphic.
If not, an entirely new LaTeX document is created with the preamble of the main document, but which otherwise contains only the graphic that needs to be processed.
This document is run through the regular (‘old-fashioned’) latex → dvips → ps2pdf compilation workflow, which performs the wanted psfrag substitutions (and any other PostScript-based processing) and the final figure is cropped to size.
Execution returns back in the main document and the PDF graphic can be inserted directly, and the compilation of the main document continues as normal.
The pstool package been invaluable to me in preparation of my PhD thesis, but I haven’t had the opportunity to work on the code for a long time.
In fact, I discovered some code I’d written for it from 2010 (see below) that I’d never released to CTAN.
Why a new package now, then? Because I hate it when my code breaks and wastes people’s time.
Windows ps2pdf breaking
Some time back, the maintainers of ps2pdf changed the way that options were passed on the command line under Windows, so where previously pstool was writing something like
ps2pdf "-dPDFSETTINGS=/prepress" "foo.ps" "foo.pdf"
to generate the PDF file from the psfrag-generated PostScript file, the default settings were now terribly broken for recent users of MiKTeX, causing their documents to fail to compile. The syntax which now works correctly is
ps2pdf -dPDFSETTINGS#/prepress "foo.ps" "foo.pdf"
Note # instead of = to set the options.
In order to fix the issue, I decided to separate the fix from the user-level interface to pstool, which can set ps2pdf options with syntax like
\usepackage[
ps2pdf-options={-dPDFSETTINGS=/prepress}
]{pstool}
Rather than requiring users to know to replace the = with \# (remembering that # is a special character than needs to be escaped), pstool automatically replaces all equals signs in the ps2pdf options with hash characters.
This provides some level of platform-independence so that documents will compile correctly whether on Windows, Linux, or Mac OS X.
Of course, it will still work correctly for Windows users that write \# anyway.
More robust preamble scanning
The second feature (and this is the code that was written in 2010 but never released) is a more robust scanning method for copying the main document’s preamble into the preamble for each externally processed graphic.
In prior versions of the package, this was achieved by redefining \begin{document} but this method broke whenever a class or package did their own redefinition.
The command \EndPreamble was provided to manually indicate where the preamble should end, but users would usually run across the error and not know where to look to fix the problem.
The changes for this feature are all internal and shouldn’t be noticeable if the code is working correctly; \EndPreamble still works for the cases where you don’t need the entire document preamble to be replicated for each graphic.
Cross-references and citations supported
The third major change for the new version of pstool is to support cross-references and citations in externally-processed graphics.
This has been on my wish-list for some time, as I know that some people have used references and citations in their figures and graphs, and have had to use Rolf Niepraschk’s pst-pdf (or my wrapper package auto-pst-pdf) in this case.
That solution is fine and perhaps still preferable in many cases, but if it could be done in pstool then I wanted to try and support it if possible.
It wasn’t entirely straightforward, but I think it now works.
The short of it is: the main file’s .aux and .bbl files are now copied over for each graphic’s external compilation; the current page number is passed into the external graphic; and anything written to the .aux file by the external graphic is copied back into the main document’s .aux file.
Copying the .bbl file is only necessary to support biblatex use, for reasons I’m still not entirely clear on.
What does this allow us to do now? If you have a document that defines several different equations and plots the results of those equations, it is possible to annotate the figure with the actual equation numbers cross-referenced from the document. Or even include a citation in the graph for some method that was described in another paper.
However, there’s a downside to all of this, which is that pstool graphics require multiple passes to resolve any cross-referencing.
And this is not possible to detect automatically (well, it may be theoretically possible but I don’t think it’s easy).
So the old approach of pstool to check the PDF and update the graphic only if necessary fails for those which use cross-references; in these cases, it is necessary to force their generation manually until everything resolves.
This can be done on a per-graphic level by using \psfragfig*, or on a document level by loading the package with the [process=all] option.
This new version is still being tested on GitHub (please check it out if you’d like to help!) and I hope to upload it to CTAN in the next few days. I hope this release marks the beginning of somewhat of a return to the LaTeX community for me — last year was tumultuous for many reasons and I hope I can now re-dedicate some time every week.
Famous last words.