How do you debug PDF files?

Question

Many times I create a PDF either programmatically and there might be a problem with it, e.g. some specific letter might no show up well or I might have encoding issues etc.

Is there some way to debug a PDF? E.g. see it's detailed structure?

Answer 1

There are a number of free tools that'll let you look at the guts of a PDF, uncompressed and decrypted (given the password).

RUPS for iText springs to mind (but I'm biased). I don't know that there's an iTextSharp equivalent. It's a GUI with a tree view (something ALL these apps have) of the PDF objects.

Some will let you edit the PDF within that tree, but not many. I believe Windjack's PDF CanOpener will (along with several other spiffy features you'd expect from a commercial Acrobat plugin).

And in a pinch, <insert favorite text editor here> works... but don't try to change anything. PDF is a binary format: byte offsets are important. If your text editor changes the \n to a \r\n (or tries to interpret it as UTF-8, or, or, or), your PDF will be Horribly Broken. Don't do that.

I end up doing a lot of searching for a given object number to look up indirect references. It's always a pain to look up a single digit reference because "4 obj" shows up at the end of every tenth object (14, 24, 34, 1234, etc). A regex search that looked for "beginning of line-4 obj-end of line" would be great, but I generally use notepad, so that's out (and I'm not much of a regex guy anyway).

PS: Even with a spiffy Acrobat plugin(not can opener, home grown from way back), I still need to crack open a text editor from time to time.

Acrobat will make changes at times as it loads a PDF (mostly to fix things), and if you want to know What's Really There, you need to look at that PDF in some other way. And when you're trying to debug a broken PDF, acrobat being helpful is the last thing you need.

PPS: Acrobat also has a spiffy "pdf syntax check" in its advanced->preflight profiles. It's also got checks for various PDF/* standards (PDF/X, PDF/A-1 [a and b], etc), accessibility, and so forth. They're invaluable when you're trying to Be Compliant. Not quite the debugging tool you were asking about, but Very Handy none the less.

PPPS: "diff"ing two PDFs is all but impossible, without writing a custom tool to do it for you. I wrote something that listed all the pages (with sizes) and fields (with types, flags, etc) in a predictable order and dumped it to a text file so I could diff the files... but directly diffing two PDFs is pointless. There are too many ways for "identical" files to differ (object order, dictionary key order, compression levels, etc).

Answer 2

Well, I wanted to debug some PDF files that I was generating using pdfLaTeX the other day, and I found that Adobe [Acrobat] Reader was not very helpful, as the slightly invalid PDFs I was producing would open as if there was no problem, they only failed to close. This made the TeX/View/Edit cycle a bit of a pain, since I would have to terminate the entire Reader process before I could TeX again.

I achieved more favorable results using Ghostscript. In my case, this was by way of GSview since I was using Windows; if I had been using Linux, I would have used gv instead. Not only did this not prevent me from re-TeXing the file (even while it was still open), it was nice enough to produce nigh-incomprehensible error messages rather than pretending everything was okay. These enabled me, with a bit of squinting, to see what I'd messed up in my PDF code and finally to produce the example given in this tex.SE answer of mine

It would have been nice if I could have figured out how to tell Ghostscript to include slightly more detail in the error message (well, I probably could have, if I'd looked at the right part of the manual for long enough, actually), but it wasn't that hard to figure out what I'd messed up by comparing the PDF with the Ghostscript error message and with Adobe's PDF reference. (I link to the archive page because the PDF references there were produced entirely by Adobe, and are of much higher typographic quality as well as much smaller size than the ISO standard for PDF that is on the main page.)

Of course, in order to make any sense of it in your text editor, it will probably be important that the page streams not be compressed, so I would suggest you figure out how to instruct your software not to compress them, or find something with which to uncompress them again afterwards.

So, in short:

1. Don't use Adobe [Acrobat] Reader (until you think your PDF is good, anyway).

2. Do use Ghostscript (typically through GSview or gv).

3. Do try to instruct your software to refrain from compressing page streams.

4. Do use a text editor to look at the PDF (preferably set to "PostScript" mode, as the syntax is closely related).

5. Do use the PDF reference.