I was wondering if comments alongside source code are not read for reasons other than them being likely to be out of date. Maybe its because ... syntax highlighting makes them less readable?
Has anyone on here written any software using #LiterateProgramming? If yes, what tools did you use? Did they work well, and would you recommend them?
I've been fascinated by the concept ever since Inform 7 was released as open source, with its own literate programming toolset. @zarfeblong quotes, "...no one has yet volunteered to write a program using another's system for literate programming." https://blog.zarfhome.com/2022/04/inform-7-open-source-release.html
Did you write your own literate programming software?
“I'm on a roll”, as they say: v2.0 of #AsciidoctorLitProg is out, with improved default styling for woven output and —the most significant change— an overhaul of the system that outputs line numbering comment in the tangling phase.
For those unfamiliar with #LiterateProgramming, weaving is the production of human-readable documentation, and tangling the production of machine-readable source code.
One of the principles of #LiterateProgramming is that “source code is for compilers”: the order in which functions and data types are defined in the source code depends on how the compiler works rather than on how the developer thinks. In #LitProg, the pieces of course are written in whatever order the developer finds more fitting for their presentation, and “tangled” to produce the compiler-oriented source.
The obvious issue with this is that if the compiler or interpreter trips on an error in the source code, any file and line number information will refer to the tangled file rather than the #LiterateProgramming source. So during tangling we insert comments indicating where every piece of tangled source code comes from —which introduces problems when moving different languages in the same source file.
Probably the last stretch for today: v2.2 of #AsciidoctorLitProg, with a feature enhancement (runtime renaming of output files), and an important bugfix for when chunk names have <, & or > in them.
"Some explanations can, will, and should be written by code authors alone, or by those authors in partnership with LLMs. Others can, will, and should be conjured dynamically by code readers who ask LLMs for explanations on the fly."
Creative Commons is great for text. It's not great for code. Literate programming is both.
CC-BY-SA-4.0 is one-way compatible with GPL-3.0. License a whole doc as CC-BY-SA-4.0, and both are neatly covered. But if you include non-trivial GPL-3.0 code into your literate program (hello, Emacs!), the doc needs two licenses or one awkward one. And so many Emacs configs are GPL, it's hard to avoid.
More Rainbow code showing the Literate programming style it is designed to support. I usually don't do comments in Swift but Rainbow makes comments joyful and intrinsically part of the code page. Black denotes a comment word. More traditional languages make it very hard to add comments in-place like this so I tend to use intermediate variable names and small functions to explain my code in as declarative a way as possible. #Rainbow#FORTH#LiterateProgramming#ConcatenativeProgramming