RE: [Axiom-developer] Re: literate programming pamphlet files forMathAction

[Bill Page]

On Thursday, September 30, 2004 9:57 AM Ralf HEMMECKE wrote:
> 
> >> I am very much open to everything, even LaTeX, but there
> >> should be some standard of how to document with ++ and
> >> this is missing  currently!
> 
> [Tim Daly wrote:]
> > I'm interested in this thread (though buried under a huge 
> > project work at the moment). The ++ and -- comments were
> > part of the original documentation mechanism. In the long
> > term these will go away.

I am also very interested in this discussion and also
believe that the ++ -- style comments and distinction
between them should go away.

> [Ralf HEMMECKE wrote:]
> Why should they go away? Is there a way in Axiom to
> produce a hyperlinked category hierarchy? Such a hierarchy
> should be generated from the actual CODE and not some
> latex documentation around.

Yes. That is exactly how the MathAction web site works
now with wiki pages containing compiled Axiom library code.
The TouchGraph navigator using the output of the compiler
to display the dependency graph of the Axiom categories,
domains and packages (which is not actually a hierarchy,
BTW).

> If then there is some helpful documentation like the ++
> comments that describe the input/output parameters and
> approximately what the domain/category/function is doing,
> this would greatly help programmers.

Yes, this (and a lot more) will be directly available to
programmers when they navigate the hyperlinked MathAction
wiki pages containing the Axiom pamphlet files.

> 
> I don't say that this should be the only documentation,
> but it should not go away, because programmers need the
> exact interface of functions in a compact way. Sometimes
> one knows what a function is doing, but not exactly in
> which order the parameters go and what there exact 
> specification is. Putting this information away from the 
> function code is dangerous.
> 
> Of course with noweb, one can do everything nicely, but
> the documentation is lost for the Aldor compiler then.
> 

I don't see much point of giving documentation to the
compiler. Perhaps like the built-in Axiom compiler,
Aldor can be made to produce output which could be
interpreted as hyperlinks into the appropriate documentation?

> 
> [Tim Daly wrote:]
> > There will be new environments in the pamphlet file
> > which will be standardized and automatically extracted.
> > Standard environments include \begin{testcase} for
> > integrating .input file tests, \begin{concept} for
> > tagging the introduction of a new concept that needs
> > to be pushed into a semantic network (see the crystal
> > discussion in the history), etc. These stylized environments
> > will, like \begin{list}, probably have special sub-tags
> > (like \testinput and \testresult so testcases can
> > automatically verify the results).

Although this is technically possible, I think that it is
likely to fail for the same reasons that Tim gives below
for the failure of the -- ++ comment mechanism - something
that is not an integral part of the development process is
very likely to be ignored by (most) developers.

> [Tim Daly wrote:]
> > ++ and -- suffer from the usual problem of documentation.
> > Programmers will not maintain documentation tags. mostly
> > because almost nobody but the programmer ever reads code.
> > we tried to be clever about it and make the comments "live"
> > with hyperdoc (a pre-javadoc idea). unfortunately it still
> > suffers from the fact that embedded comments are not the
> > primary reason for a .spad file. I'm hoping that the 
> > pamphlet file (which makes the documentation task primary
> > and coding secondary) will encourage computational
> > mathematicians to actually write papers that include
> > working code and programmers to write real papers that
> > explain their algorithms.

Yes, I think that this is very desirable *but* I think
that it is necessary to make the documentation more
directly usable than is the pamphlet file right now. Writing
LaTeX and thinking noweb/pamphlet organization for the code
is a complex skill that has to be learned. As a result it
is often left as an "after the fact" step in the creation
and publication of new ideas. I think we need to get useful
tools more "up front". This is fairly natural when using
computer algebra in mathematics and physics. Both Maple and
Mathematica have fairly "evolved" worksheet style user
interfaces that aid in the process, but they are missing
a more directly link to publishing.

I am mildly optimistic that the MathAction approach can
do all of this. :)

>
> [Ralf HEMMECKE wrote:]
> I agree to a certain extend, but not completely. The pamphlet
> idea is wonderful, but the paper-style text is quite unhandy
> as a reference manual. An additional documentation like,
> for example,
>
> http://www-sop.inria.fr/cafe/Manuel.Bronstein/libaldor/html/node18.html
>
> would be desirable. Or can this be done already with AXIOM?

Yes, that is exactly what the MathAction interface to Axiom
will provide. See for example

  http://page.axiom-developer.org/zope/mathaction/dhmatrix

The hyperlink category and domain references are shown below the
Axiom code shown in green. For a graphical view of the links
click on the 'navigator' option at the top right of the page. See

    http://page.axiom-developer.org/zope/mathaction/TouchGraph

for more information about how to use the graphical navigator.

The layout and contents of this page is very close to what a user
will see for each pamphlet file in the system although right now
this page was generated in part manually rather than automatically
the way it soon will be when the user clicks Save after editing.
There will also be internal hyperlinks and an index for code chunks
like you see here

  http://page.axiom-developer.org/zope/mathaction/l2h

but I have a small problem right now with generating this links
when the page contains LaTeX codeing.

At this time I am still uncertain as to whether to include the
nontangle+Axiom output in the same page as the documentation,
as shown on the current dhmatrix page above, or whether to
present this in a separate page.

Regards,
Bill Page.