[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Axiom-developer] Re: navigating Axiom's library
[Axiom-developer] Re: navigating Axiom's library
Tue, 13 Dec 2005 02:27:15 +0100
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 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
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).