Hacker News Reader

Comment by wwfn | Hacker News Reader

Literate programming tools that weave/tangle code and documentation don't play well with significant whitespace. Not a problem for me, but I think it's on a valid line of complaints.

View on HN

Which ones? Org mode's babel works fine with it. If you do something like this (loose, not precise babel syntax):

  <<body>>=
    if 1 == 1:
        print('1 == 1, shocking!')

  <<function>>=
    def foo():
      <<body>>

It will generate properly indented code when tangled as in:

  def foo():
    if 1 == 1
        print('1 == 1, shocking!')

Note that it puts in precisely two extra spaces for each line in the tangled `body`, which is the amount used in the block named `function` where it references `body`. If you used 4 spaces of indentation, it would use 4 in the tangled output. I've also used noweb and don't recall this being an issue, however that was not with Python so it's possible I just didn't notice a problem with it.

I stand corrected! I'm guessing my own bad formatting lead me astray at some point. I tried to come up with a pathological example that'd break with noweb just now and had no luck.

I very strongly disagree. The most successful implementation of literate programming is the Jupyter Notebook, formerly called iPython Notebook. Even when you write it as raw markdown, there's no issue mixing documentation with triple-backtick code blocks.

Maybe you're thinking of mixing Python with HTML? Python based HTML templating can be ugly, and the significant indentation of Python is a very poor mix for replacing Javascript in whitespace-agnostic HTML.

> there's no issue mixing documentation with triple-backtick code blocks.

Your argument became: By adding delimiters, even Python can play well with other languages. /s

I thought tools like jupyter and rmarkdown are better described as narratives[0] (lab notebooks and report generators) separate from and almost antagonistic to literate programming[1]. At least as I've been exposed to them, notebooks don't easily facilitate code reuse -- libraries aren't written in notebooks but could be written with literate programming tools.

[0]: https://khinsen.wordpress.com/2015/09/03/beyond-jupyter-what... [1]: http://www.literateprogramming.com/

Technically comments are considered blank lines, so indentation can be arbitrary. This is against PEP8/linters, but it's not a formatting error.

Triple quoted docstrings just require that the initial marker (""" or ''') is indented properly (since they are not considered blank lines). All contained text, and the closing marker, can be at any indentation level. This is the cleanest way to include a page of free form documentation, mid anywhere.

Reply on news.ycombinator.com