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

[Ralf Hemmecke]

Hi Martin, sorry, but I am a bit behind...

Martin Rubey wrote:
> Dear Ralf, *

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

That is true for dvi/ps/pdf. HTML and friends should be hyperlinked 
anyway. Whether ALL documentation is in one big HTML file or whether 
there are several smaller pages is a minor detail for html.

As for dvi/ps/pdf I would like to group things together that logically 
form some kind of bigger entity (like, for example, all the interpreter 
code). Maybe the book volumes are a good size. But I would not restrict 
to that. Book volumes are just an application of the technology.

Basically it says:
Write a wrapper file that contains some top-level documentation and 
lists the file names that cover that topic (the file names always 
together with a 2 sentence explanation of what they are for).

I would be concerned with the compilation of the documentation, but not 
with the logic of building binary code from the sources.

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

Well, mine is ordinary noweb stuff. It is only that I imposed a bit of 
more structure that I would also like to impose on the .pamphlet files 
of Axiom (if there is common agreement--I simply don't want to waste my 
time to do something that will not be accepted.)

I like the idea of MathAction (that's where the structured text is, 
right?) MathAction serves another purpose, I think. I propose just 
something for the Axiom sources, no interactive stuff.

As I once said, I don't really like the language that pages for hyperdoc 
are written in. It is a bit to complicated for me, simply too many 
commands. I would want to replace it with aldordoc.sty + some better 
browser that extracts information about the .as sources and is able to 
navigate through the Algbra hierarchy. Well, that would be the same idea 
as hyperdoc, but not with hyperdoc but with an ordinary webbrowser.

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

I think I could do this easily. And maybe I'll even do it for the next 
release of ALLPROSE, since you keep asking for it. But, I would consider 
it a quick hack, because:
ALLPROSE produces a complete documentation for maintainers. The API 
description for users should go through the Aldor compiler. You know, 
ALLPROSE puts the +++ stuff into the .as files and hands them over to 
the compiler. So they will be in the .al library and could be extracted 
from there via

aldor -fasy -laxiom filename.ao

There is know a program missing that transforms .asy into .tex which 
would then be processed via tex4ht to produces .html resulting in an 
even more hyperlinked API documentation than the maintainers documentation.

> 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:

What would you want there? I guess, it is some interaction, right?

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

Well, I find HyperDoc useful, but only since there is nothing better at 
the moment. ;-)

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

But it matters when you are working on the code and want to find your 
way around. It saves you from looking for the filename in which the 
corresponding code would be defined/used. Rememeber there are more 
people who are not original developers and have no idea of the general 
layout of the code.

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

There is just a library format for Aldor which is a .al library of 
several machine independent .ao files. You can, however, extract all the 
information you need from these .ao files. Just produce .asy from them 
and you basically get the complete syntaxtree back.

I have not looked into the daase files, but I guess, the index.KAF and 
info files in int/algebra/*.NRLIB are a bit similar to .asy.

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

I don't know yet, but I guess, tex4ht could do the job. (But it's a bit 
hard to know, since tex4ht is not so well documented as I would like to 
see it.)

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

As I said, it should be kept that way. ALLPROSE should be considered as 
a first step to produce such a database (.al library would be sufficient).

Ralf