Through the Looking Glass

"golst: readable Golang source listings"

Posted on March 10, 2013

While working on the book I’m currently writing, I wanted to print out some source listings to take notes on; often times when writing, I prefer to remove myself from the computer and go analogue with pad and paper. As part of the writing process, I wanted to be able to refer to the source code examples for the book, and therefore needed them with me. Normally when I print out source code (which admittedly is rarely), I just hit ‘print’ from vim.

However, I ran across a post recently by Luke Gorrie titled Readable Programs. I’d seen CWEB before, as well as Michael Fogus’ Marginalia, so the concept wasn’t new. However, his inclusion of a sed oneliner for producing PDF listings triggered some latent ideas in my head. In his oneliner, he uses --- as the delimiter for markdown comments. However, I wanted to be able to take just any Go source file and produce a listing without any special syntax or weird formatting: if it’s good enough for GoDoc, it should be good enough for whatever tool I use. Particularly, the use of Markdown as the “literate” formatting syntax stuck with me.

The tool I’ve written, golst, is designed to extract the godoc comments out of the package. I’ve put this together in an hour or so, so right now the /* */ style comments aren’t parsed, only // comments that start the line.

For example output, see the listings for the listing.go source file:

Source code is up on Github. Alternatively,

    go get github.com/gokyle/golst