Hacker News Reader

Comment by agl | Hacker News Reader

Literate programming, at least at Knuth defines it, includes some aspects which Docco omits.

Firstly, the machine readable file can be output in a different order than the human readable. (Indeed, sequential chunks in the human readable output can be directed to multiple different files.)

Secondly, the human readable file includes 'outlining': when describing a function, parts of it can be elided and covered later.

Now, these may have been required because the target language was C(like), which has different properties from many other languages. But I did want to point out that Docco is a quite different point in the literate programming landscape.

For examples, see a couple of literate programs that I've written.

With Web (Knuth's tool): https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pd...

With my own tools: http://www.imperialviolet.org/binary/lsmsb.html

View on HN

Fortunately, in most modern languages, functions can be defined in any order -- and baseline configuration can be included in a separate file.

In this day and age, generating the machine-readable version of the file in a different order than the version that is meant to be read, seems like an unnecessary convolution and debugging hurdle.

Not necessarily. I can see some value in having a different organization for explaining the program to someone new to it vs organizing it to make it easy to maintain for someone familiar with it. For example, for maintenance you'd like to have all of your constants defined together and usually near the top, but for documenting you'd probably prefer to introduce constants when they're needed.

Sure you can define the functions in pretty much any order, but can you define two or more functions at the same time?

Say you are talking about the function to build the user interface, can you stop defining that, go back and define the callback, then continue defining the gui builder function?

Or, when you are writing an Android program, can you add stuff to the manifest file, right as you write the source code that uses it?

Or, when you are writing that rails app, can you put the code for one of your user stories, then extend your db model and finally add the code that test it -- before you continue with the next user story that adds code to the same controller?

> Say you are talking about the function to build the user interface, can you stop defining that, go back and define the callback, then continue defining the gui builder function?

That's how lisp folks worked. I don't see why that technique wouldn't work in bare python as well.

Static type systems can make that difficult. How many frameworks impose analogous constraints?

I am working on system which (I hope) will be 5GL. I use literate programming as it main programming language. I cannot use any 1/2/3/4GL language in the system because of lot of limitations in 3/4GL languages. My system operates on meta-meta-data about code. I can define meta-meta-data about code using literate programming only.

If you will look at some existing systems, which operate with meta-meta-data, like yum/rpm, or apt/deb, or maven2, etc., then you will see, that code, which describes packages, is literate-like: it contains author, title, description, general overview of package, etc. It does not contains function, or something like that.

If my English is wrong - sorry. I am Ukrainian.

Literate Haskell seems to minimise the first difference (Haskell allows you to define functions out of order).

I'm not familiar with outlining. Does anyone have a simple example?

Check out 'libavl' which was written in the literate programming style: http://www.stanford.edu/~blp/avl/libavl.html/

Reply on news.ycombinator.com