4 ms·

I've been thinking a lot about literate programming, and I'm positive that Knuth-style LP's worst enemy is TeX. Realistically, an LP system is going to need to

by cxr 5y ago

I've been thinking a lot about literate programming, and I'm positive that Knuth-style LP's worst enemy is TeX. Realistically, an LP system is going to need to prioritize the reading experience of the input format itself, not just the output format after running it through a typesetting system (no matter how powerful the typesetting system might be). Consider Gruber on Markdown, and this 2014 blog post about (what became) CommonMark: > A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions (Gruber)[...] forks of Markdown, such as GitHub Flavored Markdown and MultiMarkdown extend standard Markdown in various ways, and are targeted for their particular use cases. GitHub’s implementation for code blocks, for example, looks like something a group of programmers would want to have; it looks more like code than text <http://shindoisshin.net/blog/2014/9/6/standard-markdown-controversy http://shindoisshin.net/blog/2014/9/6/standard-markdown-cont...> Consider this file. Those who are expected to interact with it in this form includes Knuth and his collaborators—the few who have sent in corrections—and nobody else. You aren't expected to read a literate program like this. In an ideal world, where we had computing better figured out, Knuth wouldn't interact with it like this, either. The second thing to address would be the use of "static" target languages like C and Pascal. A literate programming work should aim to be more like the experience of programming by configuring program entities (I hesitate to say "objects")—like Self, except powered by the written word. Among the negative ways to react to the last remark would be to say, "'Self, except powered by the written word'? So pretty much the opposite of Self, then. Basically, what we already have." But this is too superficial. Consider Jef Raskin on "the woes of IDEs": <https://queue.acm.org/detail.cfm?id=864034 https://queue.acm.org/detail.cfm?id=864034>

