constantly.at

home

Low-cost Literate Programming

28 Oct 2014

Low-cost Literate Programming

I’ve long been a fan of Luke Gorrie’s pbook, which converts a buffer containing source code into a marked-up LaTeX document (See the linked document for an example). This makes it very easy to read a source file and makes commenting a pleasure. But I never used it as much as I would have liked, since the implementation was a bit crufty and not easy to customize (fixed filename, no way to safely set the per-line comment prefix, etc.).

Recently I stumbled upon a new blog post, in which Luke replaces the whole pbook program with a sed one-liner. rs-pbook is an implementation of this approach, surrounding the global search-and-replace with a bit of Emacs comfort (auto-handling comment prefixes, making the output format extensible, creating a buffer with a proper filename, etc.).

How to use it

Write your source code as usual, sprinkling it with top-level comments beginning in column 0. These comments will be converted to text, everything else becomes code blocks.

M-x rs-pbook creates a buffer in org or markdown format. Use this to create pdf or html, browse on screen, or print it out and read on the bus. Hope it is useful!