Noweb – A Simple, Extensible Tool for Literate Programming

Literate Programming is one of those ideas I keep coming to. There is an idea there that touches on something I find to be true about software development, namely that the communication of an idea to other humans is the most critical piece. There is a similar idea in Naur's paper "Programming as Theory Building."

That said, I've never loved the LaTeX-centric nature of most tools. I don't like heavier markup systems while I am writing prose, which is why I wrote SpiralWeb (https://github.com/michaeljmcd/spiralweb) as a Pandoc/Markdown centric tool.

Obligatory shilling of Org-babel, for those using Emacs and Org-mode: https://orgmode.org/worg/org-contrib/babel/

I found Mr. Ross' funnelweb utility to have the best syntax. Unique and easy to read.

http://ross.net/funnelweb/tutorial/index.html

Unfortunately the only known implementation was last updated over two decades ago, and is written in pretty hard to understand C.

I asked for permission and started a repository here: https://github.com/loa-in-/fw-utf8

I currently have it unmodified there, except for disabled check for ASCII range. (this modification is included in initial commit, sorry, my bad). Otherwise code is the same.

I am less convinced now after an initial period of enthusiasm. I can get around things locally fairly well with or without assistance. What takes effort to comprehend a code base is its overarching organization and internal interfaces that often only exist in the heads of the creators.

But if one is into literate programming it is definitely a must to check out the Leo Editor http://leoeditor.com

It's unfortunate that Funnelweb itself wasn't written in a literate style!

I've been using Org for a little over a year, and it's actually quite nice. To support a blog post last year (https://reindeereffect.github.io/2020/05/05/index.html) I did my own quick and dirty rendition of chunk labels, chunk chain navigation, and clickable references.

Lately I've built a faster, mostly drop-in replacement for org-babel-tangle (that doesn't unnecessarily clobber files that haven't changed); and I'm finishing up a more complete chunk formatter for HTML export, along with usable chunk index generation. Once that's done, I'll quit nerd sniping myself on literate programming systems for awhile and finish up a missive on programming a Turing machine to solve the Towers of Hanoi.

I keep meaning to experiment with bable/tangle in Emacs.

I setup a simple literate configuration of my init file via markdown, which worked out really well, but doing it "properly" in org-mode would be a nice evolution.

With markdown I just search for code-blocks, write them all sequentially to a temporary buffer and evaluate once done. So it is very simplistic, but also being able to write and group things is useful:

https://github.com/skx/dotfiles/blob/master/.emacs.d/init.md

I use a couple of Pandoc scripts to run code during the render of my Web site: http://chriswarbo.net/projects/activecode

I originally tried Emacs org-mode babel, but it didn't really fit the 'batch pipeline' flow I wanted.

For the record, I wrote portia[0], based on funnelweb and which accept a (mostly) compatible syntax, in a literate style. Its source/doc can be browsed [1].

I still use it from time to time, especially for small, well defined projects, because I find it useful to have to argue with myself when designing a software. It's not so much about producing a nice documentation or a proper exposition of some idea, than it is about having to formulate all the reasoning, the alternatives, and the choices.

[0]: https://github.com/rixed/portia [1]: http://rixed.github.io/portia/

Your project is just enough working (and up to spec!) that I might just restart my (100% compatible) funnelweb resurrection in literate format. Thank you!