6 ms·

I think it's clear to everyone that Knuth's style of literate programming didn't achieve any sort of mainstream adoption. However, this article doesn't mention

I think it's clear to everyone that Knuth's style of literate programming didn't achieve any sort of mainstream adoption. However, this article doesn't mention a newer form of literate programming that has gone mainstream. Notebooks! Whether it's jupyter, colab, whatever the Julia one is called, etc. People use literate programming all the time for data science and machine learning.

rustnote 5y ago
People dismiss modern notebooks as Knuth's style of literate programming, where they are more for exploring and documenting an existing codebase or just experimenting. So people are often arguing over two completely different things. I love notebooks, made VS Code extensions for Go (gobook) and for Rust (rustnote). Give them a try if anyone is interested, still lots of features to add, but the source code is standard markdown, so the code results can be saved straight to Github and they render there.
- deleted 5y ago
  [deleted]
- iddan 5y ago
  That is amazing! Have you considered creating a notebook for TypeScript? I saw Microsoft created an extension but never cared to publish it: https://github.com/microsoft/vscode-nodebook https://github.com/microsoft/vscode-nodebook
  - fault1 5y ago
    how about https://github.com/winnekes/itypescript https://github.com/winnekes/itypescript (also obserablejs) for a different take on it. I have a feeling notebooks are not as popular for javascript since it's quite limiting relative to what a code sandbox can do.
  - jackosdev 5y ago
    Yeah I have, I'm just focusing on getting the Rust language server working first which is quite tricky, then I'll be adding other languages.
nefitty 5y ago
ObservableHQ changed my life. Coding is fun again. I use it to quickly experiment with new libraries, fast prototypes, as proof of concept building, NLP stuff, etc. And I can do it all on my phone!
- mbo 5y ago
  Observable's evaluation model confers a big advantage too - you're free to write the prose and define constants, variables and imports in any order you like. Multiple times have I been able to write some prose that reads well, but forces things to be defined in an order that is not the same as its evaluation order. And if I don't want anyone to see some code, I stuff it at the end of the notebook (often imports). That aside, I completely agree - Observable has brought back a lot of the joy of programming I had when I first started. Congratulations to Bostock and the team.
jarenmf 5y ago
Aren't modern notebooks a form of Knuth's style literate programming, are there any differences? True, they are more mainstream in analytics where there's a need to explain concepts/results more than the logic of the code itself.
- marcos100 5y ago
  Knuth's style allows code to be written in any order using named chunks. AFAIK, there are some types of notebooks that allow the use of chunks, but I've never seen people writing in those.
  - disgruntledphd2 5y ago
    Org babel is the only one that works well, tbh.
- amelius 5y ago
  Modern notebooks are closer to Stephen Wolfram's Mathematica notebooks.
