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

[daly]

On Sat, 2011-11-19 at 16:11 +0000, Martin Baker wrote:
> > 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? 

Frankly, I don't know. I am learning what works and what doesn't as I
go. Axiom is the largest literate program I'm aware of so there are no
examples. I get to invent the mistakes.

Volume 12 is about the Crystal. The crystal idea is that there is a core
problem. Wrapped around the problem is a crystal with many facets. Each
facet presents a different view of the core problem. My thinking is
that one facet presents a PDF view of related material, say by showing
a particular section of the book. Another facet presents related
hyperdoc material. A third facet presents related code. A fourth
facet presents related material in HTML form, with embedded video
or animations. A fifth facet would show a graph, like the domain
graph, related to the problem. You "rotate" the crystal to find the
facet that has the information you want.

So I think there is a place for all of the various representations.
They need to be driven from the core problem. To my knowledge, there
are no examples and no effort anywhere to develop a crystal and 
facets idea. So this is all just one big research experiment on 
my part.

Tim