[dwohnitmok]

Are there any large (> 5 people teams) projects written with literate programming?

Also are there any IDE plugins or error stack trace/debuggers for literate programming?

I haven't really paid attention to literate programming in a long long time and I'm curious if the field has advanced.

(Also I don't understand this: "A typical literate file produces many source files." Why? Why would you care about having multiple source files? Isn't the literate file the source at this point?)

[guitarbill]

I worked on a larger project where some of the code was "literate" programming. It was an absolute pain to modify anything. Debugging, not so much, since tangle produces raw source code. This you can work with. The problem is working with the original files.

Syntax highlighting? Good luck! But possibly you could work around this, e.g. via custom highlighting syntax. Same with any auto-complete, contextual IDE help, etc. Refactoring was painful.

Also, the text absolutely destroys being able to scan and reason about the control flow quickly. Especially bad when a dev decides something needs "a lot of documentation" and writes a small novel.

Needless to say, it was truly awful.

[flukus]

IMHO the two biggest problems I find with existing tools are that they assume the documentation is the source of truth and that the tangling will leave artifacts in code. Both of these make them poorly suited to the sort of projects that most of us work on, I'm not Knuth writing a dead tree tome but I would like some better ways to add documentation to existing projects and have to integrate with others.

I wrote a PoC of a tangling tool that worked through "virtual" files and had a syntax aware handler, there's enough information that it could possible work with language servers too, but sadly I haven't had time to take things further: https://gitlab.com/lusher/tanglemd

[ParetoOptimal]

> they assume the documentation is the source of truth and that the tangling will leave artifacts in code.

Leo avoids this by keeping a "shadow copy" of the artifacts or annotations and doing a diff on detangling between all 3 versions.

[k__]

"Also are there any IDE plugins or error stack trace/debuggers for literate programming?"

Good question!

I always think it would be nice to just write Markdown sprinkled with code, but without IDE/editor support, it's dead in the water :(

[Yaina]

I mean rust supports markdown comments and can compile them into documentation.[1] That's pretty good in my book in terms of documentation.

[1]https://doc.rust-lang.org/rust-by-example/meta/doc.html

[k__]

I wouldn't call it good. But better than nothing, I guess.

[Yaina]

I think it's as good as it gets. The rough principal is there: You have one file, and you can derive the documentation and the program from it with different compilers.

The idea of reading code like a book seems extremely flawed to me, and any attempts to create such languages either look like regular source code with slightly different syntax or are barely comprehensible (e.g. TeX)

[db48x]

Have you actually read TeX: The Book? It is far from “extremely flawed”.

[wrycoder]

Or another Knuth book, The Stanford Graph Base?

Early C compilers, prior to prototypes, were rigid about the order of the various functions and includes, and that interfered with the exposition of the design. Literate programming was created by Knuth to address that.

[Yaina]

Well, I have neither read through the entire 500 pages of tex.pdf[1] nor the 25k lines of tex.web[2], but I certainly have an impression of both.

I think it is very hard to comprehend what one single part of a given algorithm does and it's imho almost impossible to get a good picture of how all these pieces fit together.

[1] https://texdoc.org/serve/tex.pdf/0 [2] https://mirror.las.iastate.edu/tex-archive/systems/knuth/dis...

[k__]

I liked the idea of literate CoffeeScript.

It was basically Markdown and when executed, all but the code blocks was removed.

Made for a pretty nice file structure.

[goosedragons]

R-studio supports this for R although you can sprinkle in other languages although they are 2nd class citizens unsurprisingly. Emacs has org-mode with babel that combined with poly-mode gets you every feature you'd expect in the major mode of the language you're writing in. Emacs also supports R-markdown/Sweave quite well.

[k__]

Ah, yes I played around with R-studio last year.

Pretty nice experience.

[ParetoOptimal]

We need a polished debugger using robust detangling and source maps for literate programming.

[goosedragons]

You might still want multiple tangled files to follow a familiar app structure, or for languages that need to be compiled or if you don't want users to have to add the extra step of tangling the source before they build your program.