I could not help but notice the conspicuous absence of notebooks.
That is an excellent resource. Thanks very much for posting [and thanks to everyone involved in the original compilation].
Literate Programming: Articles
31–40 of 73 posts
Re: Literate Programming: Articles
#32Earlier quoted context omitted.
>* The "includes" problem. Most language require you to include/import/require packages used in a file. These are usually all placed at the start. This means a lot of chapters will start with "here are all the includes we'll need" if you're using a linear format. More complex formats that rearrange the code to generate outputs can do a better job but it's still a little clunky. Real literate programming, rather than…
> 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 >
I think the idea of a general preamble that would have the same explanation, every time, is fine? This is literally the boilerplate concept.
The idea is more to break the code into parts you would explain and grok easily. Not every atomic part of the code.
Re: Literate Programming: Articles
#33Earlier quoted context omitted.
Every language with block comments supports this, by starting the file with a comment and wrapping code in end-comment/start-comment pairs. It's not especially useful. For literate programming you really need the ability to move blocks of code around without the ceremony of function signatures.
Haskell actually supports literate programming [0]. Oleg Kiselyov regularly writes examples of his ideas using it, e.g. [1], [2]. [0] https://wiki.haskell.org/Literate_programming#Haskell_and_li... [1] https://okmij.org/ftp/Haskell/class-based-dispatch.lhs [2] https://okmij.org/ftp/Computation/lightweight-guarantees/eli...
Haskell does not natively support literate programming -- it only allows the comment/code default to be swapped. The format named "literate Haskell" is basically just syntactic sugar for {- comment blocks -}. Literate programming requires the ability to decouple the ordering of code relative to the commentary.
I wrote more about this at https://news.ycombinator.com/item?id=35985835> and https://john-millikin.com/software/anansi#history>.
Re: Literate Programming: Articles
#34It might be nice if modern languages defined an official way to "flip" the interpretation of a source file, so that by default the content is treated as markdown and the code goes in fenced blocks (rather than defaulting to code and providing a way to mark comment blocks). Then we might hope for support in most tooling to appear quite quickly. I think one reason why literate programming is less attractive nowadays (c…
> It might be nice if modern languages defined an official way to "flip" the interpretation of a source file, so that by default the content is treated as markdown and the code goes in fenced blocks (rather than defaulting to code and providing a way to mark comment blocks)
Jef Raskin wrote and thought about this. The sentiment sounds like it would fit best in his piece "Comments are More Important than Code" (2005), but there's another Raskin article "The Woes of IDEs" that contains the most explicit agreement:
> In my method, program segments are embedded in the midst of a word processor document--like raisins in cake--so that the emphasis is on the explanation rather than the code.
https://queue.acm.org/detail.cfm?id=864034>
> maybe something like the above is enough to get 90% of the advantages of a full literate programming system
If you're doing JS, then you can actually get pretty far with browser-based notebooks that just use vanilla HTML (and CSS), which notably doesn't require any ex ante setup/configuration for runtime support in the vein of e.g. Jupyter notebooks. (The problem being that not everyone writes JS and even most programmers these days who think they're writing JS really aren't and have no idea how to, so this won't work for them, either.)
Re: Literate Programming: Articles
#35I recently tried Literate Programming and I've found that it has some downsides not commonly discussed by its advocates. (It also has upsides which are valid, this post may come across as overly negative because I'm only covering negatives.) * It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more…
> It adds overhead to refactoring. Refactoring code now means editing and rewriting a book
In my opinion, this is a good thing. The problem with ordinary refactoring is that it's too easy to just shuffle things around until they work/seem nicer/do whatever you want to. However, with literate programming, you have to think why you're refactoring, and how does it reflect in the explanation.
Re: Literate Programming: Articles
#36It might be nice if modern languages defined an official way to "flip" the interpretation of a source file, so that by default the content is treated as markdown and the code goes in fenced blocks (rather than defaulting to code and providing a way to mark comment blocks). Then we might hope for support in most tooling to appear quite quickly. I think one reason why literate programming is less attractive nowadays (c…
There are tools to do exactly that, like a simple bash scripts lit.sh: https://github.com/vijithassar/lit
Pandoc is a nice swiss army knife that can do a similar conversion with some custom lua filters. It could even do wackier stuff like convert word or odt files to code if you were really diving into prose-first coding.
I've also heard it referred to as 'semi-literate programming' because it skips the reorganization functionality and just gives you nice prose to code conversion.
Re: Literate Programming: Articles
#37I recently tried Literate Programming and I've found that it has some downsides not commonly discussed by its advocates. (It also has upsides which are valid, this post may come across as overly negative because I'm only covering negatives.) * It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more…
their is no tooling for it because no one has tried to build it. all you need is a markdown file with links to the code bookmarks. every modern editor can resolve those links to the actual location of the code
Re: Literate Programming: Articles
#38It might be nice if modern languages defined an official way to "flip" the interpretation of a source file, so that by default the content is treated as markdown and the code goes in fenced blocks (rather than defaulting to code and providing a way to mark comment blocks). Then we might hope for support in most tooling to appear quite quickly. I think one reason why literate programming is less attractive nowadays (c…
There are tools to do exactly that, like a simple bash scripts lit.sh: https://github.com/vijithassar/lit Pandoc is a nice swiss army knife that can do a similar conversion with some custom lua filters. It could even do wackier stuff like convert word or odt files to code if you were really diving into prose-first coding. I've also heard it referred to as 'semi-literate programming' because it skips the reorganizatio…
As long as these are external tools, IDEs and things like github's default file renderer aren't going to understand what's going on.
Re: Literate Programming: Articles
#39That's ... a lot of articles. Is there any article in particular worth checking out?
Clicking through the links I find this:
> In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source.
http://literateprogramming.com/lpfaq.pdf#page11
By this litmus test, the Go standard library qualifies as literate programming. Document production tools are go doc or godoc. The .go files are themselves already compilable source.
Re: Literate Programming: Articles
#40I recently tried Literate Programming and I've found that it has some downsides not commonly discussed by its advocates. (It also has upsides which are valid, this post may come across as overly negative because I'm only covering negatives.) * It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more…
> It messes with tooling. If you're lucky then your editor will be smart enough to syntax highlight inside code blocks, or can be taught to do so easily. It's unlikely that more advanced IDE-style features will work.
Probably a niche example and the exception that proves the rule, but in Racket, the included literate programming (Scribble/LP2) is itself a language implemented in Racket. Racket’s IDE and tools for exposing and inspecting syntax work just as well in that environment as in any other Racket-implemented language.