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

[Page, Bill]

On Wednesday, November 16, 2005 7:53 AM Ralf Hemmecke wrote:
> 
> Martin Rubey wrote:
> 
> > * it would be very useful - if not necessary - if you 
> >   provided a one page summary on how to use ALLPROSE for
> >   the average A{ldor,xiom} programmer, separate from the
> >   complete 225 pages documentation.
> 
> I thought there is enough overview material at the beginning
> of the ALLPROSE documentation, but seemingly one easily gets 
> distracted by the vast amount of documentation of all the make
> files so that a short section "How to work with ALLPROSE" is
> certainly a good idea.

I have read quickly through the 225 pages of documentation of
ALLPROSE and I have to agree with Martin. A short concise summary
in 1 or 2 pages that gives the basic ideas, motivation and a few
**very simple** examples is necessary. The examples can be just
partial examples - only enough to get the basic idea across.

Although I am strongly in favor of this literate programming
methodology, if there is one criticism that I would make against
it is it easily leads to excessive verbosity and it does very
little to help with documentation organization. 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. I think this is already this is
happening in the Axiom documentation.

Perhaps too much documentation is a much better situation than
none at all, but for the first time user/developer, the result
is often the same.

> However, I am not quite sure what you would like to see in such a 
> section. What do you think is missing from Section 6 "How to Start
> a New Project"?

I find it is rather difficult to say precisely what is missing
because I think that really is not the problem. The issue is more
the way the information is presented. The best analogy that I can
think of is something like this: suppose that you have been invited
to create a one page advertisement for the ALLPROSE product that
will be placed in a technical journal such as the mythical "IEEE
Advanced Computer Algebra Systems". What do you want to say to the
experienced readers who are not likely to take more than 10 minutes
at most to review your advertisement?

I think this is the sort of thing that should appear at the
beginning of an literate programming documentation - a sort of
technical executive summary.

> 
> > * maybe you can connect yourself with Eitan Gurari to 
> >   enable automatic translation to html/mathml via tex4ht?
> 
> Thank you, I would really be happy if somebody could assist 
> me with that translation.

What problems are you having using tex4ht? Have you tried any of
the other packages for converting LaTeX to HTML?

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

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.

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?

> 
>  >  However, there is one bit missing: it is necessary that we
> >   have an environment that contains Axiom/Aldor commands 
> >   which are then sent to the Axiom/Aldor interpreter and the
> >   result gets then set in verbatim. Would this be a lot of work?
> 
> Well, the aldordoc.sty is basically an agreement between
> Christian Aistleitner and me in order to introduce some kind of 
> standard for the +++ comments that are possible in Aldor. As you
> see, the +++ environments are translated into +++ comments and
> put into the .as files. So the Aldor compiler actually sees them
> and puts them into the corresponding .ao file. Unfortunately
> there is not yet a program which extracts these comments form the
> .ao file (or the .al library). This would be on my wish list.

This functionality of using the +++ comments is built-in to
Axiom's database (daase) and used by the HyperDoc browser, the
standalone 'asq' utility and accessed by commands such as )show
)what and )display in the interpreter. I haven't checked yet
whether this holds true for the +++ comments embedded in Aldor
extension for Axiom library programming, but if it is not, then
perhaps Peter Broadbery could help to make sure that this bridge
exists.

Regards,
Bill Page.