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

[Martin Baker]

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

I tend think of this as reference information. The sort of thing that Axiom 
produces dynamically at runtime like )show and )display. I think there would 
be advantages in generating this statically with a compile-time documentation 
tool, the information would be much more richly interlinked with itself and 
the other type of information.

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

They may not be the same but why should the user have to switch between them 
and know which to use and when?

In Axiom, I have often tried to find something in pdf generated by literate 
code when what I wanted was in hyperdoc or runtime commands or visa-versa. 
There seems to be a lot of overlap of these sources of information in Axiom. I 
would like to be able to link between them by clicking on the text.

Also I may be reading something as a story when I come across some issue that 
I need to clarify which may be a different type of documentation and so I need 
to switch to a more reference way of working. I think there are all kinds of 
things that the user/maintainer needs to do between these extremes and I find 
well produced HTML to be the best way to get to the information that I need 
(of course, like anything else, there is a lot of bad HTML around).

Also I think a tree structure scales up better than a linear structure.  A 
story works well for a small program, but for a big program like Axiom, there 
has to be some form of structure doesn't there? 

Martin