Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Literate Programming: Articles

literateprogramming.com

Post reply on HN
Print view View original

51–60 of 73 posts

Re: Literate Programming: Articles

#51

Post by mncharity »

FWIW, I note emacs polymode's[1] poly-markdown, and pandoc's ast json dumps[2].

For decades, I searched for literate tooling for personal projects, but nothing stuck. Something about the design space seems to make it easy to hit design choices that are uncomfortable fits for one's use case, or personal taste, or preferences for tooling extension and customization. It reminds me of the personal information manager space.

My most recent foray seemed more promising. poly-markdown permits editing polylingual md files, and is permissive towards markdown dialects. So I could use a custom literate markdown, normalize it for rich-but-restrictive pandoc, then get the pandoc ast and emit custom html. With Julia's MLStyle[3] for pattern matching, and a bit of front-end pretty, it was unexpectedly easy to reach something comfortable.

Perhaps for literate tooling to gain greater traction, it helps that software dev progress permits folks to more easily cook their own?

[1] https://github.com/polymode/polymode [2] https://pandoc.org/filters.html [3] https://thautwarm.github.io/MLStyle.jl/latest/

Re: Literate Programming: Articles

#52

Post by Jtsummers »

cxr wrote: post #46
Jtsummers wrote: post #44

Earlier quoted context omitted.

Does it matter though? The primary purpose of using literate programming is expository. If Knuth feels that putting the includes at the start makes sense, then that's what he does. If you don't, then fine you move it to the end or the middle. That's the benefit of WEB (and WEB-derived systems). The presentation order is not dependent on the code order, it's dependent on what makes the most expository sense. When I've…

> Does it matter though? Yes. > The primary purpose of using literate programming is expository. Right. A big, zero-context block of includes prefaced with a comment that you should just "skip ahead" past it to the "interesting stuff" and offering no insight about the stuff that you're skipping over is the opposite of expository. The main program—what it actually does—is sufficient to serve as exposition for the incl…

My point, which you missed: It doesn't matter what Knuth does.

thr-nrg rightly pointed out in their comment that you can place the code wherever you want. You then say, "Knuth puts it at the top" (meant as a criticism of his style).

