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 don't see any markdown in the script at the top, it looks like a normal bash script. It doesn't look in any way as "literate programming" as commonly understood since originally introduced. I'm in utterly confused how this example script is in any way related to what we're talking about in this thread, including your post above.
I wasn't snarking. Writing one or more markdown-specific examples is something I'd like to do. I was asking for ideas for examples that would be more useful to sysadmins than the shell example at the top of the readme.
No problem, I just assumed some kind of misunderstanding and tried to explain my thoughts in different words :) I'm afraid I don't have especially great ideas for that, nor am I a sysadmin. In fact, I was hoping to see some example of how you'd suggest to use the thing so that I would better understand it and get inspired :P hm, dunno, how about uploading my ssh public key to a remote machine? Just random idea of a thing commonly needed to be done.
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).
I started with "just use mdsh", but then found that executing mdsh scripts on remote servers was yucky; either the file needed to be copied up, executed, and then cleaned up, or the file was executed over ssh but that was fragile. It took a lot of tries to find a way to do it that didn't break bash or sudo or interactive prompts from remote programs.
I used that trick for a while, but it required the `--compile` option for mdsh, and re-compiling each script every time was silly. Also, I wanted shellcheck to look at the output each time to make sure something wasn't horribly broken before running some markdown on a server. (Other than the part where I'm running markdown on a remote server.)
So, I started caching the compiled files. Then I wanted a couple of convenience functions added to them. Then golem sort of happened.
It pretty much just takes mdsh and makes it safer and nicer to run on remotes.
Right. My use case is more to tweak and test a few scripts, then have a(nother| junior) dev(op) be able to clone a repo and set up a service or server.
Maybe with some minor obvious tweaks.
I've looked at ansible - but I'm not convinced that it's a good fit; ansible feels a bit like a padded straight jacket, rather than comfortable outwear, so to speak.
I need to weaponize my documentation, rather than dull the edge of my shell recepies ;)
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.
