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

21–30 of 73 posts

Re: Literate Programming: Articles

#21

Post by smcl »

yuchi wrote: post #17
smcl wrote: post #13

Earlier quoted context omitted.

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

Oh that's neat, but I've no problem using the little emoticon style 88

Re: Literate Programming: Articles

#24

Post by cxr »

thr-nrg wrote: post #16
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…

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

Re: Literate Programming: Articles

#25

Post by Joker_vD »

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.

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

Re: Literate Programming: Articles

#26

Post by musingsole »

I've been experimenting a lot with using Jupyter Notebooks (http://jupyter.org/) to get many features of literate programming.

The tooling can be a bit clunky -- though JupyterLab and some plugins can go a long way. Importing notebooks into other notebooks or modules is still kind of weird even with the `ipynb` library.

However, on the otherside of it all, you have a collection of documents that contain documentation, code, and tests, all side by side and storable with proof of past execution.

I'll take this arrangement over someone's unit test and CI suite every day of the week.

Re: Literate Programming: Articles

#27

Post by myaccountonhn »

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…

I use it in a commercial team to write technical documentation. I write it while, for example, exploring an API that I am integrating with. It produces a nice little document with important integration apis, limitations, open questions, integration decisions as well as interactive ways to check certain parts of the integration.

I do this with Typescript (deno) and a neovim plugin called sniprun.

Re: Literate Programming: Articles

#28

Post by lloeki »

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…

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.

Re: Literate Programming: Articles

#29

Post by crispyambulance »

I think there's some distinctions that need to be made. IMHO, Literate programming can be an umbrella for a bunch of different things.

Is it "notebook" style programming, like Mathematica, matlab, Jupyter, and markdown-based stuff like R/python + Quarto? In this mode, I think the focus is more on creating a document or communicating stuff typically with data analysis. And actually, "literate" is a very apt adjective for something that's ultimately intended to be a document of some kind.

Or is it more general intended for writing arbitrary software applications and having everything in the source code? In other words, to understand the source, you just read the source and there are no other documents.

The latter mode, I think, is still very much not around as far as I know (academic proof-of-concepts for papers don't count :-) ). Will it ever really exist?

Re: Literate Programming: Articles

#30

Post by taeric »

crispyambulance wrote: post #29

I think there's some distinctions that need to be made. IMHO, Literate programming can be an umbrella for a bunch of different things. Is it "notebook" style programming, like Mathematica, matlab, Jupyter, and markdown-based stuff like R/python + Quarto? In this mode, I think the focus is more on creating a document or communicating stuff typically with data analysis. And actually, "literate" is a very apt adjective…

I have tried a few blog posts with literate style code. Some in a notebook style, like https://taeric.github.io/cube-permutations-1.html. in general, that style seems easier nowadays.

There is Stanford GraphBase, and a really good MP3 book that are full programs. Not to mention TeX.

Post reply on HN