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

[Martin Rubey]

Ralf Hemmecke <address@hidden> writes:

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

too much traffic...

> Martin Rubey wrote:

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

Well, I believe that it does make a difference for the HyperDoc replacement:
When you "browse" an operation or a constructor, you only want to see the
documentation to this particular entry, not more. It wouldn't be quite the
right thing to simply jump to the first line of the description of the
operation. 

More importantly, in HyperDoc you can select "descriptions" to get the
descriptions of all operations with a certain name. In this case, I guess that
the html page needs to be build dynamically.

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

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

Yes, BUT: it should be trivial to add another environment that serves to
execute code and pastes in the result verbatim. In fact, I believe that this
would be useful for the documentation part, too.

And that's nothing but the functionality MathAction provides and not much else
but an interactive worksheet if processing is sufficiently fast.

All that I'm saying is: forget "structured text", make everything
noweb. "structured text" and "noweb" are not that far apart as it might
seem. Syntax for interactive worksheets does not exist yet, so it should
clearly be noweb.

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

Yes. Well, "some better browser" would probably be a javascript application or
something similar that composes html pages from smaller pieces dynamically.

> > 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 please be aware of the fact that I will use Aldor only when it has become
a replacement for SPAD. So I really would like to have a HyperDoc replacement,
that makes use of the documentation in the pamphlet files. Currently HyperDoc
provides a button "Examples", it's future replacement should also have a button
"Documentation", which gives you the documented source code.)

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

Well, in the distant future I think that the maintainers documentation should
be as hyperlinked as the users 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 want the features of HyperDoc, MathAction and possibly a worksheet-like
interface. The latter is not important to me, though.

Martin