Brooks (brooksmoses) wrote,

"Literate Programming", Fortran, and TeX.

One of the interesting sort of side things that came out of Knuth's original work on the TeX typesetting program is the idea of literate programming -- the idea that a program should be written, and be readable, like a piece of ordinary prose. Like most ideas that have become programming buzzwords, any given N programmers will have at least N+1 ideas about what it actually means, and most of those will be contradictory to some extent. At a functional level, though, the essential idea is that one can process the source code with one tool and produce the compiled executable, or one can process the same source code with another tool and produce a readable typeset version of the comments with the code embedded in them.

In my case, the programs that I've recently been writing involve rather a lot of mathematical derivations prior to actually writing any code -- for instance, a day's worth of messy integrals, and then six or eight lines of Fortran that implement the result. It's rather important to document all of that mathematics (and the thought process behind it) somewhere in case I need to revisit it, and the most obvious place to document it is within the same file as the source. But writing mathematics in ASCII comments is painful; for this, one really wants TeX. Thus, I arrive at the need for literate programming, at least of a somewhat weak sort, that will allow me to write TeX and Fortran in the same file.

The problem with things like this is that everyone's needs are a bit idiosyncratic -- this goes back to the N+1 ideas I just mentioned. In my case, I want source files that I can compile directly to executable; the extra step of extracting Fortran from some other format before compiling it would be a significant slowdown in my debugging cycle. I also want the typeset version of the output to be defined with completely standard LaTeX, and I want a fair bit of control over the output formatting. In particular, though, I need to be able to include all of LaTeX's equation-writing capability, and include some extra utilities that enhance that.

There are undoubtably other tools that do most of this, but they also undoubtably are going to end up not being exactly what I want in some crucial way that I'll only discover after using them for a while, so it seemed simplest just to go ahead and write my own -- for what I want, it's a simple enough thing that I started and finished it all today, and I know exactly how to use it and change it. There's only one program involved; since the source is standard Fortran with some restrictions on what goes in the comments, all I needed to write was the program to extract the LaTeX from the comments and add in whatever is necessary to handle the rest.

So, for those of you who might be curious or find it useful, I've put the source code on my website here. Of course, this program is written in the same literate format that it interprets, and so it's trivial to produce a nicely formatted and readable version, which is in this .pdf file. It's not really the best example of a literate program, as there's not too much commentary on the problem -- as I said, it's a pretty simple program! -- but it at least shows off the formatting.
  • Post a new comment


    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.