[Axiom-developer] Re: navigating Axiom's library

[Martin Rubey]

Dear Ralf, *

I was just pondering the various approaches to the documentation issue:

As far as I understand, you are proposing a system where several (literate)
source files are compiled into one big dvi/ps/pdf/html/mathml ... file.

As you know, I think that it is necessary that we go from three documentation
formats (namely: pamphlet, hypertex, structured text) to one, namely yours.

As far as dvi/pdf/ps, i.e., printed matter is concerned, I think there is not
much left to do. The one bit missing is to enable ALLPROSE to produce different
files for the various user groups. For example a file which contains only the
usage info (as in aldordoc) and the examples for endusers.

However, for the web based documentation, there seems to be more to do - apart
from being able to produce it using tex4ht and jsmath and these matters:

> > ... we have to think about the best ways to "navigate" quickly and easily
> > through such a large complex structures as the Axiom algebra library.

> > HyperDoc does this very well. Unfortunately, HyperDoc <> MathAction <>
> > ALLPROSE. But it should be.

> I have mentioned before that I do not find HyperDoc particularly
> useful. Every time I sit down to use it I get a bad case of "browser
> shock". ... So I do badly want to see HyperDoc's features re-packaged with a
> standard web browser interface.

> The idea of being able to navigate through the Axiom database (daase files)
> easily is a very good one.

Of course, with ALLPROSE you can point at a line in the dvi viewer and jump to
the corresponding line of source code, but this is a very different matter.

Somehow we need a facility that interacts with ALLPROSE and uses the
databases. I wonder whether Aldor has similar ones... Do you know? If yes, we
have to agree on one format, so that everything works together as it should.

The net result would be a webbrowser-script, that displays the documentation
produced by ALLPROSE and adds some buttons on the bottom depending on what is
displayed currently, just as HyperDoc does it now...

Of course, there is a discrepancy between the ALLPROSE approach and the way
hyperdoc works currently:

HyperDoc uses mostly the text in the in the databases, which axiom extracts
into the appropriate database from the +++ comments when compiling the
algebra. Apart from that, one can write additional HyperTex files, which get
displayed as examples or the like.

I do not understand how hyperdoc knows whether there are example files around
or not. Is this information also in the databases?

It seems to me that we would need to modify the generation of the databases
such that the +++ comments are transformed into html or mathml with a call to
tex4ht. Or we could write a program that takes a database generated by axiom
and transforms the text it contains into html, no idea what would be easier.

Alternatively, let the databases only contain a pointer to the right file. For
example, it could contain simply the filename where the text is stored. In
fact, this looks a lot better to me. This way, the compiler would only supply
the dependencies of the operations, not their documentation. Is it a problem to
have a few thousand files in a directory?

Kai, do you think you could help?

Martin