Hi all, this is my first post here. Ever since I saw this literate programming talk I have been messing with existing literate programming tools. After trying multiple tools, I ended up writing my own tool using python + sphinx + cog + markdown. I am calling it wheel.
Because of cog - I believe literate programming can enable many interesting things like arbitrary preprocessing and code generation instead of just mangle and tangle. In plannr I have experimented with adding some syntax to hylang, a dialect of lisp. I think literate programming is criss-cross programming 🙂 and enables feature driven development. I have documented my findings here https://xyzzyapps.link/wheel/why.html
Would love to hear you guys think!
Links
1. Wheel - a literate programming tool with python + sphinx + cog + markdown.
My main app Plannr (currently beta) and the literate documentation for it. Source code inside the documentation.
My music making app Bitrhythm and its documentation
I find my self nodding a lot reading through it: https://xyzzyapps.link/wheel/why.html
I briefly looked through the “Code Walkthrough” of Plannr to get a better understanding. I wonder how you can get different perspectives on code besides chapters and pages.
Thinking in books: I understand that there is a table of contents and a linear flow through the book. There are also links. Is there also some sort of Appendix, Glossary or other forms of organization possible? For example, I found a couple of code snippets called “Websocket Reply Handlers” that contained message types and handlers. I could imagine an index of all those that link to their implementation. Would that be possible / how would you set this up?
In the original implementation cweb extensive cross referencing capabilities are provided but yes there could be other perspectives on chapters. You can get cross references with this tool. My current notion is 1 chapter = 1 use case or 1 complete feature with backend, frontend and tests.
Thanks! I really find this whole idea super interesting. I’ve been keeping a written log of my programming progress with notes about features, implementations and screenshots. But linking that with actual code would be interesting. I believe a lot of challenges from coding comes from the lack of Organisation and verbalisation. And as described here, files/folders aren’t enough and seem to be rather hacks. I like that in Processing (.org), you can create “tabs” when a single code file gets too long. You create a tab inside the IDE but that tab isn’t a new file that you need to import. It is just a new “snippet” that will be appended together with the other tabs. I wonder: is Observable another example of literate programming? https://observablehq.com — I do have to say that your examples are better, because they have a table of contents! 🙂 In general I think that lists, maps, and other designed forms of access to code are really needed in contrast to just files, folders and naming conventions.
I haven’t used observable but I have used python notebooks. I think nbdev comes close to literate programming. The difference lies in the flexibility of organisation and arbitrary reordering. In literate programming you define chunks that can be reused wherever you want, whether in docs or code. If observable provides a named block that can be referenced and embedded anywhere then it gets close. I would emphasise that this is production code, not just examples which blogs and notebooks are typically used for! Personally I find literate programming for noting down 1. todo’s 2. bugs 3. bookmarks 4, design decisions and history 5. build commands 6. tests