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

11–20 of 73 posts

Re: Literate Programming: Articles

#11

Post by bradrn »

pseudonymcoward wrote: post #5

I 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…

> Obviously tools could be adapted with custom plugins but literate programming isn't popular enough for these to already exist as far as I'm aware.

I’ve heard that org-babel [https://orgmode.org/worg/org-contrib/babel/intro.html] works pretty well for this, though I’ve never used it myself.

Re: Literate Programming: Articles

#12

Post by jmillikin »

mjw1007 wrote: post #10

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). 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…

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.

Re: Literate Programming: Articles

#13

Post by smcl »

jmillikin wrote: post #6
Davidnkt89 wrote: post #4

[flagged]

I wrote a literate programming preprocessor in Haskell[0], and used it to weave/tangle a D-Bus implementation (also in Haskell). The woven PDF[1] weighs in around 90 pages. I'll quote from the linked page regarding my conclusions: ------------>8---------- But in the end, I was never able to realize the promised benefits of Literate Programming. The typeset PDF was not easier to read than hypertext documentation gener…

I really hope that "--->8---" catches on here as a way to quote an extract from something nicely :)

Re: Literate Programming: Articles

#15

Post by tmtvl »

bradrn wrote: post #11
pseudonymcoward wrote: post #5

I 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…

> Obviously tools could be adapted with custom plugins but literate programming isn't popular enough for these to already exist as far as I'm aware. I’ve heard that org-babel [ https://orgmode.org/worg/org-contrib/babel/intro.html ] works pretty well for this, though I’ve never used it myself.

Org Babel is really nice, but it doesn't really solve the problem, rather it sidesteps it my giving you the option to edit a block of code in a dedicated buffer. I don't know how well that works with LSP (I don't use LSP) but it does allow you to make full use of SLIME.

Re: Literate Programming: Articles

#16

Post by thr-nrg »

pseudonymcoward wrote: post #5

I 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…

>* 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 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.

I did some literary programs about a previous generation of our program. Every new hire reads them and asks me for copies.

Re: Literate Programming: Articles

#17

Post by yuchi »

smcl wrote: post #13
jmillikin wrote: post #6

Earlier quoted context omitted.

I wrote a literate programming preprocessor in Haskell[0], and used it to weave/tangle a D-Bus implementation (also in Haskell). The woven PDF[1] weighs in around 90 pages. I'll quote from the linked page regarding my conclusions: ------------>8---------- But in the end, I was never able to realize the promised benefits of Literate Programming. The typeset PDF was not easier to read than hypertext documentation gener…

I really hope that "--->8---" catches on here as a way to quote an extract from something nicely :)

The actual size may change a lot depending on the font, but there’s a nice Unicode symbol for that:

——— ———

Update: apparently HN doesn’t like some characters…

Anyway these are the characters: https://unicode.org/charts/nameslist/n_2700.html

- 2700 Black Safety Scissors

- 2701 Upper Blade Scissors

- 2702 Black Scissors

- 2703 Lower Blade Scissors

- 2704 White Scissors

Re: Literate Programming: Articles

#18

Post by mjw1007 »

jmillikin wrote: post #12
mjw1007 wrote: post #10

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). 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…

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.

If I use block comments like that in most contemporary IDEs, I find that by default they show the main text in flat "this is a comment" styling, even though they're in principle capable of using different kinds of highlighting for different parts of the file.

Similarly, if I preview such a file on github I get syntax highlighting for the code but I don't get rendering for the markdown.

So I think the advantage of an 'official' way of saying you're using this arrangement would be communicating intent to more-or-less generic tools.

Re: Literate Programming: Articles

#20

Post by jmillikin »

mjw1007 wrote: post #18
jmillikin wrote: post #12

Earlier 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.

If I use block comments like that in most contemporary IDEs, I find that by default they show the main text in flat "this is a comment" styling, even though they're in principle capable of using different kinds of highlighting for different parts of the file. Similarly, if I preview such a file on github I get syntax highlighting for the code but I don't get rendering for the markdown. So I think the advantage of an…

That's an IDE configuration problem. Most of them support mixed-mode syntax highlighting nowadays, so you just need to configure your theme to treat block comments as Markdown (or LaTeX, HTML, whatever).

You could probably even do it with Markdown directly, using fenced code blocks as part of your begin/end lines.

I think you'll find that this approach offers very little benefit over either traditional commentary or linear notebook-style inline code blocks.

Post reply on HN