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

[Ralf Hemmecke]

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
complicated.


> > > * 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
structured.

> 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
> right?

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,

Ralf