Hacker News Reader

Comment by WillAdams | Hacker News Reader

Have you considered/looked at Literate Programming?

With a bit of help on tex.stackexchange.com I managed to put together a system which allows editing a .tex file (without the docstrip mandated almost everything is a comment greyness):

https://tex.stackexchange.com/questions/722886/how-to-write-...

View on HN

Yes, I wrote some literate Haskell professionally a few years back. I think it’s an interesting and useful concept. In my experience, it also fundamentally changed the way I read and wrote code, with both pros and cons.

What I’m advocating here is a little different, though. While it would certainly be useful to write documentation using more expressive formats than plain text, here I’m arguing for the ability to (a) attach that documentation to specific parts of the code at different scales and then (b) have all relevant information at all scales readily available depending on what I’m currently editing.

One of the reasons I would like to have this ability in my development environment is that I found the literate style to be very helpful for writing informative documentation but relatively unhelpful for finding it again later. By its nature, literate documentation is organised primarily for a linear reading flow, like the story in a book, but most of the time when I’m editing code, that’s not my typical searching behaviour.

Apart from Donald Knuth, you are the first person that I heard from who used literate programming professionally. Would be great to learn more from your experiences, good and bad, if you every fancy writing about it.

Thanks. We did discuss this on HN a few years ago and I added a few comments, starting here:

https://news.ycombinator.com/item?id=12048693

I continued to work on that project for a while afterwards, but I don’t think my overall views on the pros and cons of the literate style changed much from what I wrote there.

If there’s anything you’re particularly curious about, I’m happy to discuss further (though my professional experience was limited to that one project, so I’m hardly an expert).

One thing which might help with "scannability" is to have a toggle in the LaTeX code which changes it from focusing on displaying the document as a typeset whole to showing only the typeset code. A possible way to do this would be change the width of the page so that the text lines are so wide each paragraph would only be a single line, then you could set the PDF view to only be the width of the widest code line at the left edge.

I've also used it fairly extensively, both in academia and in industry jobs (using Emacs org-mode, with several target languages, often combined). I found it very useful when thinking through a problem, and as documentation for myself later on. At some point it starts to become a bit unwieldy. Nowadays, most of my work is in Clojure, and I find that the literate workflow gets in the way of REPL-driven development, so I haven't been using it as much lately.

Overall, I'd highly recommend it.

I've found that having a hyper-linked ToC and index and having the marginal callouts of module and variable names helps a great deal in finding code again.

It wasn’t so much the code that I found less discoverable with the literate style, more the relevant documentation when reading any given part of the code. I found the linear flow didn’t really lend itself to quickly finding all relevant commentary about any given piece of code, since it tends to encourage building up a “big picture” and so there could easily be comments much earlier in any given chapter/file that were relevant to later code but with no obvious way to know that and find them short of reading the whole thing from front to back.

I use section markers/Xrefs to help with that.

My issue with LP is that common tools don't support it directly.

I'm generally against metaprogramming and DSLs for that reason, the linter and the debugger don't understand it. Even template languages have the issue, which is a great case for logicless templates.

Seems like LP would be at it's best if your audience is going to read and carefully study your code without a bunch of extra stuff added, as is probably more common in academia, rather than see it indirectly through an IDE.

Reply on news.ycombinator.com