I’ve written a fairly long literate program in Literate: https://blog.zdsmith.com/whist.html I really enjoyed the experience. It came out well and it was relatively painless to compose.
It extends https://github.com/bashup/mdsh so that you can execute shell code, embedded in markdown, on remote servers. I hope someday that documented server management becomes the standard.
It won't ever take off because it's not universally applicable - no one wants to write a CRUD web app as a literate program, for example. Most developers don't want to write any more words than they really have to: just try getting your average developer to write some actual documentation - it's a struggle! (Of course there are some developers who want to write books - but it's a tiny, tiny minority.)
Literate programming will remain an interesting and fun little niche, but I don't think it'll ever get any further than that: it's destined always to be a bit of an academic exercise. (Just so I don't sound like a terribly negative cynic, I have written a couple of literate programs and really enjoyed it.)
Please show a "hello world" script in your readme demonstrating the core feature of your tool. I skimmed the whole big readme and couldn't find any example of an actual literate script. Nor could I find any "examples" dir in the repo.
I like the idea, but I think I'd prefer to go more towards mdsh - I already write up markdown documents for various tasks - I would prefer extracting and running code directly from file (eg: a local checkout of a gitlab wiki project, or from a docs-folder in a checkout of a regular project).
Maybe I can bend mdsh to my needs with a bit of inspiration from your project.
Currently there's expected to be a bit of copy paste from the wiki/rendered markdown - but that only scales so far. (I generally do drop helper scripts in a project /bin folder, and document the use of those via markdown - but having a sensible way to execute code blocks would maybe help).
It depends on the system as there are different levels.
1. Promote comments above code. So the syntax for comments is the default. A simple notion is a markdown file where the process to create the program is to concatenate all the code blocks in order of appearance. Everything else is irrelevant to the code generated, but relevant to the developer. The idea here is to just promote communication of the reasons why and basic philosophy that leads to the code. The what should largely be easily readable from well-written code, but the reason for this choice versus that choice is what the comments want.
2. Reorder code. So each code block has a name and can be inserted in other code blocks. Order is irrelevant. This allows one to have, say, conditional logic easily readable without the actual code in between being executed. Functions can serve this purpose too, but the advantage of this style is that one can see the woven code together and read it as a whole in addition to this separated version. It helps prevent functions from being used purely as a reordering mechanism and to have functions being used only when its features are truly needed, such as repeatedly calling the same code. This allows for an in-between of avoiding copy-and-paste and avoiding unnecessary function calls (too many can lead to bouncing all over the place to see what is actually being executed).
The first two together is what is generally taken to be the mains of literate programming. This third one, however, is what I love about it.
3. Arbitrarily changing the code bits before insertion. This allows a lot of little DSL applications, easily inserting code from one language into another (e.g., writing markdown that converts into HTML that is embedded in a JS render function). This can also be used to do copy-paste-modify on a programmatic level. I often find this step to be one just before making an actual function, but somehow it helps me step through it all more easily.
4. Arbitrarily arranging inputs and outputs. Basically, write code entirely the way you (or your team, but probably just you) want to write it. If you want HTML, JS, and CSS all located together in functional units but put into separate files, no problem. If you want them coded in separate files but them brought into one HTML file, no problem. You want to manage configuration, installation, compiling, ..., no problem. You can write these files all separately, together, in pieces of relevance, etc. The danger is of course that your preferred style will not match others, but the hope of the original comment before code will allow people to follow. Essentially, you can read a top-level project management file that tells you where to look for all the other bits and it is faithful because this is how the system is being created.
---
A system that I created that does all of that is https://github.com/jostylr/literate-programming It does work and I tweak every now and then, but it certainly is not in an ideal state. It is a npm installable command line program and there is a 10% written book linked to from the README (free to read on Leanpub in HTML style). Almost every command is documented in there, but just barely.
It is a markdown-based tool. I had experimented with creating a different tool called pieceful-programming which would allow for changing the basic literate style (say instead of markdown, using asciidoc). But I did not complete it (yet?).
I used my tool for web programming, allowing me to freely arrange backend and frontend code as I see fit.
[+] [-] crux|5 years ago|reply
[+] [-] jsyedidia|5 years ago|reply
[+] [-] schaefer|5 years ago|reply
[+] [-] thaumaturgy|5 years ago|reply
A couple of months ago I released a "literate devops" tool: https://github.com/robsheldon/golem/
It extends https://github.com/bashup/mdsh so that you can execute shell code, embedded in markdown, on remote servers. I hope someday that documented server management becomes the standard.
[+] [-] bshimmin|5 years ago|reply
Literate programming will remain an interesting and fun little niche, but I don't think it'll ever get any further than that: it's destined always to be a bit of an academic exercise. (Just so I don't sound like a terribly negative cynic, I have written a couple of literate programs and really enjoyed it.)
[+] [-] akavel|5 years ago|reply
[+] [-] e12e|5 years ago|reply
Maybe I can bend mdsh to my needs with a bit of inspiration from your project.
Currently there's expected to be a bit of copy paste from the wiki/rendered markdown - but that only scales so far. (I generally do drop helper scripts in a project /bin folder, and document the use of those via markdown - but having a sensible way to execute code blocks would maybe help).
Ed: Or perhaps I'm better off just using https://zyedidia.github.io/literate/index.html directly.
[+] [-] brudgers|5 years ago|reply
[+] [-] johtela|5 years ago|reply
There is also a VSCode syntax highlighting extension https://marketplace.visualstudio.com/items?itemName=johtela....
[+] [-] cableclasper|5 years ago|reply
[+] [-] daly|5 years ago|reply
https://www.youtube.com/watch?v=mDlzE9yy1mk
[+] [-] mzs|5 years ago|reply
[+] [-] rpmuller|5 years ago|reply
[+] [-] sieste|5 years ago|reply
[+] [-] cableclasper|5 years ago|reply
[+] [-] wrycoder|5 years ago|reply
and the source can be read here
404
[+] [-] cableclasper|5 years ago|reply
[+] [-] tom_d999|5 years ago|reply
[+] [-] jostylr|5 years ago|reply
1. Promote comments above code. So the syntax for comments is the default. A simple notion is a markdown file where the process to create the program is to concatenate all the code blocks in order of appearance. Everything else is irrelevant to the code generated, but relevant to the developer. The idea here is to just promote communication of the reasons why and basic philosophy that leads to the code. The what should largely be easily readable from well-written code, but the reason for this choice versus that choice is what the comments want.
2. Reorder code. So each code block has a name and can be inserted in other code blocks. Order is irrelevant. This allows one to have, say, conditional logic easily readable without the actual code in between being executed. Functions can serve this purpose too, but the advantage of this style is that one can see the woven code together and read it as a whole in addition to this separated version. It helps prevent functions from being used purely as a reordering mechanism and to have functions being used only when its features are truly needed, such as repeatedly calling the same code. This allows for an in-between of avoiding copy-and-paste and avoiding unnecessary function calls (too many can lead to bouncing all over the place to see what is actually being executed).
The first two together is what is generally taken to be the mains of literate programming. This third one, however, is what I love about it.
3. Arbitrarily changing the code bits before insertion. This allows a lot of little DSL applications, easily inserting code from one language into another (e.g., writing markdown that converts into HTML that is embedded in a JS render function). This can also be used to do copy-paste-modify on a programmatic level. I often find this step to be one just before making an actual function, but somehow it helps me step through it all more easily.
4. Arbitrarily arranging inputs and outputs. Basically, write code entirely the way you (or your team, but probably just you) want to write it. If you want HTML, JS, and CSS all located together in functional units but put into separate files, no problem. If you want them coded in separate files but them brought into one HTML file, no problem. You want to manage configuration, installation, compiling, ..., no problem. You can write these files all separately, together, in pieces of relevance, etc. The danger is of course that your preferred style will not match others, but the hope of the original comment before code will allow people to follow. Essentially, you can read a top-level project management file that tells you where to look for all the other bits and it is faithful because this is how the system is being created.
--- A system that I created that does all of that is https://github.com/jostylr/literate-programming It does work and I tweak every now and then, but it certainly is not in an ideal state. It is a npm installable command line program and there is a 10% written book linked to from the README (free to read on Leanpub in HTML style). Almost every command is documented in there, but just barely.
It is a markdown-based tool. I had experimented with creating a different tool called pieceful-programming which would allow for changing the basic literate style (say instead of markdown, using asciidoc). But I did not complete it (yet?).
I used my tool for web programming, allowing me to freely arrange backend and frontend code as I see fit.