3 ms·
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 or
by agl 16y ago
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.pdf https://github.com/agl/rwb0fuz1024/raw/master/rwb0fuz1024.pd...
With my own tools: http://www.imperialviolet.org/binary/lsmsb.html http://www.imperialviolet.org/binary/lsmsb.html
- pufuwozu 16y agoLiterate 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?
- ch 16y agoCheck out 'libavl' which was written in the literate programming style: http://www.stanford.edu/~blp/avl/libavl.html/ http://www.stanford.edu/~blp/avl/libavl.html/
- jashkenas 16y agoFortunately, 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.
- DougWebb 16y agoNot 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.
- tomjen3 16y agoSure 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?
- anamax 16y ago> 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?
- vlisivka 16y agoI 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.