alt Hacker NewsCouple things that helped me understand literate programming:
- A literate program has code and documentation interleaved in one file.
- Weaving means extracting documentation and turning it into e.g. a pdf.
- Tangling means extracting code in a form that is understandable to a compiler.
A crucial thing to actually make this paradigm useful is the ability to change around the order of your code snippets, i.e. not letting the compiler dictate order. This enables you to code top-down/bottom-up how ever you see fit, like the article mentioned. My guess on why people soured on literate programming is that their first introduction involved using tools that didn't have this ability (e.g. jupyter notebooks). Also, you usually lose a lot of IDE features: no go-to-definition, bad auto-complete, etc.
IMO, the best tool that qualifies for proper literate programming is probably org-mode with org-babel. It's programming language agnostic, supports syntax highlighting and noWEB for changing around order. Of course it requires getting into the Emacs ecosystem, so it's destined to stay obscure.
Replies
I’d guess that tools like Doxygen and Apple docc are probably the most obvious examples of documentation extraction.
I’ve written code for many years, with Doxygen/Jazzy/docc in mind (still do[0]). I feel that it’s a big help.
>> A literate program has code and documentation interleaved in one file.
>> - Weaving means extracting documentation and turning it into e.g. a pdf.
>> - Tangling means extracting code in a form that is understandable to a compiler.
Interesting. i have made a few times DomainSpecific-"languages" - like for chips-module-testing , or for HR-payroll stuff - expressed in some general language with an engine underneath, which allowed for both turning/rendering the DS-"code" into various machine-readable outputs - verilog, labview, .. - as well as various documentation formats. Essentially a self-contained code-piece-with-execution/s-and-documentation/s, with the feature to "explain" what goes on, change-by-change.
Never knew it might be called literate programming.