That’s right, I’m finally beginning to take my first small steps towards literacy. I’ve known of the concept for quite some time, joining documentation and program code together into a unified document, but haven’t really been using it. Sure, I’ve used plenty of automatically extracted API documentation, but rarely (if ever) written any. And today, I needed something slightly different – I needed a report on a programming project.
As with earlier reports, I fired up LyX, because I’m a sucker for easy interfaces. I’m not really at home in LaTeX, and had prior experience that LyX could make entry of formulae, tables and such easier. This time, though, I needed some circuits, state diagrams, and above all, source code. So, looking at the options, I found LyX now supports both Noweb and Listings. So I sat about writing bits, documenting the circuit using CIRC, and inserting code with Noweb “scraps” as LyX calls them. Pretty soon, this got me tired.
LyX provided me with two options for the source code: scraps, where I had to use Ctrl+Enter to get halfway reasonable spacing, and had no indentation or syntax assistance, or Listings, where code was reformatted for printing but not in the editing view. Besides, my CIRC drawing was just literal code anyhow, so LyX didn’t help very much in the WYSIWYG department. Even looking at the file, it was clear that LyX was just adding overhead – my document would be cleaner in Noweb directly.
Having written just a little code inside LyX, I now knew I wanted back to a proper programmer’s editor. That meant Emacs or Vim. Emacs did open Noweb documents happily, but the syntax highlighting turned out to be a bit bipolar. It was switching, depending on the cursor (point?), between TeX and C sub-modes, and reinterpreting the whole document each time – which destroyed the source context. I did find a simple workaround by using /* and */ in TeX comments, letting the C mode know the text wasn’t code. Not really a big deal, but I’m not used to Emacs, and this swapping (reminescent of per window palette switching in X) was annoying either way. Vim is usually my editor of choice, but it didn’t recognize Noweb at all. For Vim, I found a few scripts, and the highest rated one actually worked. It’s not perfect – it has a few hardcoded languages it can recognize within Noweb – but it’s easy enough to modify if needed, and it does the job.
Noweb style programming is a considerable change for me. My code is now migrating from lots of different files into one larger document, within which I’m writing the structure of the code in an easier, modular fashion. It’s not perfect, but I’m learning. The current question is why double dashes (as in decrements in C) are converted to single ones in print. The same thing even happens here in wordpress. Still, a few steps forward.