- andreareina 5y ago
  Implied by arbitrary chunk order, chunks don't need to be stand-alone (or even syntactically valid, but that's probably asking for trouble): int main(int argc, char **argv) { <<main-parse-argv>> // ... }
d0mine 5y ago
Org Babel can be useful for explorative programming (emacs-jupyter), devops-y stuff: more permanent than REPL but less structured, more fluid compared to the usual code practices.
davidgrenier 5y ago
Yes, my productive editor becomes useless with that kind of file content.
- sdfgsdf 5y ago
  I just want to point out that Jupyter and ipynb are separate things. ipynb files are shit, but Jupyter doesn't have to be. For example, VS Code supports Jupyter without ipynb. This way you can end up with files which, unlike ipynb, are valid in the target language (e.g. python, julia) AND play nice with git, but are still interactive thanks to Jupyter. In fact, the above realization - that there are IDEs that support Jupyter without ipynb - has been the biggest boost to my productivity in 2021. This came in the form of being able to version my interactive jupyter files.
  - jonnycomputer 5y ago
    I did not know that. I may have to revise my opinion.
    - sdfgsdf 5y ago
      Read this, thank me later https://code.visualstudio.com/docs/python/jupyter-support-py https://code.visualstudio.com/docs/python/jupyter-support-py
zelphirkalt 5y ago
To me as an org mode and org babel user, notebooks seem to be a very half-assed form or literate programming for the following reasons: (1) No linking from on cell to another. A sequential execution is assumed or otherwise you need to manually run cells in different order. There might be extensions to help with that. It is not out of the box though. (2) The documentation language is markdown This does not allow for great technical documents with arbitrary links to arbitrary other parts in the document or inside another notebook. ReStructuredText would have that using link sources and link sinks. org mode can also link to parts in other documents. (3) I cannot include other notebooks to have it all exported as one whole document or notebook as I can in org mode. In org mode I can even specify at what level some heading should be imported. (4) The editor in notebooks is not that great compared to any IDE or normal code editor or Emacs. (5) In a typical JupyterLab environment there is only one programming language per notebook. I know there are other kinds JupyterLab environments, which allow for multiple langs inside the same notebook. (6) The base format of notebooms is JSON instead of plain text like in org mode. This means diffs are harder to read and version control. Again you need extra tooling for dealing with it well (which does exist). The literate programming stuff of notebooks has all long been there before notebooks came into existence. It is not like that was the advent of a new form of literate programming. In JupyterLab environments it would take lots of fumbling and tweaking to get something comparable to org + org babel.
- funklute 5y ago
  R notebooks (which are not jupyter-based) addresses (to varying degrees) issues 3-6. But then you are of course stuck inside the R ecosystem, where only Rstudio and emacs are what I would consider fully mature editors. As a casual rather than power user, I especially dislike the JSON format of jupyter notebooks.
  - jonnycomputer 5y ago
    For all the popularity of Jupyter notebooks, I never did understand the appeal. I agree that R notebooks and Emac's org-mode are far more sensible ways of doing things. Not perfect, by any means, but sensible.
sdfgsdf 5y ago
> Whether it's jupyter, colab, whatever the Julia one is called, etc The Julia one is called jupyter. Jupyter stands for Julia, Python, TeX and R.
- leephillips 5y ago
  In fact Jupyter is just a mashup of Julia, Python, and R (no TeX). The commenter may have been thinking of Pluto¹, which is Julia-only but a big improvement over Jupyter. 1 ‘An introduction to pluto’. LWN. Available from: https://lwn.net/Articles/835930/
  - fault1 5y ago
    yes, jupyter is more or less a generalization of ipython, which has been around since 2001. the notebook aspects and language agnostic parts were split off to target python-like languages (julia and R), while ipython became a python kernel for jupyter (like irkernel and ijulia).
- eigenspace 5y ago
  You are of course correct, but 'the Julia one' is probably actually Pluto, since it's Julia only.
gnlpyx 5y ago
These are entirely different things. Literate programming tells you what the code does in large code bases and why it is correct. Notebooks are used for small snippets, many of them trivial. The comments usually tell you what the buggy snippet is supposed to to. They are more like Powerpoint.
tpoacher 5y ago
In my view, notebooks are the exact opposite of literate programming, and it's a shame some people seem to think it is its pinnacle instead. The focus on a notebook is the report, not the code. In practice this means that the report structure dictates code structure, not the other way round. By contrast, the focus of literate programming is the code. Any "reporting" done is strictly to enhance the code, and not the other way round. I've seen far too many codebases that should have been "code generating a report" reverse that logic and implemented as notebooks instead, in the expectation that the underlying code can simply be exported from the report. Good luck if you need to work on someone's code of that kind. It's its own special kind of hell.
Zababa 5y ago
On the other hand, I think the main point of literate programming was to make programs easier to maintain, and I constantly hear about the big gap between developping a notebook and pushing the code into production. Notebooks feels more like an answer to how to quickly experiment rather than how to make knowledge last.
hzhou321 5y ago
The mistake of Knuth is instead of "Literate Programming", he made it, or at least let most people take it, into "Literate + Programming". Depend on which part you focus on, it is either "code" with copious amount of "document", or "document" with verifiable "code". Many "literate" programs are in fact the former. The modern "Notebooks" are the latter*. Neither is "Literate Programming". With "literate Programming", it is one product, the program! Ideally, it is just readable code, code that human can read literally. Since human mind works differently from computer, so the literate programming environment need transform the literate code into a form that compiler can optimize. I believe this idea is inside Knuth's LP. But early attempt is always limited by technology. For example, Knuth's system is based on token parser. Token is not the unit of comprehension for human. Thus he can't do much with the Pascal part other than "tangling" the code as is. Then he had to supplement his goal with English or "document". But if we start to develop the framework beyond "tangle", we'll see a new page in literate programming. * The "Notebooks" (the noun) implies we are emphasizing the product as documents. However, nothing prevent people to use "Notebooks" to program. Then immediately one will see how limited it is. "Notebooks" does not "tangle" code. Really, there is not much you can do with the code part. For example, try use the "Notebook" form on a C program.
deleted 5y ago
[deleted]
benhurmarcel 5y ago
> whatever the Julia one is called https://github.com/fonsp/Pluto.jl https://github.com/fonsp/Pluto.jl

rustnote 5y ago

People dismiss modern notebooks as Knuth's style of literate programming, where they are more for exploring and documenting an existing codebase or just experimenting. So people are often arguing over two completely different things. I love notebooks, made VS Code extensions for Go (gobook) and for Rust (rustnote). Give them a try if anyone is interested, still lots of features to add, but the source code is standard markdown, so the code results can be saved straight to Github and they render there.

deleted 5y ago
[deleted]
iddan 5y ago
That is amazing! Have you considered creating a notebook for TypeScript? I saw Microsoft created an extension but never cared to publish it: https://github.com/microsoft/vscode-nodebook https://github.com/microsoft/vscode-nodebook
- fault1 5y ago
  how about https://github.com/winnekes/itypescript https://github.com/winnekes/itypescript (also obserablejs) for a different take on it. I have a feeling notebooks are not as popular for javascript since it's quite limiting relative to what a code sandbox can do.
- jackosdev 5y ago
  Yeah I have, I'm just focusing on getting the Rust language server working first which is quite tricky, then I'll be adding other languages.

nefitty 5y ago

ObservableHQ changed my life. Coding is fun again. I use it to quickly experiment with new libraries, fast prototypes, as proof of concept building, NLP stuff, etc. And I can do it all on my phone!

mbo 5y ago
Observable's evaluation model confers a big advantage too - you're free to write the prose and define constants, variables and imports in any order you like. Multiple times have I been able to write some prose that reads well, but forces things to be defined in an order that is not the same as its evaluation order. And if I don't want anyone to see some code, I stuff it at the end of the notebook (often imports). That aside, I completely agree - Observable has brought back a lot of the joy of programming I had when I first started. Congratulations to Bostock and the team.

jarenmf 5y ago

Aren't modern notebooks a form of Knuth's style literate programming, are there any differences? True, they are more mainstream in analytics where there's a need to explain concepts/results more than the logic of the code itself.

marcos100 5y ago
Knuth's style allows code to be written in any order using named chunks. AFAIK, there are some types of notebooks that allow the use of chunks, but I've never seen people writing in those.
- disgruntledphd2 5y ago
  Org babel is the only one that works well, tbh.
amelius 5y ago
Modern notebooks are closer to Stephen Wolfram's Mathematica notebooks.
andreareina 5y ago
Implied by arbitrary chunk order, chunks don't need to be stand-alone (or even syntactically valid, but that's probably asking for trouble): int main(int argc, char **argv) { <<main-parse-argv>> // ... }

d0mine 5y ago

Org Babel can be useful for explorative programming (emacs-jupyter), devops-y stuff: more permanent than REPL but less structured, more fluid compared to the usual code practices.

davidgrenier 5y ago

Yes, my productive editor becomes useless with that kind of file content.

sdfgsdf 5y ago
I just want to point out that Jupyter and ipynb are separate things. ipynb files are shit, but Jupyter doesn't have to be. For example, VS Code supports Jupyter without ipynb. This way you can end up with files which, unlike ipynb, are valid in the target language (e.g. python, julia) AND play nice with git, but are still interactive thanks to Jupyter. In fact, the above realization - that there are IDEs that support Jupyter without ipynb - has been the biggest boost to my productivity in 2021. This came in the form of being able to version my interactive jupyter files.
- jonnycomputer 5y ago
  I did not know that. I may have to revise my opinion.
  - sdfgsdf 5y ago
    Read this, thank me later https://code.visualstudio.com/docs/python/jupyter-support-py https://code.visualstudio.com/docs/python/jupyter-support-py

zelphirkalt 5y ago

To me as an org mode and org babel user, notebooks seem to be a very half-assed form or literate programming for the following reasons: (1) No linking from on cell to another. A sequential execution is assumed or otherwise you need to manually run cells in different order. There might be extensions to help with that. It is not out of the box though. (2) The documentation language is markdown This does not allow for great technical documents with arbitrary links to arbitrary other parts in the document or inside another notebook. ReStructuredText would have that using link sources and link sinks. org mode can also link to parts in other documents. (3) I cannot include other notebooks to have it all exported as one whole document or notebook as I can in org mode. In org mode I can even specify at what level some heading should be imported. (4) The editor in notebooks is not that great compared to any IDE or normal code editor or Emacs. (5) In a typical JupyterLab environment there is only one programming language per notebook. I know there are other kinds JupyterLab environments, which allow for multiple langs inside the same notebook. (6) The base format of notebooms is JSON instead of plain text like in org mode. This means diffs are harder to read and version control. Again you need extra tooling for dealing with it well (which does exist). The literate programming stuff of notebooks has all long been there before notebooks came into existence. It is not like that was the advent of a new form of literate programming. In JupyterLab environments it would take lots of fumbling and tweaking to get something comparable to org + org babel.

funklute 5y ago
R notebooks (which are not jupyter-based) addresses (to varying degrees) issues 3-6. But then you are of course stuck inside the R ecosystem, where only Rstudio and emacs are what I would consider fully mature editors. As a casual rather than power user, I especially dislike the JSON format of jupyter notebooks.
- jonnycomputer 5y ago
  For all the popularity of Jupyter notebooks, I never did understand the appeal. I agree that R notebooks and Emac's org-mode are far more sensible ways of doing things. Not perfect, by any means, but sensible.

sdfgsdf 5y ago

> Whether it's jupyter, colab, whatever the Julia one is called, etc The Julia one is called jupyter. Jupyter stands for Julia, Python, TeX and R.

leephillips 5y ago
In fact Jupyter is just a mashup of Julia, Python, and R (no TeX). The commenter may have been thinking of Pluto¹, which is Julia-only but a big improvement over Jupyter. 1 ‘An introduction to pluto’. LWN. Available from: https://lwn.net/Articles/835930/
- fault1 5y ago
  yes, jupyter is more or less a generalization of ipython, which has been around since 2001. the notebook aspects and language agnostic parts were split off to target python-like languages (julia and R), while ipython became a python kernel for jupyter (like irkernel and ijulia).
eigenspace 5y ago
You are of course correct, but 'the Julia one' is probably actually Pluto, since it's Julia only.

gnlpyx 5y ago

These are entirely different things. Literate programming tells you what the code does in large code bases and why it is correct. Notebooks are used for small snippets, many of them trivial. The comments usually tell you what the buggy snippet is supposed to to. They are more like Powerpoint.

tpoacher 5y ago

In my view, notebooks are the exact opposite of literate programming, and it's a shame some people seem to think it is its pinnacle instead. The focus on a notebook is the report, not the code. In practice this means that the report structure dictates code structure, not the other way round. By contrast, the focus of literate programming is the code. Any "reporting" done is strictly to enhance the code, and not the other way round. I've seen far too many codebases that should have been "code generating a report" reverse that logic and implemented as notebooks instead, in the expectation that the underlying code can simply be exported from the report. Good luck if you need to work on someone's code of that kind. It's its own special kind of hell.

Zababa 5y ago

On the other hand, I think the main point of literate programming was to make programs easier to maintain, and I constantly hear about the big gap between developping a notebook and pushing the code into production. Notebooks feels more like an answer to how to quickly experiment rather than how to make knowledge last.

hzhou321 5y ago

The mistake of Knuth is instead of "Literate Programming", he made it, or at least let most people take it, into "Literate + Programming". Depend on which part you focus on, it is either "code" with copious amount of "document", or "document" with verifiable "code". Many "literate" programs are in fact the former. The modern "Notebooks" are the latter*. Neither is "Literate Programming". With "literate Programming", it is one product, the program! Ideally, it is just readable code, code that human can read literally. Since human mind works differently from computer, so the literate programming environment need transform the literate code into a form that compiler can optimize. I believe this idea is inside Knuth's LP. But early attempt is always limited by technology. For example, Knuth's system is based on token parser. Token is not the unit of comprehension for human. Thus he can't do much with the Pascal part other than "tangling" the code as is. Then he had to supplement his goal with English or "document". But if we start to develop the framework beyond "tangle", we'll see a new page in literate programming. * The "Notebooks" (the noun) implies we are emphasizing the product as documents. However, nothing prevent people to use "Notebooks" to program. Then immediately one will see how limited it is. "Notebooks" does not "tangle" code. Really, there is not much you can do with the code part. For example, try use the "Notebook" form on a C program.

deleted 5y ago

[deleted]

benhurmarcel 5y ago

> whatever the Julia one is called https://github.com/fonsp/Pluto.jl https://github.com/fonsp/Pluto.jl