RE: [Axiom-developer] Literate documentation

[C Y]

--- Bill Page <address@hidden> wrote:

> But the point of view
> Leo is that that the outline view is more powerful and more
> flexible than that and so the woven result is of considerable
> lesser importance.

I think this might come down to how much "domain knowledge" is expected
of the person who is to work with the code.  There is a limit to how
"plug and play" a document can be made if it is intended to be a good
background and introduction to an entire topic - my original thought
when I examined Leo was "how do I write a document that flows and can
still have pieces broken up and viewed elsewhere?"  To me it seems a
little like trying to paint/view the Mona Lisa in small chunks with no
awareness of what is next to each individual chunk.  You need to be
aware of the whole design to paint/appreciate it.

My take on Axiom is that we should try to assume as little as
functionally workable.  This is why I included an introduction to
literate programming as a concept in CL-WEB, for example - someone
needing to maintain that someday has to look no further than the
pamphlet itself for a basic introduction and references to the major
works.  For heavily mathematical subjects it would be even more
important.  Dhmatrix is one example - I find it hard to envision how
that would fit into Leo.
 
> In particular this was a follow-up to comments from Waldek,
> Gaby, and me that were critical of the creation of
> 'bookvol5.pamphlet' as literate documentation of the Axiom
> interpreter. We all expressed the opinion that 'bookvol5' was
> more difficult to appreciate even than the original code.

IIRC, the major objection to bookvol5 in its current form was that it
is "restating" the code in English rather than putting it in context.

> Of course this is from a "programmers point of view" which
> might not be the same as someone new just starting to use
> Axiom and trying to understand how it works. But I think
> programmers still need literate documentation, the question
> is just what form this should take. I am saying that the
> Knuth-style "book" is not a particularly good form of
> documentation for a programmer.

One possible approach to this would be to use the "document strings" in
code for experienced programmer information.  Lisp has document
strings, and IIRC SPAD/Aldor have multiple LEVELS of document strings. 
There are utilities to generate reference manuals using these comments,
at least for Lisp.  I have discussed this at one point with the main
CFFI author.  His code is very well commented.  I like that a lot, but
I wonder if he has in his code any background on what is an FFI, why is
it necessary, etc.  For a programmer this would be more or less useless
- if you are seeking out CFFI you probably have a pretty good idea of
what you are after.  But if someone using a program says "I wonder how
this library is talking to that one" and starts to research that
question in the code, an explanation of what an FFI is would be a big
help.

I think eventually we can re-visit the code and add
"convenience/reference manual" notes to the source code itself, but I
think such steps are secondary compared to documenting the domain
knowledge behind the code.  Most people who are likely to encounter
Axiom are beginners, and people who deal with the mathematical code may
view themselves as mathematicians rather than programmers.  The number
of experts in the world on these subjects is small, and I think
research paper style communication will be appropriate for a large part
of the audience.  I am hopeful that Axiom may some day serve as an
excellent source of advanced mathematical knowledge not locked away
behind subscription journal access controls - sort of an "online or
on-computer mathematical encyclopedia" which also happens to be
integrated with a powerful CAS.

> The question is: given current (web) technology and current
> programming practices, what form should a "literate program"
> take?

My opinion is "hyperlinked research paper".  But that's one opinion.

Cheers,
CY


       
____________________________________________________________________________________Get
 the free Yahoo! toolbar and rest assured with the added security of spyware 
protection.
http://new.toolbar.yahoo.com/toolbar/features/norton/index.php