Three Dollar Quill

A grab-bag of things, followed by a little more depth:

• I looked into literate programming. More on that in a moment.
• I revisited some hobby code. It is now more correct, and less prone to stack overflows.
• I did a bunch of merges with my Jedi fork to hopefully get ready to start actually developing.

I let this entry go late, so I'm going to try to type quickly.

Literate Programming is a subject somewhere between obscure and contentious, except for Haskell, and CoffeeScript, I guess. I think I also read about it in R. I guess what I should have said is, there seems to be widely scattered experimentation with the concept, but it hasn't really taken the world by storm in the course of 35 or so years. I've mainly been exposed to the general through Jupyter notebooks, which don't go as far as Knuth's CWEB tool, and also have... issues (I haven't watched the recording, but I read the slides, and it seemed to jibe with my experiences. Hopefully things have changed since I last seriously tried to use Jupyter.)

Anyway, what is literate programming? According to that website I linked:

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

But some people feel that the original implementations of the idea (from Knuth!) falls short in various ways.

For my part, I've been refreshing my memory on what's out there, with a focus on Python, over the last few days. I might do a survey of things later, but I don't have time to hunt down and describe all of the links. Thinking over the way I want to see my own documentation improve, I think I don't need to learn a new tool for it. What I need to do is focus on documenting the affordances and requirements of my public interfaces, and make sure that dependencies are hyperlinked. The idea being, to make it easy, using the existing documentation infrastructure, for people to put together the narrative that tells them how to use the library, using fragments of hypertext. ("What?" "They need to be able to wiki-walk the documentation." "Oh.")

Examples of the kinds of information that should be included:

• Required types/interfaces ("What do I need to give it?")
• Provided types/interfaces ("What can I do with what it gives me back?")
• Known subclasses/implementations ("How can I satisfy this requirement?")

I'll give it a shot tomorrow. Good night for now!