My point (so you don't miss it again): You can place the code wherever you want when doing a literate programming style. It also doesn't matter what Knuth does with his includes because his style does not dictate your style or my style or anyone else's style. So put it wherever you want. His style does not matter.

Re: Literate Programming: Articles

#53

Post by cxr »

cnity wrote: post #7
Davidnkt89 wrote: post #4

[flagged]

I have often thought about implementing a simple Makefile alternative in a literate style. Almost like an executable README.md. This way you can describe the project and the ways to interact with it in a much more readable way than a Makefile.

> Almost like an executable README.md

Previously:

> There is a way to write a plain text file so that it looks the same (i.e. appears as plain text) whether it has the .txt extension when it's opened in a text editor and/or Web browser versus whether you rename it to have a browser-associated file extension like .htm or .html and then re-open it in a Web browser.

Why is this relevant? Because:

> Documents opened Web browsers are programmable.

From https://news.ycombinator.com/item?id=35389974>

> If folks were really committed to improving the developer experience, then instead of what we do now [...] development would work like this: ¶1. Download the project source tree ¶2. Open README.html ¶3. Drag and drop the project source onto README.html

From https://news.ycombinator.com/item?id=28407936>

Re: Literate Programming: Articles

#54

Post by mananaysiempre »

cxr wrote: post #50
mananaysiempre wrote: post #42

Earlier quoted context omitted.

Also the PCC compiler published A Retargetable C Compiler by Fraser & Hanson, as well as the PBRT renderer as described in the Academy Award winner Physically Based Rendering [1] by Pharr, Jacob, & Humphreys. As for instances where the point is more the book than the program, there’s C Interfaces and Implementations by Hanson, and while the “literate diffs” style used by Nystrom’s Crafting Interpreters [2] comes at t…

> the PCC compiler published A Retargetable C Compiler by Fraser & Hanson You're thinking of LCC. PCC is AT&T's compiler and the work of Johnson who also did yacc.

Right. That’s what I get for checking the ’net instead of literally flipping back to the introduction of the book I literally already had open. :/

Re: Literate Programming: Articles

#55

Post by taeric »

cxr wrote: post #46
Jtsummers wrote: post #44

Earlier quoted context omitted.

Does it matter though? The primary purpose of using literate programming is expository. If Knuth feels that putting the includes at the start makes sense, then that's what he does. If you don't, then fine you move it to the end or the middle. That's the benefit of WEB (and WEB-derived systems). The presentation order is not dependent on the code order, it's dependent on what makes the most expository sense. When I've…

> Does it matter though? Yes. > The primary purpose of using literate programming is expository. Right. A big, zero-context block of includes prefaced with a comment that you should just "skip ahead" past it to the "interesting stuff" and offering no insight about the stuff that you're skipping over is the opposite of expository. The main program—what it actually does—is sufficient to serve as exposition for the incl…

I'm not entirely sure that trying to not have boilerplate of any kind is a worthy goal. Consider, no book is wanting to get rid of the title page. Even a dedication page has grown to be a near required page that we literally teach students to write.

To that end, the goal is to not have parts that can be the same between programs vary. That has pedagogical value. Is a type of stability that we don't really value much anymore.

Though, I also give a +1 to jtsummers' point. Knuth has a style of writing literate programs. And if you find some old videos of his reviewing student's code, he explicitly calls out points of style that he likes from different students and how they work together. He didn't necessarily want to push a "this is how you style your programs," but instead was working how you talk about programs into a way that you can also write them. While not having to relearn either, necessarily.

Re: Literate Programming: Articles

#56

Post by cxr »

Jtsummers wrote: post #52
cxr wrote: post #46

Earlier quoted context omitted.

> Does it matter though? Yes. > The primary purpose of using literate programming is expository. Right. A big, zero-context block of includes prefaced with a comment that you should just "skip ahead" past it to the "interesting stuff" and offering no insight about the stuff that you're skipping over is the opposite of expository. The main program—what it actually does—is sufficient to serve as exposition for the incl…

My point, which you missed: It doesn't matter what Knuth does. thr-nrg rightly pointed out in their comment that you can place the code wherever you want. You then say, "Knuth puts it at the top" (meant as a criticism of his style). My point (so you don't miss it again): You can place the code wherever you want when doing a literate programming style. It also doesn't matter what Knuth does with his includes because h…

I didn't miss it. I replied to your question of whether it matters: yes, it does.

Your point doesn't make any sense. ("_You_ can place the code wherever _you_ want when doing a literate programming style.") Literate programs are supposed to be read. Of course a writer can write however they want. You could write a book where everything that isn't a proper noun ends with an uppercase letter, except for proper nouns, which are all lowercase. It will be shit.

Re: Literate Programming: Articles

#57

Post by cxr »

taeric wrote: post #55
cxr wrote: post #46

Earlier quoted context omitted.

> Does it matter though? Yes. > The primary purpose of using literate programming is expository. Right. A big, zero-context block of includes prefaced with a comment that you should just "skip ahead" past it to the "interesting stuff" and offering no insight about the stuff that you're skipping over is the opposite of expository. The main program—what it actually does—is sufficient to serve as exposition for the incl…

I'm not entirely sure that trying to not have boilerplate of any kind is a worthy goal. Consider, no book is wanting to get rid of the title page. Even a dedication page has grown to be a near required page that we literally teach students to write. To that end, the goal is to not have parts that can be the same between programs vary. That has pedagogical value. Is a type of stability that we don't really value much…

> Consider, no book is wanting to get rid of the title page.

Lists of imports are not title pages.

> the goal is to not have parts that can be the same between programs vary

