Literate programming

I spent a few years working with literate programming tools, even writing my own XML-based markup language for the purpose. If you're not familiar with the notion of literate programming, it was invented by Donald Knuth while writing TeX, and formats source code (using TeX) as a readable book. The TeX source code is, in fact, a pretty readable and entertaining book.

Knuth's insight was that the order of presentation that makes understandable reading is not the same as the order of presentation that makes parsable code - he was using Pascal, so all the variable declarations had to be at the outset of a given function, but he wanted to introduce them where they were used, for instance.

His system also generated an index of identifiers and did some other nice presentation-oriented stuff.

So I wrote my own literate programming system and used it for several years, and it really did help me organize my code. But it doesn't go far enough; there's still no semantic information that's machine-usable.