Literate Programming in Quarto
5 comments
·February 9, 2025WillAdams
I am a big believer in Literate Programming, and for a long while, the most expedient way for me to do it was to just use a .dtx (documented TeX file), since it allowed me to work with a straight-forward toolchain (a TeX editor/previewer such as TeXshop or TeXworks) --- adding Peter Wilson's docmfp package (https://ctan.org/pkg/docmfp) made it general-purpose enough for my needs, but I didn't like the sea of grey of the entire document being a comment in the editor.
I looked around and considered other tools, and Quarto was in the running, but it didn't seem straight-forward to get it to support multiple languages (my current project began in OpenSCAD, migrated to Python, and still maintains an OpenSCAD wrapper, as well as needing to write out G-code and DXFs).
Wound up asking how to do this w/ LuaLaTeX and got a very helpful answer:
https://tex.stackexchange.com/questions/722886/how-to-write-...
which I used to create a package which suits my needs, despite some serious drawbacks/failings (the .sty file _and_ .tex file have to be edited when a new file is added (or an old one removed), line numbering has to be managed manually, and I haven't puzzled out a seamless way to manage the Markdown file for readme.md).
Curious what other folks use/how they approach this sort of thing, so glad of this thread.
goosedragons
I've been using Org mode, more specifically org-babel. The only real downside of org mode is that it is Emacs exclusive. But it's very powerful and supports multiple languages. Lots more options than Quarto/Rmarkdown/Sweave which I have tried previously.
WillAdams
While, for a while I was using the emacs shortcuts in Apple's text object, I don't use my Mac enough for that to have stuck, and I find emacs itself intimidating, though I have great respect for the folks who can make the lifestyle commitment to use it (one programmer I knew launched it at the beginning of the day and never left it) --- gave away a copy of the emacs lisp programming book I received as a gift.
fjfaase
I developed something for C that just works in github markdown files, but without place holders. It just parses all the fragments, possibly from multiple files, and puts them in an order to be compiled. It does automatically generate forward declarations for functions. The generated C output does contain #line lines. I used this in the past years for AoC.
The article doesn't mention a key aspect of literate programming: publishing a code chunk at a different point in the document than where it is executed. This is possible in Quarto and should probably be added to that article for completeness. An answer on [stack overflow](https://stackoverflow.com/questions/76278117/how-to-achieve-...) explains how to do so.