Literate Programming

Ordinary programming (a.k.a. illiterate programming) consists of code with bits of text (hopefully explanatory) interspersed as comments. In 1984 Donald Knuth introduced literate programming, consisting of text interspersed with code. For example

$date$
Dear $person$
Thanks for the $gift$. I hope you do not mind being addressed in an example
of literate programming.
> date = os.getenv "Sys$Date";
> person = [[Aunt Mabel]]; gift = [[large furry draught-excluding snake]];
Your grateful nephew $from$
> from = [[Bertie]];

Looks like a mail merge that has gone wrong!

Looks like a mail merge that has gone wrong!

When all the program does is to assign values to variables appearing in the text, that is maybe a fair comment. But it works with wimp programs too.

Try this! You clicked OK $count$ times. 
> local wt = require "wimp.task"
Open wimp.task library.
> local fred, count = wt:spawn "Fred"
Create a task called Fred and a variable _count_.
> do 
>   local _ENV = fred
Make fred the environment for global variables.
>   mask = (1<<1)|(3<<4)|(1<<8)|(7<<11)|(7<<17)|(7<<22)
>   count = 0
>   local ask = "OK - go on? CANCEL - stop? Count = %d."
>   local null_event, flags, OK = 0, 23, 1
Define a handler for null events. 
>   handler[null_event] = \ (self)
>      count + = 1
>      local click = self:report (ask:format (count), flags)
>      => click ~= OK
>   end -- function
Do this before exiting. 
>   preclosedown = \ (self)
>     self:report (("You reached %d. Goodbye."):format (count))
>   end -- function
> end -- do
We are back to the old global environment. 
> fred:init ( )
Register fred with the task manager and finally
> fred:run ( )      -- run fred
run it.

So instead of a comment character, you have a code character, and as there is more code than comment, its more work and less clarity?

OK, Gov, it is a fair cop. I think Knuth thought he had a game changer in literate programming, which he developed for compiling and documenting TeX. But the uptake was not huge. Fashions come and go. I just thought a few folk might be entertained, is all.

It is definitely an interesting concept and not one I had heard of before. I think it is great idea for small scripts, particularly console/shell commands that need a particular setup or require variables set manually, particularly for the people not as literate in those languages.

I think it is great idea for small scripts,

I agree, though I think the original intentions were more ambitious. Knuth said¹ I wrote the entire TeX compiler and desk-checked it before I did any debugging on a machine. At that point I had in my hands a document of some 500 pages, containing the program and an informal proof of its correctness.

¹ In a speech on 16 July 1985 in the ancient Greek theatre of Epidaurus, as part of the 12th International Colloquium on Automata, Languages and Programming. He had started writing the compiler in 1977.

Compilers and various other terminal based applications which simply take an input and do a thing also make a lot of sense (the literate version of wc is certainly interesting (https://github.com/zyedidia/Literate/blob/master/examples/wc.lit), it sounds like doing it for more complex modern applications is a lot more challenging.

I think it all stems from the idea that we would be using natural language programming in the future (as seen from back then). However in evidence to the contrary I’d like to submit this video, on how difficult it is to state what you want in natural language to other humans, never mind a computer. Video of sandwich instructions

I think people have always relied too strongly on our anthropomorphic terminology for computing. We talk of programming languages, of reading and writing, etc. But these metaphors are misleading. Programming languages are nothing like human languages. Our understanding of how computers work far exceeds our understanding of how we ourselves work.

So instead of a comment character, you have a code character, and as there is more code than comment, its more work and less clarity?

I think the point is that code can be succinct and describes precisely what you’re doing. The reasoning and intent of the code, however, is something that needs to be conveyed to humans and because – as has been said – this is harder to do, it is clearly a longer process. So why not have the code – which is short and precise – being the inline, and the primary detail of the code communicating what you’re doing and why being the larger part of the content?

This is the converse of regular programming where you write your code, and comments are a secondary – an afterthought in some cases. Literate programming is an understanding that telling what to do is easy, but communicating with people is hard, so focus on giving the hard part greater prominence.

Many templating systems apply a similar reasoning – the thing you’re templating is more important than the control logic, so make the control logic embedded in the templating system, rather than having the templated output inside the control logic.

Even if you don’t agree with the style, giving more prominence to communication (appropriate communication) in code is good take away from such exercises.

giving more prominence to communication (appropriate communication) in code is good take away from such exercises.

Thanks for the backup. I think the educational background of RISC OS is a valuable part of its heritage, even though the world of computing has become vastly more complex in the meantime.

It is definitely an interesting concept and not one I had heard of before.

That is just why I thought it worth mentioning, and why I keep hammering away with topics that are probably rather peripheral for the majority of RISC OS users. Thank goodness we no longer have to reckon using Roman numerals. There are many things we can safely forget. But just because an idea emerged a while ago does not always mean it is not interesting – unfashionable maybe, but that is another matter. The more fundamental the concept, the longer it is worth study.

Forget Roman numerals at your peril!

I recall a question in a Computer Science exam that involved writing a program to convert between decimal numerals and Roman numerals. A student complained that this was an unfair question as nobody had ever taught him Roman numerals. I forget what his background was. Such are the pitfalls for the writer of exam questions.

I recently saw a video with a basic but very practical use for literate programming that I found interesting. It is based around linux dotfiles and emacs org-mode but it does seem like a useful concept I might have a play with at some point. Made be think back to this topic to share as it certainly made the concept a little clearer to me.

https://www.youtube.com/watch?v=pQe1ul51RM0