38 ms·

Literate programming is a thing that's long piqued my interest, but it usually seems more suited to academic or personal use. Having said that, a beautiful exa

Literate programming is a thing that's long piqued my interest, but it usually seems more suited to academic or personal use. Having said that, a beautiful example of LP in the wild is geom[0], a Clojure/Clojurescript library written entirely in org-mode. Browsing through the source, I have to keep reminding myself that I'm looking at the code and not just the documentation. [0] https://github.com/thi-ng/geom https://github.com/thi-ng/geom

vog 10y ago
I see that this is a honorable goal, but in this particular project the source looks more like source than documentation. An extreme example is this part, where the code even contains function docstrings, rather than having the docstring as part of the surrounding document: https://github.com/thi-ng/geom/blob/master/geom-core/src/matrix.org#view-matrix-generation https://github.com/thi-ng/geom/blob/master/geom-core/src/mat... This is an effect which I observed with my own literate programming attempts, too: They quickly end up with large documents that contain lots of code listings and not much explaination.
- toxmeister 10y ago
  Author here: Agreed & most parts of this particular project aren't really the best example. With other (newer) projects I embraced the LP style much more, and in fact by now really often first write the prose parts to get my head clear about a certain aspect and only then start writing code, e.g. https://github.com/thi-ng/fabric/blob/master/fabric-facts/src/dsl.org https://github.com/thi-ng/fabric/blob/master/fabric-facts/sr... https://github.com/thi-ng/geom/blob/develop/src/viz/core.org https://github.com/thi-ng/geom/blob/develop/src/viz/core.org As for the docstrings included in the core, this is largely to address complains from other users, who are used to have docs available in the REPL and I often don't have the resources/time to provide both org-mode and docstrings...
616c 10y ago
I have wanted to try this for so long. Doing my own short articles is one thing, but to see something as complex as 2D/3D voxel libraries in Clj/Cljs is very inspiring. My only concern for such things is what to do with non-org loving, neigh, Emacs-hating users? This can be generalized to all literate programming tools. I assume beyond the humble, it kills adoption. The maintainer of Axiom did a good talk that got me into my penultimate LP kick, but this is always thing missing from such impassioned talks for it. UPDATE: Axiom, dear 616c, not Maxima. Someone even links it in another thread to boot.

vog 10y ago

I see that this is a honorable goal, but in this particular project the source looks more like source than documentation. An extreme example is this part, where the code even contains function docstrings, rather than having the docstring as part of the surrounding document: https://github.com/thi-ng/geom/blob/master/geom-core/src/matrix.org#view-matrix-generation https://github.com/thi-ng/geom/blob/master/geom-core/src/mat... This is an effect which I observed with my own literate programming attempts, too: They quickly end up with large documents that contain lots of code listings and not much explaination.

toxmeister 10y ago
Author here: Agreed & most parts of this particular project aren't really the best example. With other (newer) projects I embraced the LP style much more, and in fact by now really often first write the prose parts to get my head clear about a certain aspect and only then start writing code, e.g. https://github.com/thi-ng/fabric/blob/master/fabric-facts/src/dsl.org https://github.com/thi-ng/fabric/blob/master/fabric-facts/sr... https://github.com/thi-ng/geom/blob/develop/src/viz/core.org https://github.com/thi-ng/geom/blob/develop/src/viz/core.org As for the docstrings included in the core, this is largely to address complains from other users, who are used to have docs available in the REPL and I often don't have the resources/time to provide both org-mode and docstrings...

616c 10y ago

I have wanted to try this for so long. Doing my own short articles is one thing, but to see something as complex as 2D/3D voxel libraries in Clj/Cljs is very inspiring. My only concern for such things is what to do with non-org loving, neigh, Emacs-hating users? This can be generalized to all literate programming tools. I assume beyond the humble, it kills adoption. The maintainer of Axiom did a good talk that got me into my penultimate LP kick, but this is always thing missing from such impassioned talks for it. UPDATE: Axiom, dear 616c, not Maxima. Someone even links it in another thread to boot.