Literate Programming: Articles
literateprogramming.com
Literate Programming: Articles
1–10 of 73 posts
Re: Literate Programming: Articles
#2That's ... a lot of articles. Is there any article in particular worth checking out?
Re: Literate Programming: Articles
#3That's ... a lot of articles. Is there any article in particular worth checking out?
Knuth's original article is a good starting point: http://literateprogramming.com/knuthweb.pdf.
Knuth's Programming Pearls entries are good reading as well.
Re: Literate Programming: Articles
#4[flagged]
Re: Literate Programming: Articles
#5I recently tried Literate Programming and I've found that it has some downsides not commonly discussed by its advocates. (It also has upsides which are valid, this post may come across as overly negative because I'm only covering negatives.)
* It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more advanced IDE-style features will work. Obviously tools could be adapted with custom plugins but literate programming isn't popular enough for these to already exist as far as I'm aware.
* It adds overhead to refactoring. Refactoring code now means editing and rewriting a book, doing a good job requires significantly more effort. If you have designed the program thoroughly ahead of time you can avoid this, but that's not generally the way most programmers work.
* The "includes" problem. Most language require you to include/import/require packages used in a file. These are usually all placed at the start. This means a lot of chapters will start with "here are all the includes we'll need" if you're using a linear format. More complex formats that rearrange the code to generate outputs can do a better job but it's still a little clunky.
Overall my conclusion was that literate programming works best if you write code like Donald Knuth: work solo, have a good idea of the entire design and a fixed scope which you can complete to declare both book and program "done forever". Unfortunately that doesn't cover most real world programming. I don't think it works well in the most common commercial/programming team style settings.
Re: Literate Programming: Articles
#6[flagged]
I wrote a literate programming preprocessor in Haskell[0], and used it to weave/tangle a D-Bus implementation (also in Haskell). The woven PDF[1] weighs in around 90 pages.
I'll quote from the linked page regarding my conclusions:
------------>8----------
But in the end, I was never able to realize the promised benefits of Literate Programming. The typeset PDF was not easier to read than hypertext documentation generated by Haddock, and both were obviously worse than the very nice docs being created by the Python community with Sphinx.
So in mid 2012 (~3 years after starting the project) I removed all the literate annotations and styles, dropped the fancy build scripts, and released haskell-dbus 0.10 as standard Haskell.
------------>8----------
I'm sure an expert in LaTeX could do a better job with the formatting, and with the benefit of 10 additional years of experience there are some design decisions I would do differently in the code, but even so I think it was a reasonably effortful attempt.
I've never felt any urge to try Literate Programming again.
[0] https://john-millikin.com/software/anansi#history
[1] https://github.com/jmillikin/haskell-dbus/releases/download/...
Re: Literate Programming: Articles
#7[flagged]
I have often thought about implementing a simple Makefile alternative in a literate style. Almost like an executable README.md. This way you can describe the project and the ways to interact with it in a much more readable way than a Makefile.
Re: Literate Programming: Articles
#8[flagged]
I wrote a literate programming preprocessor in Haskell[0], and used it to weave/tangle a D-Bus implementation (also in Haskell). The woven PDF[1] weighs in around 90 pages. I'll quote from the linked page regarding my conclusions: ------------>8---------- But in the end, I was never able to realize the promised benefits of Literate Programming. The typeset PDF was not easier to read than hypertext documentation gener…
Cute fleurons.
Re: Literate Programming: Articles
#9That's ... a lot of articles. Is there any article in particular worth checking out?
Knuth's original article is a good starting point: http://literateprogramming.com/knuthweb.pdf . Knuth's Programming Pearls entries are good reading as well.
Yeah I have read the original Literate Programming text and played with tangle/weave a bit before realising jupyter notebooks were more suitable for what I was doing. I'm just wondering if there is something in particular the submitter wanted to highlight, or whether they just wanted to share the concept of "Literate Programming" in general
Re: Literate Programming: Articles
#10It might be nice if modern languages defined an official way to "flip" the interpretation of a source file, so that by default the content is treated as markdown and the code goes in fenced blocks (rather than defaulting to code and providing a way to mark comment blocks).
Then we might hope for support in most tooling to appear quite quickly.
I think one reason why literate programming is less attractive nowadays (compared to the days of Pascal) is that programming languages have got better at letting you arrange your code in whatever way you like. So maybe something like the above is enough to get 90% of the advantages of a full literate programming system.