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.

Sooner or later, development projects need some revision tracking. Usually right about when you either need an experimental branch for a new feature or sharing the project, which would include releases. You’ll also need to document the work, and if you’re maintaining it at all, probably track issues. Even better if this can all be done publically.
Traditionally, all these tasks are done in central repositories with specialized tools – perhaps RCS (with descendants like CVS and Subversion), Bugzilla, and so on. They’ve been more or less difficult to set up and serve, which lead to services like Sourceforge, Github, and Google Code. There are tools to handle the combination, like Trac. Most of these work, and sometimes they’re just the thing – because you know you’ll want to share the project and spend the time to set up that infrastructure.
Other times, you’re just doing a quick hack. And then you give it to someone. And, two months later, you run into an indirect friend who’s using that same hack, with their own changes, and experiencing an issue you solved later on.. but the code has grown so much you can’t easily track down the changes needed, let alone figure out which release their version is based on.

We’ve seen a move lately towards distributed revision control, with the likes of Git, Mercurial, Darcs, Bazaar and so on. They can, and do, solve the issue of independent development – but only if people use them. Mostly that tends to get stuck on either learning how to use them, or having the tool available. The first is an issue mostly because each tool is different, and the second because they have varying requirements. This is not at all unique to revision control; people hesitate all the time to install software because of complex requirements and so on.

Fossil is a project management tool intended to solve some of these issues. It’s not necessarily best at anything it does, but it does it with a minimum of setup. It has a discoverable web interface, works as one program file, stores data in self-contained files, and offers revision control, a wiki, account management for access, and issue tracking. All set up at a moment’s notice, anywhere. Of course there’s a command line interface too.

I intend to use it for a few minor projects so I get a good sense of how it’s used. At this moment, the most nagging question is if it does anything like Git’s bisection (also available in Mercurial), which is very convenient when tracking down regressions.