3 ms·
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 chan
by Chris_Newton 2y ago
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.
- jll29 2y agoApart 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.
- Chris_Newton 2y agoThanks. 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 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).
- WillAdams 2y agoOne 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.
- tincholio 2y agoI'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.
- WillAdams 2y agoI'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.
- Chris_Newton 2y agoIt 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.
- WillAdams 2y agoI use section markers/Xrefs to help with that.