Lists of imports vary. (And in today's world of extreme software reuse, which other pieces of software a program depends on is of greater interest than ever.)

I'd take your point on boilerplate if it were necessary and unavoidable. I've already described, however, that it isn't and how.

Re: Literate Programming: Articles

#58

Post by cxr »

thr-nrg wrote: post #49
cxr wrote: post #24

Earlier quoted context omitted.

> Real literate programming, rather than rich text comments, can order the code blocks in any order. You can add then at the very end of the book/chapter/section if you feel like it. And yet Knuth still does it the other way. http://akkartik.name/post/literate-programming >

And? Knuth also used Pascal for the original Web and TeX. Both are still Pascal programs that get transpiled to C before being compiled. Just because he does something doesn't mean you should copy it religiously. Web and its derivatives are sufficiently advanced that they suffer from the lisp curse. What in other systems are major fundamental engineering problems - try adding an include in the middle of a c file - in…

> And?

And nothing. For programs that are ostensibly meant to be read, Knuth's examples are poor ones.

> in Web derivates are a matter of taste

Dumping a bunch of includes at the top and saying the equivalent of "don't worry about this boring stuff for now; you can skip it if you want" (and thereby compromising the entire LP experiment) is a matter of taste in the way that putting beef in a vegan casserole is.

Re: Literate Programming: Articles

#59

Post by taeric »

cxr wrote: post #57
taeric wrote: post #55

Earlier quoted context omitted.

I'm not entirely sure that trying to not have boilerplate of any kind is a worthy goal. Consider, no book is wanting to get rid of the title page. Even a dedication page has grown to be a near required page that we literally teach students to write. To that end, the goal is to not have parts that can be the same between programs vary. That has pedagogical value. Is a type of stability that we don't really value much…

> Consider, no book is wanting to get rid of the title page. Lists of imports are not title pages. > the goal is to not have parts that can be the same between programs vary Lists of imports vary. (And in today's world of extreme software reuse, which other pieces of software a program depends on is of greater interest than ever.) I'd take your point on boilerplate if it were necessary and unavoidable. I've already d…

Depends on the list? The ones you linked from Knuth are basically fixed imports that are, in fact, very common and easy to take as a whole.

I think the disconnect is still that you are writing a C program with CWEB. If I'm using a literate style to write JavaScript, I'm still writing a JavaScript program. As such, the point isn't to just throw any established norms out, but to rearrange for presentation. If some items go well together, might as well keep them together.

Most programming tools that can do this require you to "bundle" things such that you have to have well formed containers, if you will. Having the "add this to a section" constructs really help, as then you can say things like "add this to the imports" the first time you have need of a new import. But, if you don't add any non-standard imports, you can forego doing that.

The other approach is to try and make everything implied, such that new users can skip any of the boilerplate and jump straight to programming. That is fine, for what it is, but does little to build understanding of the programs as a whole.

That said, I may have missed your described solution. I'm kind of scattershot today and not keeping fully on top of this. Apologies if I'm talking past you.

Re: Literate Programming: Articles

#60

Post by Jtsummers »

cxr wrote: post #56
Jtsummers wrote: post #52

Earlier quoted context omitted.

My point, which you missed: It doesn't matter what Knuth does. thr-nrg rightly pointed out in their comment that you can place the code wherever you want. You then say, "Knuth puts it at the top" (meant as a criticism of his style). My point (so you don't miss it again): You can place the code wherever you want when doing a literate programming style. It also doesn't matter what Knuth does with his includes because h…

I didn't miss it. I replied to your question of whether it matters: yes, it does. Your point doesn't make any sense. ("_You_ can place the code wherever _you_ want when doing a literate programming style.") Literate programs are supposed to be read . Of course a writer can write however they want. You could write a book where everything that isn't a proper noun ends with an uppercase letter, except for proper nouns,…

What matters is the exposition. Does the presentation (order, style, etc.) communicate what you intend for it to communicate, and does it communicate effectively. That's what matters.

Does it matter what Knuth does? Nope. I don't care for that aspect of his style. I already said I put the includes (when a text gets past the draft stage at least) toward the end. We're in violent agreement with respect to how we (if I understood you correctly) often or generally put them into LP texts.

You're just weirdly caught up on criticizing Knuth's style for some reason. Have fun shouting into the wind. The rest of us know, it doesn't matter. The goal is to communicate effectively and not whine about things that don't matter.

Post reply on HN