I find it surprising that nobody talked about Jupyter so far. I still think that Jupyter is an overly simplified realisation of cweb's vision.
The CWEB System of Structured Documentation
11–16 of 16 posts
Re: The CWEB System of Structured Documentation
#12I studied CWEB when I did computer science in the early 1990s (eek!). While it is a way to document and compile your programs from a single file, it still contains the problem of where the story of a program should happen, and in keeping the documentation and code in line and up to date with each other. It should also be understood that the documentation is for other programmers and not users, since the printout of t…
I think that underlines a major point, though. CWEB is specifically to document the program for reading. It is not user documentation. It is not a design document of the intent of the system. It is documentation of the code, specifically. It can be difficult, because the assumption is emphatically not that the reader in unfamiliar with the target language. To that end, much of the code you find in CWEB will still be…
No you can combine both, which is the preferred way. As an example (although it does not use CWEB, but its own code) LaTeX's .docstrip/doc/dtx system does that. It generates the code, a driver and documentation both for code and user. It also produces an index automatically. You can use it to write your Javascript code if you want. As Wirth or maybe it was Hoare used to say code is literature as it is meant to be read by humans not only computers.
Re: The CWEB System of Structured Documentation
#13isn't the first problem of documentation is keeping it in sync with the source code? Time and time again people come up with "better ways of documentation" while neglecting this basic problem, what problem do they think they're solving?
Yes, but the closer the documentation is to the code, the easier it is to keep up-to-date. I've found anecdotally that other developers on my team readily update doc-comments when method signatures change, but update out-of-file documentation less readily (such as a markdown readme document).
Structuring the documentation as part-and-parcel of the code helps give the documentation a fighting chance of staying up-to-date over time given without requiring all developers on the team from being religious about updating docs (which I find I need to enforce at the PR stage for those repos with external readme files).
Re: The CWEB System of Structured Documentation
#14Earlier quoted context omitted.
I think that underlines a major point, though. CWEB is specifically to document the program for reading. It is not user documentation. It is not a design document of the intent of the system. It is documentation of the code, specifically. It can be difficult, because the assumption is emphatically not that the reader in unfamiliar with the target language. To that end, much of the code you find in CWEB will still be…
No you can combine both, which is the preferred way. As an example (although it does not use CWEB, but its own code) LaTeX's .docstrip/doc/dtx system does that. It generates the code, a driver and documentation both for code and user. It also produces an index automatically. You can use it to write your Javascript code if you want. As Wirth or maybe it was Hoare used to say code is literature as it is meant to be rea…
Fair. Though I think it is a safe to say that the intent is to document the software moreso than the use of it. Mainly going off of all of the programs on Knuth's homepage. TeX and METAFONT are both the same. The literate program is distinct from the user manuals.
Re: The CWEB System of Structured Documentation
#15Earlier quoted context omitted.
I think that underlines a major point, though. CWEB is specifically to document the program for reading. It is not user documentation. It is not a design document of the intent of the system. It is documentation of the code, specifically. It can be difficult, because the assumption is emphatically not that the reader in unfamiliar with the target language. To that end, much of the code you find in CWEB will still be…
Counter-example. Have used literate programming for a real-life freelance project a year ago. Am using it for both my private projects and current freelance projects. The manual can be broken down into four parts or volumes depending on size: I. User's Guide II. User's Reference Manual III. Maintainer's Guide IV. Maintainer's Reference Manual Don't get this wrong, updating the screenshots in the User's Guide is annoy…
[deleted]
Re: The CWEB System of Structured Documentation
#16CWEB spawned several other Literate Programming systems, the main differences being in programming languages supported as well as how the documentation was formatted. My favorite is nuweb https://nuweb.sourceforge.net/ which allows for LP in virtually any language and provides documentation in LaTeX. The main trade off being that with wide language support the code sections are as-is, without special formatting. Sinc…
I use Noweb https://www.cs.tufts.edu/~nr/noweb/>, which is, I believe, very much like nuweb. It is also LaTeX-centric, and also allows code sections to be written in any language. Within code sections, instead of depending on Noweb for code formatting, I use a syntax-aware editor. I configure Vim to recognize the language within each code section. This means that, in Vim, I get formatting and syntax highlighting.
Vim is also able to export syntax highlighted code as HTML markup. Because Noweb is modular and supports plugin filter stages, it might be possible to write a Noweb filter stage that calls Vim, translates the markup to LaTeX, and adds syntax highlighting to the document. This is something I haven't tried.