svat 5y ago
I actually agree with your main point — in fact I would go further and say that in an ideal LP system, the (or at least a) source format would just simply be valid files in the target language, with any LP-related markup or whatever in the comments. The reason is so that LP programs can get contributions from "mainstream" programmers. (It's ok if the LP users have an alternative format they can write in, as long as edits to the source file can be incorporated back.) So the following correction is not intended as disagreement but simply to share some history / facts: > Consider this file. Those who are expected to interact with it in this form […] You aren't expected to read a literate program like this. In an ideal world, where we had computing better figured out, Knuth wouldn't interact with it like this, either. Actually, even in the world we live in, no one is expected to read a literate program like this (Knuth has comments to that effect somewhere), and everyone is "supposed" to read the typeset program (today that would be tex.pdf or whatever). Knuth reads it off the printed book. He navigates the program using the indexes in the book, and as recently as this year he raved about how good his system was (https://tug.org/TUGboat/tb42-1/tb130knuth-tuneup21.pdf https://tug.org/TUGboat/tb42-1/tb130knuth-tuneup21.pdf): > While I was preparing this round of updates, I was overjoyed to see how well the philosophy of literate programming has facilitated everything. This multifaceted program was written 40 years ago, yet I could still get back into TeX’s darkest corners without trouble, just by rereading [B] and using its index and mini-indexes! I can’t help but ascribe most of TeX’s success to the fact that it has enabled literate programming. This works for him, because he started programming in the days when program "listings"—printouts of source code—were the most common way to read programs, and it's also how he wrote TeX (https://news.ycombinator.com/item?id=10172924 https://news.ycombinator.com/item?id=10172924: “Knuth wrote the entirety of the first version of TeX on yellow legal note pads, and then typed it all in, and then started debugging” — he worked full-time on the program, writing it with pencil on paper, over several months, before typing a single word of it into a computer). And of course, he's a professional book-reader and book-writer (and book-tweaker, as his books keep getting newer editions and updates), so it comes naturally to him.
- cxr 5y ago
  > Actually, even in the world we live in, no one is expected to read a literate program like this (Knuth has comments to that effect somewhere), and everyone is "supposed" to read the typeset program (today that would be tex.pdf or whatever). Sorry if it wasn't clear, but that was the point that I was making. The file that susam has linked to here is nominally "plain" "text", but no reader is expected to consume it in this form, or really interact with it in this form at all. This form serves exactly one set of humans: Knuth, et al, and only while they are actively editing it. To reiterate my earlier claim: a more perfect LP system would be designed in such a way that the plain text input format would be a suitable way to read programs written in that system. (And when I say "suitable", I don't merely mean "possible". I mean designed expressly for that purpose, like how Markdown was _intended_ to be used before the GitHub contingency got their hands on it.) > LP-related markup or whatever in the comments That's sort of the opposite of what I'm after! Please do check the Raskin article I linked to.
  - svat 5y ago
    Ah I see, thanks for clarifying. I had missed the subtle distinction in your comment between "interact with" and "read": I treated them as synonymous, when in fact you were referring to the interaction that is confined to actively editing (i.e., for Knuth, "typing up" the edits he has already made on paper). About the more perfect LP system, I agree it would be nice if the input format was designed to be the suitable way to read programs: in other words, there would be no "weave" step. [Aside: should this input format be plain text? Maybe notebooks like Wolfram's or "nbdev" count?] The idea of having the markup in the comments is instead related to eliminating the "tangle" step. (I think there are some LP-related tools that do this; one I know is Harold Thimbleby's "warp": http://www.harold.thimbleby.net/cv/files/warp.pdf http://www.harold.thimbleby.net/cv/files/warp.pdf — but the structured comments are in (ugh) XML. See also Visual Studio's XML comments…. He also has a later "relit" that does "reverse" LP, extracting source code out of the intended-for-publication format.) (These goals are indeed sort of opposites, but can be reconciled: I guess we can agree that the ultimate would be a format that eliminated both the tangle and weave steps!) (My reason for wishing eliminating the "tangle" step (and/or enabling going back from the tangled document to the LP input format) is simply an acknowledgement of network effects: LP is unlikely to ever catch on enough to be the majority, so there needs to be a way for a random programmer using their preferred IDE/editor to edit a "literate" program without getting too annoyed.) I read Raskin's article and it has good complaints about IDEs, and (although I don't see a close connection) I think I understand what you're suggesting as the ideal language/programming environment. But for me, because of the "LP will never be mainstream" belief, I'm still thinking of targeting mainstream languages, with "code" and "comments". :-) Anyway, this part from Raskin's article is particularly inspiring and quotable: > …the result was very readable and maintainable. To achieve this, we had regular code-reading sessions in which one programmer read and commented on each piece of code written by another programmer. In addition, an expert documenter/writer worked alongside the programmers. If he did not understand a piece of code, he would interview the programmers until he could write a cogent explanation. > Incidentally, many bugs and conceptual errors were discovered during this process, which more than paid for itself in decreased debugging time. Some programmers balked at the procedures at first, but all came to be enthusiastic when the project did not slow or founder as completion neared. The project was on time, on budget, and bugless (meaning that the software was released commercially to tens of thousands of users and produced no bug reports).
JasonFruit 5y ago
I'm with you up to that last paragraph, and wonder if I would agree with you more there if you explained what you mean by "powered by the written word."
- cxr 5y ago
  Okay. First, the establishing shot: Literate programming envisions programs as texts meant to be read in the same vein as other texts like, say, a book of historical non-fiction or long-from narrative journalism. It goes without saying, but the written word is the basis for any work in this form. Second establishing shot: Self and Smalltalk are notoriously image-based systems. You grab hold of objects and then configure them, relying on point-and-click for much of it. Some aspects of these systems will by their nature be exposed in part as text, e.g. textual representation of methods, but you're still interacting with live objects. I'll assume that you're familiar with this, but for completeness including for the benefit of those who aren't, consider the way the way the CSS style sidebar in your favorite browser's Web developer tools work. Only now imagine that instead of just using it for debugging and tweaks, suppose when you needed to make a permanent edit to the style sheet on your homepage, you opened up the CSS viewer, made the edit, and the result persists—not just in your browser, but by changing the very style sheet itself. Here's David Ungar on this experience (around 1 hour in): > I try to explain to people that the notion of compiler is broken. Of course I learned this from Smalltalk, but what we want to build is experiences—artificial realities that convince you that your source code is real. It's directly executed. There's no lag between editing and running[...] The environment stresses things in your program, not tools—which is another rant I have. It's this whole idea that we want to put you in an artificial reality—I got that from Randy [Smith]—in which it's easy and natural and low-cognitive-burden to get the computer to do what you want it to do, rather than running language translators that turn weird strings of text into bits the machine can run <https://vimeo.com/594563690 https://vimeo.com/594563690> Now I want to attack the traditional experience by doing the opposite and leaning in on the text part. The point-and-click part of object configuration in Self and Smalltalk is not readily reproducible (hence the proliferation of image-based designs for runtime implementations), and texts deliberately designed for consumption are pretty robust as far as transmission goes with respect to both physical transmission as well as a matter of transmission of knowledge—one of the best ways to "get up to speed" on something is to have someone just tell you about it. A good LP system would work the way Self and Smalltalk do, but with the point-and-click eliminated. Interactive object configuration should be replaced by written exposition. Despite mainstream programming being overwhelmingly text-based, none of them really work this way. (After all, if being text-based were sufficient, then there would be no meaningful difference between mainstream filed-and-compiled source code vs LP systems.) I suppose what I'm advocating for could be thought of as object-oriented literate programming, as treacherous and unfashionable as the term OO is. Neither REPLs nor notebooks really capture this in the right way, being rooted still too far away from LP and and more akin to traditional programming, but it's a start. I'm sure that interactive fiction could contribute something here, but with the open sourcing of Inform7 being two years overdue (and itself being implemented in C++), there's a dearth widely available prior art.
plafl 5y ago
I think the main problem with LP is philosophical: it is used so you can deeply understand the whole program but most people want to understand a part and ignore the rest. So for example extracting how Tex renders math equations is almost impossible without understanding the whole (some people kindly did this and published a paper using SML). This actually is related to your comment because it's impossible to "navigate" or to "debug" the code, or at least I'm unaware of how could it be done in a simple way (that is, with existing tooling) and so if you want to learn how Tex is written you must proceed page by page of "TeX: The Program" instead of randomly jumping through code, hacking here and there. It's like learning mathematics axiom by axiom. I personally find it unproductive as learning for me is highly non sequential. If knowledge is a graph of concepts I want to explore as I wish, not following another's predefined serialization.
- JasonFruit 5y ago
  I've found literate programming helps in one main situation: where I am writing and want to force myself to very thoroughly think through a difficult and self-contained section of code that has to be understood as a whole. In that case, the narrative format makes me much less likely to overlook edge cases, and I find it easier to go back in and make changes later on. I wouldn't ever write a larger system in that way, but on that scale it's like working with a metronome in music: it's a form of discipline that produces almost magical results.
- svat 5y ago
  I agree with this: I found it very hard, at least until I got a good sense of the overall structure and conventions etc, to be able to understand just one part and ignore the rest. On the other hand, ironically, Knuth recommended getting familiar with the program by picking up one particular part and "navigating" the program to study just that part. (See https://youtu.be/D1jhVMx5lLo?t=4103 https://youtu.be/D1jhVMx5lLo?t=4103 at 1:08:25, transcribed a bit at https://shreevatsa.net/tex/program/videos/s04/ https://shreevatsa.net/tex/program/videos/s04/) He seems to find using the index (at the back of the book, and on each two-page spread in the book) to be a really convenient way of "navigate" the program (and indeed randomly jumping through code, as you said), and he thinks that one of the convenient things about the "web" format is that you can explore it the way you want. This is really strange (to us) as the affordances we're used to from IDEs / code browsers etc are really not there, but it makes a bit of sense when you consider that books are Knuth's life, and he must find things like flipping pages with a bookmark in the index page at the back of the book etc really second-nature. (BTW if you know someone who has the super-obscure interest in making WEB programs actually navigable with hyperlinks etc, do consider https://github.com/shreevatsa/webWEB/discussions https://github.com/shreevatsa/webWEB/discussions or if you know some better way of finding such people let me know :P)
e12e 5y ago
I think one "unfortunate" side effect of literate programming with a "stupid" procedual language like C, Pascal or even Java - is that your lp system tends toward becoming your macro system. It does allow straightforward, short procedual/structured programs to become very readable and easily understandable - but for bigger "piles of code" - it's probably not that good a fit in practice. I guess https://github.com/daly/axiom https://github.com/daly/axiom is both an argument for this being true (I seem to recall there was an effort to get away from lp) - and against (proof of existence: it's a big system, it's old, it seems to not be dead). Then there's the other thing - I don't recall who's quote it is - but it is along the lines of: "There are few good programmers, there are few good writers of prose/technical documentation - therefore the subset of people that are both great programmers and great writers are tiny - and that is the subset for whom literate programming is a great fit". I do think there's a middle ground though, and "notebooks" for "executable, repeatable" research papers is one such middle ground (or: to write a great cs paper your team need to have both skills anyway). But there are certainly great programmers that can't write documentation on how to escape a wet paper bag.

by cxr 5y ago

svat 5y ago

I actually agree with your main point — in fact I would go further and say that in an ideal LP system, the (or at least a) source format would just simply be valid files in the target language, with any LP-related markup or whatever in the comments. The reason is so that LP programs can get contributions from "mainstream" programmers. (It's ok if the LP users have an alternative format they can write in, as long as edits to the source file can be incorporated back.) So the following correction is not intended as disagreement but simply to share some history / facts: > Consider this file. Those who are expected to interact with it in this form […] You aren't expected to read a literate program like this. In an ideal world, where we had computing better figured out, Knuth wouldn't interact with it like this, either. Actually, even in the world we live in, no one is expected to read a literate program like this (Knuth has comments to that effect somewhere), and everyone is "supposed" to read the typeset program (today that would be tex.pdf or whatever). Knuth reads it off the printed book. He navigates the program using the indexes in the book, and as recently as this year he raved about how good his system was (https://tug.org/TUGboat/tb42-1/tb130knuth-tuneup21.pdf https://tug.org/TUGboat/tb42-1/tb130knuth-tuneup21.pdf): > While I was preparing this round of updates, I was overjoyed to see how well the philosophy of literate programming has facilitated everything. This multifaceted program was written 40 years ago, yet I could still get back into TeX’s darkest corners without trouble, just by rereading [B] and using its index and mini-indexes! I can’t help but ascribe most of TeX’s success to the fact that it has enabled literate programming. This works for him, because he started programming in the days when program "listings"—printouts of source code—were the most common way to read programs, and it's also how he wrote TeX (https://news.ycombinator.com/item?id=10172924 https://news.ycombinator.com/item?id=10172924: “Knuth wrote the entirety of the first version of TeX on yellow legal note pads, and then typed it all in, and then started debugging” — he worked full-time on the program, writing it with pencil on paper, over several months, before typing a single word of it into a computer). And of course, he's a professional book-reader and book-writer (and book-tweaker, as his books keep getting newer editions and updates), so it comes naturally to him.

cxr 5y ago
> Actually, even in the world we live in, no one is expected to read a literate program like this (Knuth has comments to that effect somewhere), and everyone is "supposed" to read the typeset program (today that would be tex.pdf or whatever). Sorry if it wasn't clear, but that was the point that I was making. The file that susam has linked to here is nominally "plain" "text", but no reader is expected to consume it in this form, or really interact with it in this form at all. This form serves exactly one set of humans: Knuth, et al, and only while they are actively editing it. To reiterate my earlier claim: a more perfect LP system would be designed in such a way that the plain text input format would be a suitable way to read programs written in that system. (And when I say "suitable", I don't merely mean "possible". I mean designed expressly for that purpose, like how Markdown was _intended_ to be used before the GitHub contingency got their hands on it.) > LP-related markup or whatever in the comments That's sort of the opposite of what I'm after! Please do check the Raskin article I linked to.
- svat 5y ago
  Ah I see, thanks for clarifying. I had missed the subtle distinction in your comment between "interact with" and "read": I treated them as synonymous, when in fact you were referring to the interaction that is confined to actively editing (i.e., for Knuth, "typing up" the edits he has already made on paper). About the more perfect LP system, I agree it would be nice if the input format was designed to be the suitable way to read programs: in other words, there would be no "weave" step. [Aside: should this input format be plain text? Maybe notebooks like Wolfram's or "nbdev" count?] The idea of having the markup in the comments is instead related to eliminating the "tangle" step. (I think there are some LP-related tools that do this; one I know is Harold Thimbleby's "warp": http://www.harold.thimbleby.net/cv/files/warp.pdf http://www.harold.thimbleby.net/cv/files/warp.pdf — but the structured comments are in (ugh) XML. See also Visual Studio's XML comments…. He also has a later "relit" that does "reverse" LP, extracting source code out of the intended-for-publication format.) (These goals are indeed sort of opposites, but can be reconciled: I guess we can agree that the ultimate would be a format that eliminated both the tangle and weave steps!) (My reason for wishing eliminating the "tangle" step (and/or enabling going back from the tangled document to the LP input format) is simply an acknowledgement of network effects: LP is unlikely to ever catch on enough to be the majority, so there needs to be a way for a random programmer using their preferred IDE/editor to edit a "literate" program without getting too annoyed.) I read Raskin's article and it has good complaints about IDEs, and (although I don't see a close connection) I think I understand what you're suggesting as the ideal language/programming environment. But for me, because of the "LP will never be mainstream" belief, I'm still thinking of targeting mainstream languages, with "code" and "comments". :-) Anyway, this part from Raskin's article is particularly inspiring and quotable: > …the result was very readable and maintainable. To achieve this, we had regular code-reading sessions in which one programmer read and commented on each piece of code written by another programmer. In addition, an expert documenter/writer worked alongside the programmers. If he did not understand a piece of code, he would interview the programmers until he could write a cogent explanation. > Incidentally, many bugs and conceptual errors were discovered during this process, which more than paid for itself in decreased debugging time. Some programmers balked at the procedures at first, but all came to be enthusiastic when the project did not slow or founder as completion neared. The project was on time, on budget, and bugless (meaning that the software was released commercially to tens of thousands of users and produced no bug reports).

JasonFruit 5y ago

I'm with you up to that last paragraph, and wonder if I would agree with you more there if you explained what you mean by "powered by the written word."

cxr 5y ago
Okay. First, the establishing shot: Literate programming envisions programs as texts meant to be read in the same vein as other texts like, say, a book of historical non-fiction or long-from narrative journalism. It goes without saying, but the written word is the basis for any work in this form. Second establishing shot: Self and Smalltalk are notoriously image-based systems. You grab hold of objects and then configure them, relying on point-and-click for much of it. Some aspects of these systems will by their nature be exposed in part as text, e.g. textual representation of methods, but you're still interacting with live objects. I'll assume that you're familiar with this, but for completeness including for the benefit of those who aren't, consider the way the way the CSS style sidebar in your favorite browser's Web developer tools work. Only now imagine that instead of just using it for debugging and tweaks, suppose when you needed to make a permanent edit to the style sheet on your homepage, you opened up the CSS viewer, made the edit, and the result persists—not just in your browser, but by changing the very style sheet itself. Here's David Ungar on this experience (around 1 hour in): > I try to explain to people that the notion of compiler is broken. Of course I learned this from Smalltalk, but what we want to build is experiences—artificial realities that convince you that your source code is real. It's directly executed. There's no lag between editing and running[...] The environment stresses things in your program, not tools—which is another rant I have. It's this whole idea that we want to put you in an artificial reality—I got that from Randy [Smith]—in which it's easy and natural and low-cognitive-burden to get the computer to do what you want it to do, rather than running language translators that turn weird strings of text into bits the machine can run <https://vimeo.com/594563690 https://vimeo.com/594563690> Now I want to attack the traditional experience by doing the opposite and leaning in on the text part. The point-and-click part of object configuration in Self and Smalltalk is not readily reproducible (hence the proliferation of image-based designs for runtime implementations), and texts deliberately designed for consumption are pretty robust as far as transmission goes with respect to both physical transmission as well as a matter of transmission of knowledge—one of the best ways to "get up to speed" on something is to have someone just tell you about it. A good LP system would work the way Self and Smalltalk do, but with the point-and-click eliminated. Interactive object configuration should be replaced by written exposition. Despite mainstream programming being overwhelmingly text-based, none of them really work this way. (After all, if being text-based were sufficient, then there would be no meaningful difference between mainstream filed-and-compiled source code vs LP systems.) I suppose what I'm advocating for could be thought of as object-oriented literate programming, as treacherous and unfashionable as the term OO is. Neither REPLs nor notebooks really capture this in the right way, being rooted still too far away from LP and and more akin to traditional programming, but it's a start. I'm sure that interactive fiction could contribute something here, but with the open sourcing of Inform7 being two years overdue (and itself being implemented in C++), there's a dearth widely available prior art.

plafl 5y ago

I think the main problem with LP is philosophical: it is used so you can deeply understand the whole program but most people want to understand a part and ignore the rest. So for example extracting how Tex renders math equations is almost impossible without understanding the whole (some people kindly did this and published a paper using SML). This actually is related to your comment because it's impossible to "navigate" or to "debug" the code, or at least I'm unaware of how could it be done in a simple way (that is, with existing tooling) and so if you want to learn how Tex is written you must proceed page by page of "TeX: The Program" instead of randomly jumping through code, hacking here and there. It's like learning mathematics axiom by axiom. I personally find it unproductive as learning for me is highly non sequential. If knowledge is a graph of concepts I want to explore as I wish, not following another's predefined serialization.

JasonFruit 5y ago
I've found literate programming helps in one main situation: where I am writing and want to force myself to very thoroughly think through a difficult and self-contained section of code that has to be understood as a whole. In that case, the narrative format makes me much less likely to overlook edge cases, and I find it easier to go back in and make changes later on. I wouldn't ever write a larger system in that way, but on that scale it's like working with a metronome in music: it's a form of discipline that produces almost magical results.
svat 5y ago
I agree with this: I found it very hard, at least until I got a good sense of the overall structure and conventions etc, to be able to understand just one part and ignore the rest. On the other hand, ironically, Knuth recommended getting familiar with the program by picking up one particular part and "navigating" the program to study just that part. (See https://youtu.be/D1jhVMx5lLo?t=4103 https://youtu.be/D1jhVMx5lLo?t=4103 at 1:08:25, transcribed a bit at https://shreevatsa.net/tex/program/videos/s04/ https://shreevatsa.net/tex/program/videos/s04/) He seems to find using the index (at the back of the book, and on each two-page spread in the book) to be a really convenient way of "navigate" the program (and indeed randomly jumping through code, as you said), and he thinks that one of the convenient things about the "web" format is that you can explore it the way you want. This is really strange (to us) as the affordances we're used to from IDEs / code browsers etc are really not there, but it makes a bit of sense when you consider that books are Knuth's life, and he must find things like flipping pages with a bookmark in the index page at the back of the book etc really second-nature. (BTW if you know someone who has the super-obscure interest in making WEB programs actually navigable with hyperlinks etc, do consider https://github.com/shreevatsa/webWEB/discussions https://github.com/shreevatsa/webWEB/discussions or if you know some better way of finding such people let me know :P)

e12e 5y ago

I think one "unfortunate" side effect of literate programming with a "stupid" procedual language like C, Pascal or even Java - is that your lp system tends toward becoming your macro system. It does allow straightforward, short procedual/structured programs to become very readable and easily understandable - but for bigger "piles of code" - it's probably not that good a fit in practice. I guess https://github.com/daly/axiom https://github.com/daly/axiom is both an argument for this being true (I seem to recall there was an effort to get away from lp) - and against (proof of existence: it's a big system, it's old, it seems to not be dead). Then there's the other thing - I don't recall who's quote it is - but it is along the lines of: "There are few good programmers, there are few good writers of prose/technical documentation - therefore the subset of people that are both great programmers and great writers are tiny - and that is the subset for whom literate programming is a great fit". I do think there's a middle ground though, and "notebooks" for "executable, repeatable" research papers is one such middle ground (or: to write a great cs paper your team need to have both skills anyway). But there are certainly great programmers that can't write documentation on how to escape a wet paper bag.