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 _______________________________________________ Axiom-developer mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/axiom-developer
