Back in 2004, I wrote a blog post Versioned Literate Aspect-Oriented Programming:
As I've been developing a GEF application, I've been thinking about turning it into a tutorial. I immediately wondered if it might be a great project for literate programming.
I could write a web and then tangle it to generate the GEF application and weave it to get the tutorial. But as features are incrementally added to the application over the course of the tutorial, conventional literate programming might not be enough. At the very least, some kind of versioning would need to be included.
But then it occurred to me that it's perhaps best thought of not just as a versioning issue but as an aspect-oriented one. For example, if step four of the tutorial is adding undo support then that would involve not only new classes but the insertion of code at points in existing methods.
I wonder if such a system exists?
I've played around a little bit with using Git branches, where each branch is a step in the tutorial.
The problem is there's really two "version dimensions" in his context: the versioning of the code being developed as part of the tutorial and the versioning of the tutorial itself.
You need to be able to go back an fix a problem in tutorial step 2 and have it cascade through all subsequent steps. So in one sense, you're rewriting history, rebasing, etc. But there's still a separate history your tutorial writing is following.
Dave Long's response to my original 2004 post:
Literate programming is composing a program source by pasting together a dag of (smaller) chunks. Versioning, however, is composing a program source by pasting together a list of (sequential) edits.
The former is primarily spatial, and the latter primarily temporal, so it may not be too difficult to keep the two from interfering.
Heck; use the versioning capability to expand chunks in the appropriate environment of a configuration tree, and one would have self-documenting CM.
Of course, with things like Git, versioning is a DAG too.
Another comment I made on the idea back in 2005:
One thing that occurs to me is that the versioning in what I'm talking about isn't exactly the same kind of versioning you normally do with something like Subversion. It's not about keeping a history, it's about creating a history, so there'd be nothing wrong with going back and changing earlier versions.
Back in 2011, I posted a couple of Git-related questions to StackOverflow specifically with this project in mind:
Someone actually accused me of asking for help on my homework in that first question :-)
I'm starting to think an approach might be to have the code alongside the tutorial but have markup in the tutorial that refers to commit and tree SHAs relevant to the code changes being discussed.
"tutour" is the archaic spelling of "tutor" plus has "tour" in it which works nicely :-)
The approach I'm taking isn't (initially) literate programming Knuth-style because I'm thinking of writing code, then annotating the SHAs.
Once I get a better sense of how that's going to go, though, I think the code could be more literate.
Some examples of (hand-crafted) versioned literate tutorials that could benefit from tools:
In particular, there are examples in the above links where I redefine existing functions and it would be nice to cleanly show the diffs.
And if I were tweaking methods on a class, the approach in some of these examples just wouldn't work.
In tutour, I've started down the path of annotating SHAs after the fact, but another approach (almost the dual) would be to write a literate program containing diffs and then being able to generate the code at any step from there.
It's more natural in some respects but more cumbersome in others.
When I say "write a literate program containing diffs", they wouldn't be traditional diffs as you wouldn't want to have to explicitly say what's been deleted (besides being a pain, it would be very fragile).
In fact, fragility in the face of tweaking earlier steps is a key thing to watch for in general in any approach.
Another example of something I've written before that would be ripe for this:
http://jtauber.com/blog/2008/11/27/voronoi_canvas_tutorial_part_i/
Lately I've been thinking about a variation to the above approach where, instead of annotating SHAs, the full patches are included in the "web" and you "tangle" to get a commit history and you "weave" to get the tutorial.
So the tool wouldn't directly reference the git repo; you'd develop the tutorial and the git repo side by side.
But there'd be a separate utility where you basically say "given this point in the web, generate the patch that will get me to this SHA in the git repo".
This patch could then be incorporated into the "web", annotated appropriately, etc.
To avoid a change in the "web" breaking something, you could put in checks like "at this point, the tangled code should equal this SHA in git" (or maybe even just "this content SHA").
This is sort of like octave checks in lilypond (the music typesetting system) where, when using relative pitches, you can at any time say "this note is supposed to be in the 4th octave so flag an error if it isn't".
So I think what this would look like is an extension to something like Markdown plus the aforementioned command-line utilities.
Because the changes you want displayed in the "weaved" tutorial aren't necessarily the same as the patch necessary for the "tangled" code, the patch in the "web" must be able to be annotated not only with comments about the change, but with directives as to how to display it.
For example, often you'll want to just display the new version of something in full rather than a fine-grained diff.
Although it occurs to me that as long as you still end up with the same content SHA, the "web" itself could do things like full-replacements of functions or methods rather than containing fine-grained diffs.
It would be nice if there was language-specific knowledge in the tools so the directives could be as simple as saying "replace the foo function with this" and it work out the patch on "tangle".
I should also point out that an online version of the tutorial could present alternative displays off the diffs at the reader's choice.
So if the default is "replace the foo function with this" there could be an icon which actually switches that to display the actual diff.
Or the reader could arbitrarily say "show me a diff between step 3 and step 7 of the tutorial".