Literate programming is an idea going back to the 1980s, when a chap called Donald Knuth suggested that programs should not be written in a way to suit their execution on computers but rather in a way to facilitate human understanding and, shock horror, appreciation and enjoyment. It is no wonder that this idea hasn’t exactly taken off, it just makes too much sense.

Having tinkered with the idea during my studies, I had pretty much forgotten about this until recently discussing the need for an AstroPhysics application to acquire better documentation. There is, of course, a paper that goes along with the code that explains all the relevant maths but how would one bring this information into the code? Well, using literate programming tools, one could turn the whole thing into a paper that contains the full code that corresponds to the mathematical concepts. Nicely printed using LaTeX, this would make the human consumable part while the code can be extracted and compiled.

Now, the code is written in Fortran, so there are two options - use FWEB, a version of the original WEB system that specifically supports Fortran or use one of the language agnostic tools such as FunnelWeb, nuweb or noweb. One advantage that a system such as FWEB has is that it will ‘pretty-print’ the source code, thereby improving its enjoyability. FWEB is available on Debian and Ubuntu in the fweb package, so very easy to install and play with.

Btw. if Fortran is not your thing but Java is, have a look at Rambutan. If you are using R to create statistical reports then SWeave should be of interest.