By Robert Laing
Computer programs are fun to write, and well-written computer programs are fun to read. — Donald Knuth’s opening sentence of Literate Programming published in 1983
Many years ago, I typeset and published a book for a friend by converting her Microsoft Word document into LyX, an open source graphical frontend for LaTeX, which simplified using Knuth’s mathematical typesetting language TeX.
A reason I did this was a large company had blatantly plagiarised material from the ringbound printouts of her MS Word document done by the local business centre. Lawyers got her nowhere. With the aid of LyX, her training manual was turned into a beautifully typeset, bound softback complete with table of content pointing to the correct page numbers, and even an index. As soon as the plagiarists saw it, they assumed she had secured the support of some massive publisher — not just some hobbyest friend publishing it as a learning exercise — admitted guilt and paid royalties. Her sales to students also went up.
TeX is very good at producing files for printers — where the dominant format is Adobe’s PDF, a descendant of PostScript, an implementation of a programming language called Forth.
Principle of least power
Horror stories of how pranksters and criminals abused that “files for printing” were in fact written in a fully-fledged programing language able to do plenty of malicious stuff prompted Tim Berners-Lee to addopt a “principle of least power” for HTML.
I could have used a language like Donald Knuth’s TeX, which though it looks like a markup language is in fact a programming language. It would have allowed very fancy typography and all kinds of gimmicks, but there would have been little chance of turning web pages into anything else. — Weaving the Web: The Past, Present and Future of the World Wide Web by its inventor, published in 2000
But for all HTML’s faults, it’s a huge improvement on PDF. Many financial institutions still love PDF files, emailing them to get filled in. Though my browser lets me view PDF files, it doesn’t support editing them, so I have to print out the form, fill it out by hand, scan these pages to email back to the financial institution, where a data input clerk invariably makes typos which could have been avoided by letting me type in my own name and address, easily done with an HTML web page. Corporate love of PDF files keeps overheads high because since they are often hard to read on a computer screen, every document gets printed, ramping up paper and toner costs.
Though LyX does let me output documents as HTML instead of PDF, the resulting web pages are not very pretty or easy to navigate. Generally, the technology Knuth developed was excellent for books — especially those with mathematical equations. How to improve on traditional books with the technology available to us is a big problem of our age.
Untangling the Web
Note that while I’m using a document generation system written in Go called Hugo for this site, it serves a different purpose to godoc. Hugo uses a templating language to convert Markdown to HTML, whereas godoc creates reference material for go packages if their comments are written correctly. A pet peeve of mine is that the “howto use the automated documentation system” of every programing language I’ve encountered is badly documented. (I just started teaching myself Go, and found it annoying godoc doesn’t come with the base package).
How to Design Programs
Benefiting from the obvious advantages of well defined specifications, test-driven development, and clear documentation with examples, means weaning oneself off the bad habit of coding first, thinking second, which is difficult for those of us not educated on how to do things properly from day one, which is what How to Design Programs strives to do.
Its six step design recipe shows that documentation, specifications or interfaces, and tests are all intertwined and need to be done hand-in-hand with coding.
As someone who dabbles with lots of different programing languages, I prefer general tools. For instance, I prefer simple text editors which handle syntax highlighting for just about anything to integrated development environments. A reason I switched from Doxygen is it didn’t support syntax highlighting for code of various programming languages I used. Hugo’s list of supported code formats, on the other hand, shows what an incomprehensibly large world of programing languags and data formats are out there.
Dr Racket doesn’t come with any fancy tools to generate online documentation, but mapping its six part recipe to the way the various *Doc packages mentioned above generate HTML pages I find a powerful way to build software in a disciplined way.
I’ve tried to tie the following six sections to each step of the How to Design Programs recipe, with examples from programming languages I think have implemented good tools to do it with.