[Top][All Lists]

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

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

From: Ralf Hemmecke
Subject: [Axiom-developer] Re: navigating Axiom's library
Date: Tue, 13 Dec 2005 02:27:15 +0100
User-agent: Thunderbird 1.4 (X11/20050908)

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

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


reply via email to

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