NHacker Next
  • new
  • past
  • show
  • ask
  • show
  • jobs
  • submit
Literate: A Flexible Literate Programming System (zyedidia.github.io)
crux 1121 days ago [-]
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.
jsyedidia 1121 days ago [-]
Here's another long literate program that was written using Literate: https://justinmeiners.github.io/lc3-vm/
schaefer 1121 days ago [-]
Beautiful. Thank you for sharing.
e12e 1121 days ago [-]
Indeed, thank you for sharing this.
thaumaturgy 1121 days ago [-]
I've seen a few posts here recently on literate programming; I really hope it takes hold as a trend.

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 1121 days ago [-]
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.)

akavel 1121 days ago [-]
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.
thaumaturgy 1121 days ago [-]
An "examples" directory is a great idea that didn't occur to me at all.

Do you have a suggestion for a useful example that would be better than the example at the top of the readme?

akavel 1120 days ago [-]
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.
thaumaturgy 1119 days ago [-]
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.
akavel 1116 days ago [-]
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.
wizzwizz4 1121 days ago [-]
e12e 1121 days ago [-]
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).

Ed: Or perhaps I'm better off just using https://zyedidia.github.io/literate/index.html directly.

thaumaturgy 1121 days ago [-]
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.

e12e 1120 days ago [-]
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 ;)

brudgers 1121 days ago [-]
I first heard of Literate DevOps via this video a few years ago https://youtu.be/dljNabciEGg
johtela 1121 days ago [-]
Shameless plug of my own tool. If you want to write literate programs in TypeScript, check out https://johtela.github.io/litscript/

There is also a VSCode syntax highlighting extension https://marketplace.visualstudio.com/items?itemName=johtela....

cableclasper 1120 days ago [-]
Looks great! LOL at the "Knuth is my homeboy" picture!
daly 1121 days ago [-]
Literate Programming Example:

https://www.youtube.com/watch?v=mDlzE9yy1mk

mzs 1120 days ago [-]
Here's literate programming in markdown implemented in gawk: https://github.com/bapcyk/lawk
rpmuller 1120 days ago [-]
My hope is that this recent interest in literate programming will combine with the recent interest in readable jupyter notebooks (jupytext, etc.).
sieste 1121 days ago [-]
Very nice project, I'm a big fan of literate programming. I currently use knitr. Are there any big differences between knitr and literate?
cableclasper 1120 days ago [-]
Not much in principle. It is just that literate is language agnostic whereas knitr seems dedicated to R.
wrycoder 1120 days ago [-]
At the bottom of the link:

and the source can be read here

404

cableclasper 1120 days ago [-]
Dead link that. Should let the author know. But there's a link at the top of the page as well: https://zyedidia.github.io/literate/website-source/
tom_d999 1121 days ago [-]
what are the benefits of literate programming systems?
jostylr 1117 days ago [-]
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.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact
Rendered at 03:50:09 GMT+0000 (Coordinated Universal Time) with Vercel.