Indeed. I think the point I was trying to get across is that I feel that the presentation of code differs from the execution of code. The Jonesforth example is simply because, essentially, there’s but a single path through the code (most specifically the NEXT and the organization of the dictionary, and the compiler), followed by a litany of individual words which (mostly) can be taken as isolated context.
Most complicated systems have many disparate paths through their system. This is where you get the “impedance mismatch” of a “reference guide” and “user’s guide”.
The reference guide is many of the component in isolation whereas the user’s guide gives a higher level view of how the components are stitched together. Those two documents, while related, are fundamentally different on their approach.
Now, again, I don’t have any vast experience with examples of Literate Programming, but I find it hard to see a single document filling both roles.
The other example to cite is the Software Tools books by Kernighan and Plauger. These books go in to the detail of implementing non-trivial programs as well as a mechanism to espouse their software “tools” philosophy. The programs are presented as isolated routines, some routines are evolved during the presentation. In the end you get the entire program, but not in a single throw, and not necessarily in the proper order.
Mind, this is not Literate Programming. You can’t run the book through a tool and get working code – but it’s pretty close. With some effort, it could be made “literate” with little more than the robust use of language comments ala Jonesforth.
But in the end, I think, most developers (me, notably) want the code with “notes” more so than “literate programming”. In that I’d rather read the code and ask questions (i.e. refer to notes) than read the english prose and then the code.
An interesting compromise in this is Forth and Shadow Screens.
Consider (I appreciate this is wide)
\ 16 bit Stack Operations 22Aug83map | \ 16 bit Stack Operations 02AUG83HHL
CODE [email protected] (S -- n ) | [email protected]
SP AX MOV 1PUSH END-CODE | Return the address of the next entry on the parameter stack
CODE SP! (S n -- ) | SP! ( Warning, this is different from FIG Forth )
SP POP NEXT END-CODE | Sets the parameter stack pointer to the specified value.
CODE [email protected] (S -- addr ) | [email protected]
RP AX MOV 1PUSH END-CODE | Return the address of the next entry on the return stack.
CODE RP! (S n -- ) | RP! ( Warning, this is different from FIG Forth )
RP POP NEXT END-CODE | Sets the return stack pointer to the specified value.
In original Forth, code was organized in 1K blocks called screens. Screens are numbered. Screens are typically just mapped to raw disk blocks. A 360K floppy would have, basically, 360 Screens for code.
A Shadow Screen is where some range of Screens are considered code, and then another range, at a specific offset, are considered documentation. So, on a 360K floppy, you can see the first 180 screens being code, and the latter 180 being documentation. Screen 1 is code, screen 1 + 180 (181) is documentation.
The example above demonstrates this concept, with the code screen displayed alongside it’s shadow screen.
So, to the point, a nice affect of this is that you can look at the code simply as code. If you have any questions about the code, you can just pop over to the shadow screen and, ideally, get some more insight. its nice because the documenation can be expressive and general, or it can even be very specific (<-- THIS LINE HERE DOES XXX).
As a developer in Java, they like to document code with bodies of text as headers to the code. As a developer, if I’m using a code folding editor, I hide all of this. By this point, I’m editing, not learning, and the documentation is, literally (wait, did I say that?) in my way. I have to scroll/page through it all. It’s just bulky and in the way. If I’m not using a code folding editor, I’m just flat stuck scrolling.
The shadow screen concept is nice simply because the documentation is actually side by side the code, but not IN the code. It’s still limited, naturally, only so much you can do in a 64x16 character window. It would be interesting to see something akin to this for other code.