Source code: https://github.com/ZoomTen/nailit
Example using its own source: https://zoomten.github.io/nailit/
This is a minimal tool for literate programming, a way of programming that seems to best be described as "pretend you're writing a tutorial on how to write your program".
And by that I mean literate programming in a Knuthian sense, in that you can write your program in the order that makes most sense to a reader and then the tool can process it into something that can actually compile. This is in contrast to the more modern definition using e.g. Jupyter notebooks where each code block is self-contained and usually meant to be run one after another, but most importantly cannot actually reference one another. (runnableExamples seems to be a different thing entirely)
Knuth's literate programming concept remains interesting to me even when it's impractical for me to maintain such a program (generally due to not meshing well with syntax highlighters and language tooling). I have written at least one guide with this concept and I had fun doing it. (though, I still don't know whether or not it's actually helpful to people)
Similar tools I already know of for this sort of thing:
Reasons I wrote my own tool even though it's less capable than those other ones:
I originally contemplated plainly using nimlit as the program's name, but I thought: Nah, I don't think I want to give people the wrong idea that it can only be used with Nim though it is written in it :p
Nice work! Literate programming for sure is underrated (at least for _certain types of programs)!
In my view (from a physicists perspective) it's especially well suited to explanatory (or exploratory if one has a good idea already) documents. E.g. a document describing some calculation or doing some simulation, where the code might even only be an addition for the interested reader.
Other tools you should be aware of:
Going at it from a different direction by using Nim source files as the main 'literate document' with special code blocks is nimib:
https://github.com/pietroppeter/nimib/
Examples here:
or here:
https://github.com/SciNim/getting-started/ (source files)
https://scinim.github.io/getting-started/ (produced)
Emacs' Org mode is (in my biased opinion) still the best tool for literate programming. Although it is of course best suited to be used with Emacs, which limits accessibility quite a bit of course.
Examples of mine for literate documents using Nim and Org mode (the Org file links just link to the raw documents):
http://files.vindaar.de/phd/docs/bufferGasIAXO/v1/axionMass.html (produced HTML)
http://files.vindaar.de/phd/docs/bufferGasIAXO/v1/axionMass.org (Org file)
http://files.vindaar.de/phd/docs/SolarAxionConversionPoint/axion_conversion_point.html (produced HTML)
http://files.vindaar.de/phd/docs/SolarAxionConversionPoint/axion_conversion_point.org (Org file)
(And well, my PhD thesis can be considered a massive literate programming document, lol)
Note that there is ntangle,
https://github.com/OrgTangle/ntangle
a simple Nim tool to tangle code snippets from Org files without using Emacs.
I think I've heard of those! And yeah… while orgmode from what I've seen is useful for basically everything, you're right, I'm not an Emacs user :)
(Nimib(ook) is really cool though)
And those tools—as I understand it—don't really let you order your code in any other way other than in a straight linear fashion, as if you are writing just code. I do see that ntangle has plans at least for noweb-style references, which would actually make that possible.
I think it just goes to show that the "notebook" style is far more practical than the method that was originally proposed back in the 80s, especially with it playing heavily on interactivity (output directly beneath the code and such), which is more exciting than passively reading code.
Perhaps it's valid as well—after all, does it matter what it is if at the end readers understand what the code is doing?
I have yet to try Leo though…
Hi, cool to see a new tool for literate programming, it looks very nice, congrats!
Thanks @Vindaar for sharing info about Nimib. Me and @hugogranstrom are being very quiet in the forum but we are progressing on various fronts (with the usual slowness) and we have a number of interesting things going on (we also report about those in our monthly speaking hours for those cuorious). Hopefully they will reach a more "shareable" point in the future.
Inspired by the tool I made a new post that implements an out of order api for nimib: https://nimib.land/nblog/drafts/out_of_order.html
I could see (with more effort and macros) how an api and output like the one in NailIt could be replicated in Nimib, but I would defintely not the one doing it (and it might not even be a good idea, NailIt looks nice as it is!).