Question

I’ve tried using LaTeX and DocBook for documenting programming tools, to get PDF output. What I’ve found is that these tools are excellent in some ways – easily versioned, and generating very usable PDF manuals. But there is a serious flaw. Code-snippets cannot simply be cut-and-pasted out of the PDF.

With DocBook, the problem is the loss of whitespace – mostly for indentation, but any repeated spaces seem to get stripped out. So, once you paste the snippet into a text editor, you’ll need to clean up the indentation and vertical alignment. Not too much hassle for two or three lines, but it quickly gets annoying.

With LaTeX – well, it’s a mess. The following was taken from a PDF generated using the LaTeX in MikTeX 2.8.

node myclas s
f f i e l d f i e l d 0 1 : i n t ;
f i e l d f i e l d 0 2 : ” char ” ;
g;

The intended example is…

node myclass
{
  field field01 : int;
  field field02 : "char*";
};

Other than the fact LaTeX plays with the quotes, the intended form is what you see in Adobe Reader – but not much like what you get from a cut-and-paste. Don’t ask me what’s going on with the spaces, or why the braces turned into letters, or what happened to the asterisk – I don’t know!

Mostly, I’ve noticed these things playing with ways of keeping my own personal notes, and just went back to other ways. Some notes are in HTML or plain text, so I can version them. Others are in an old Journal program I’ve used for years. But I’ve written a tool that I may want to release soon – and I’ll want to include a usable PDF manual, which will need to include examples.

So – is there a way of creating PDF documentation where the code snippets can be easily cut-and-pasted? Preferably a way that allows me to keep “sources” in versioned text files.

EDIT

Any solution must be portable. I will need to use it on Linux and on Windows XP.

EDIT

It looks like this may be impossible.

I’ve tried printing from Notepad++ to the Adobe Acrobat Pro 7 printer driver. The resulting document looked fine, but cutting and pasting gave the same missing whitespace problems as occur with DocBook.

I tried using the touchup text tool in Acrobat Pro to add leading spaces. These are preserved when you save and reload – but when you select text normally in acrobat, they aren’t included. You can only cut-and-paste including those spaces using the touchup text tool, so far as I can tell, which is obviously not included in reader.

In other words, this looks like a fundamental limitation – not of the PDF format itself so much as the tools that work with it. There appears to be a general assumption at work here that whitespace is insignificant – which for my purposes obviously isn’t true.

EDIT

One solution may be a “text field”. I can add these fairly easily using Acrobat Pro, can set a fixed width font, enter multiple lines of text and make the field read only. In Acrobat Pro 7, the text in the field then isn’t selectable – but in Reader 9 it is selectable and everything is preserved when you cut and paste.

The question is – can text fields be generated directly using some kind of markup language that is usable to create complete manuals?

Answer 1

I’d suggest enscript. I use it for producing archives and documentations.
Also, you can merge multiple source codes ps’ed with enscript into another pdf.