Re: [Axiom-developer] Literate Programming -- Knuth interview

[daly]

On Sat, 2011-11-19 at 10:17 +0000, Martin Baker wrote:
> > If you feel that interleaving videos, animations, navigation, and any
> > other tricks improves the "independence test" results then these
> > techniques should be used. If, however, you are just trying to
> > organize the material by some random criteria (e.g. alphabetical
> > or as trees of logically grouped files) then you are undermining
> > the transfer of ideas.
> 
> Tim,
> 
> I think we may agree about the importance and general principles of this and 
> we are just discussing the mechanics here? (although I think that navigation 
> and diagrams are much more fundamental and powerful than just "tricks")

I think we are in agreement on principles I still shy away from a 
focus on the mechanics. Think typewriters.

> 
> I think its good to take into account practical matters and allow the use of 
> standard HTML and code editors and to separate these principles from the 
> tools 
> used.

Well, maybe. Programmers love their tools and see nothing wrong with 
splashing "documentation" all over a tree of little files. You could
write a literate program that way but it would be like reading a
book in weekly installments in a magazine.

> 
> I don't see problem in having multiple source, HTML and diagram files treated 
> as single entity (in a ZIP file or something similar) the entry points would 
> be at the root. I cant see a problem for the "independence test".

Several people have pointed me at trees of code that are supposed to be
in a literate style. The problem is that they have confused the idea of
documentation or comments with the idea of literate programming.

Literate programming makes the human to human communication paramount.
This means that you ought to be able to "sit and read", like any good
novel. You could easily print the example page I used and read it from
beginning to end without a computer.

Documentation and comment systems are not like this. They make the
program organization "fit the machine". They talk about the code, and
focus on line-by-line or file-by-file. They tend to work well with all
kinds of "tools" like Eclipse, Javadoc, or Doxygen.

It is easy to confuse literate programming with these documentation
and commenting system but they are nowhere the same.

So if I have to know anything about file organization, if I have to
pop between files or if I have to have rules about what the correct
syntax is (e.g. Javadoc) then I am looking at a documentation and
comment system.

If I can write a story in any form I want and splash code icons in at
the appropriate moment, if the story focuses on ideas, and if I can
understand it without looking at the code then I am looking at a
literate program.

> 
> When the code is complied the HTML files can be transferred unchanged to the 
> runtime so they are available for hyperdoc(HTML version) and help files at 
> runtime.

That's a documentation and commenting tool.

Tim