[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Axiom-developer] Re: [Aldor-l] Ann: ALLPROSE / Suggestions

From: Ralf Hemmecke
Subject: [Axiom-developer] Re: [Aldor-l] Ann: ALLPROSE / Suggestions
Date: Wed, 23 Nov 2005 00:04:24 +0100
User-agent: Thunderbird 1.4 (X11/20050908)

Dear Bill,

In many cases it is often more difficult for the author of a complex
program (or any scientific work for that matter) to write 2 really
good pages about the work than it is to write 200 pages. As a result
 the documentation can get so verbose that it becomes inaccessible
even though it is complete.

But clearly, literate programming does not help at all here. LP is just
a tool that enables people to write documents instead of programs.
Unfortunately, the reality is the other way round. Most people find it
difficult to change their minds from programs to documents. So it would
be good to provide many more examples like dhmatrix.spad.

I think this is already this is happening in the Axiom documentation.

I recently looked at many of the pamphlet files. Most of them lack their
documentation. But you are right in some respect that Axiom is already
too complex. For example, I wanted to learn more about the building
process of Axiom. I cannot say that I really found that at the time I
was looking for it. I realised that pamphlet files have to be translated
into .dvi files via the "document" command. But that does not help very
much since one does not get the global picture.

So I started at the top-level Makefile. Honestly, that is much to

* I really want that your documentation format becomes a
replacement for Axioms Hypertex format.
Well, I would be happy if ALLPROSE goes this way.

I presume that what is most appealing to Martin about the ALLPROSE
approach is the automatic "lifting" of the +++ comments from the
source code to the documentation and vice-versa. The availability of
this documentation coupled with the ability to navigate the algebra
hierarchy of parents, ancestors, children, descendants (including
those domains that might be their own grandfathers :) and packages is
very important for both users and developers.

What I can do with just the source code is quite limited. It is
basically similar to what can be seen in the libaldor and libalgebra
documentation. However, sometimes, I'd like to see ALL the functions,
that a domain provides without clicking from one category to the other.
One needs compiler support for that. The aldordoc.sty in ALLPROSE is
only there to suggest a _convention_ of how the +++ comments should be

I like the way you have used hyperref to embed a lot of this
information directly into the documentation. I think some of this
could be quite easily grafted onto the pamphlet files that Tim uses
now for the Axiom source code, although right now none of the
sections of these pamphlet files is automatically generated.

Are you just speaking of the algebra subdirectory? Or do you mean also
other dirs?

Or can you imagine this going the other way: Can ALLPROSE as it
exists now really play the same role as pamphlet files in Axiom? I
worry that too much is "hard coded" into the way that the ALLPROSE
makefiles are structured to be easily adaptable to Axiom. Is that

I don't quite understand, what exactly you would like ALLPROSE to do.
Of course its goal is to support library writers for the Aldor language,


reply via email to

[Prev in Thread] Current Thread [Next in Thread]