4 ms·

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 markdow

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 (compared to the days of Pascal) is that programming languages have got better at letting you arrange your code in whatever way you like. So maybe something like the above is enough to get 90% of the advantages of a full literate programming system.

jmillikin 3y ago
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.
- mjw1007 3y ago
  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.
  - jmillikin 3y ago
    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.
- Joker_vD 3y ago
  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_literate_programming https://wiki.haskell.org/Literate_programming#Haskell_and_li... [1] https://okmij.org/ftp/Haskell/class-based-dispatch.lhs https://okmij.org/ftp/Haskell/class-based-dispatch.lhs [2] https://okmij.org/ftp/Computation/lightweight-guarantees/eliminating-mult-array-bound-check.lhs https://okmij.org/ftp/Computation/lightweight-guarantees/eli...
  - jmillikin 3y ago
    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 https://news.ycombinator.com/item?id=35985835> and <https://john-millikin.com/software/anansi#history https://john-millikin.com/software/anansi#history>.
lloeki 3y ago
I had a black/white/gray vim theme that supports that, the only color is comments are gray. Press F6 and it reverses code and comment colors.
cxr 3y ago
> 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 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.)
qbasic_forever 3y ago
There are tools to do exactly that, like a simple bash scripts lit.sh: https://github.com/vijithassar/lit 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.
- mjw1007 3y ago
  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.
  - qbasic_forever 3y ago
    Yeah that's why lit.sh and most similar tools have a mode to output a version of the file with the markdown commented out except for code blocks. This lets you pipe it into any tool and get output with proper line numbers, analysis, etc. VS code is getting pretty smart about code notebooks too, it has native support for a few different formats of markdown + code blocks (hydrogen, jupyter, etc) and applies all the right syntax highlighting, analysis, etc. to each block automatically.
skimdesk 3y ago
One more tool to accomplish this is lmt [0] which, despite minimal documentation, is quite pleasing to use. [0] https://github.com/driusan/lmt https://github.com/driusan/lmt

jmillikin 3y ago

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.

mjw1007 3y ago
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.
- jmillikin 3y ago
  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.
Joker_vD 3y ago
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_literate_programming https://wiki.haskell.org/Literate_programming#Haskell_and_li... [1] https://okmij.org/ftp/Haskell/class-based-dispatch.lhs https://okmij.org/ftp/Haskell/class-based-dispatch.lhs [2] https://okmij.org/ftp/Computation/lightweight-guarantees/eliminating-mult-array-bound-check.lhs https://okmij.org/ftp/Computation/lightweight-guarantees/eli...
- jmillikin 3y ago
  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 https://news.ycombinator.com/item?id=35985835> and <https://john-millikin.com/software/anansi#history https://john-millikin.com/software/anansi#history>.

lloeki 3y ago

I had a black/white/gray vim theme that supports that, the only color is comments are gray. Press F6 and it reverses code and comment colors.

cxr 3y ago

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

qbasic_forever 3y ago

There are tools to do exactly that, like a simple bash scripts lit.sh: https://github.com/vijithassar/lit 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.

mjw1007 3y ago
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.
- qbasic_forever 3y ago
  Yeah that's why lit.sh and most similar tools have a mode to output a version of the file with the markdown commented out except for code blocks. This lets you pipe it into any tool and get output with proper line numbers, analysis, etc. VS code is getting pretty smart about code notebooks too, it has native support for a few different formats of markdown + code blocks (hydrogen, jupyter, etc) and applies all the right syntax highlighting, analysis, etc. to each block automatically.

skimdesk 3y ago

One more tool to accomplish this is lmt [0] which, despite minimal documentation, is quite pleasing to use. [0] https://github.com/driusan/lmt https://github.com/driusan/lmt