Skip to content

Topic: Literate Programming

Literate Programming is the practice of flipping the importance of comments and code. Suddenly, your documentation has main stage and your code is nestled throughout. There's a rich history, with nice niche words - but suffice to say it emphasizes explanation of your thought process and makes a project intimately documentation-first without too much trouble in your tooling.

One of my favourite tools has been lit1. I've been using it to keep my nvim configuration understandable as it grows and shifts and I've already found it invaluable a few times. It's a great tool which is entirely language agnostic - it will support any language and it's possible to set your editor up to highlight languages within code fences with ease. A major downside, in my opinion, is that it doesn't support markdown directly. It's nearly markdown, so the literate source can't simply be included in sites like this.

  • Literate Programming in Purescript
    • After looking for some literate programming software specific to PureScript, I found literate-purescript1. I found no way to build it without it erroring out, and I'm not comfortable with purescript dependencies to go digging just yet (plus, this was a Sunday - didn't want dependency management stress). After some hunting in the issues[^2] of the project, I found one of the users had published a version on npm as paluh-litps. A little npx later, and this worked just fine.
  • Notes

  1. ~zyedidia/literate ↩↩