axiom-developer
[Top][All Lists]

## Re: [Axiom-developer] RE: Another question

 From: Ralf Hemmecke Subject: Re: [Axiom-developer] RE: Another question Date: Tue, 22 Aug 2006 15:35:08 +0200 User-agent: Thunderbird 1.5.0.5 (X11/20060719)

Hi Martin,

On 08/22/2006 02:45 PM, Martin Rubey wrote:

Ralf Hemmecke <address@hidden> writes:


Martin wrote:



why won't we use ALLPROSE?




I simply have the suspicion that Martin talks about pamphlet files of the form
.spad.pamphlet and anybody else means pamphlets with general content so also
.lisp.pamphlet or Makefile.pamphlet. Am I wrong?


Oh, yes you are right. I had only SPAD in mind. On the other hand, you do
document your perl and Makefile stuff with ALLPROSE too, so, I guess that we
can focus on the differences between Aldor and SPAD.


Aha. Maybe you were misled.

Maybe it is not so clear, what ALLPROSE actually is. The goal is to support the writing of Aldor libraries. But ALLPROSE itself is a program (or a collection of programs if you look deeper into it) and so it should also be documented properly using a LP style. That is what you see if you say

make include-allprose-documentation
make dvi


without the first make you only get the documentation of the library, and I guess most people are just happy with it, but the documentation of ALLPROSE itself always sleeps somewhere in the background and can be awakened.


In some sense you are right that I would like such a system for all of Axiom. But for now I cannot do this since I simply do not yet understand the Axiom build process. You can see ALLPROSE as a small example of where I want to see the Axiom sources in the future. You type "make dvi" at the top-level and get a (probably HUGE) document that describes all the sources, the buildprocess and the library code (and yes, it describes also how "make dvi" works). But that is a big task and it has to fight agains lots of legacy code. I cannot simply introduce some conventions because they might conflict with some part of Axiom deep deep into the jungle (which, of course is currently undocumented). So first comes the documentation (or an experimentation in some svn-branch). But it's a super long way to go.



All the current pamphlet stuff is legacy code. It simply doesn't fit so
easily into ALLPROSE, yet making it available in an HTML form should be
simple enough before we go the ALLPROSE way.


OK. Although I think it would be high time to move from pamphlet files to
ALLPROSE files. After all, nothing forces us to use all the features of
ALLPROSE right away. The only thing we *have* to do is to transform the ++ and
+++ bits into +++ environments, because otherwise hyperdoc won't work anymore.



Oh yes, good suggestion. But again, you speak just of the .spad.pamphlet files.


Anyway, you are right that all new code should follow the few simple guidelines that Christian and I have worked out. You can find it in ALLPROSE in the description of aldordoc.sty.


And as Bill pointed out, ALLPROSE is an environment for writing libraries. As
I understood, making pamphlets available as HTML has nothing to do with
libraries. At least not at the moment.


What? In what way is DHMATRIX different from a library?



Maybe, I am wrong, but for me DHMATRIX is just a domain. A library is something like libaldor, libalgebra, libaxiom.


No no, the conventions are quite OK. No way we are going to write yet another
SPAD parser. As far as I understand, since ALLPROSE literally copies the +++
environment into a +++ section, there is no need to adhere to the ALLPROSE
conventions at first.



OK. If you want. \begin{+++} ... \end{+++} should be written just in front of the chunk you want to document. If ALLPROSE finds a

define CategoryName(...): Category ==

or

DomainName(...): ...


in that chunk, then that corresponds to \atthistype. (And, yes Martin, that can be replaced on the fly by the appropriate \adtype{DomainName}, but that is only half of the story.)

Other types of chunks look like

foo: Type1 -> Type2;


So they should look like function of constant declarations in a with part. The +++ environment then is associated to the name foo.


That is not too hard. The problem only is that such a "foo" line has to be one line. It is an important restriction, because the whole line is translated into a command



and later used to distinugish a link to that function from a link to a function

foo: % -> Type2


Even note that ALLPROSE allows to have two domains A and be defining the same function foo. One can writing \adname{foo} is ambiguous, but \adname[A]{foo} or even better \adname[B]{foo:%->Type2} would be more appropriate. Don't worry about the %. A script takes care before latex has a chance to see it.

Ralf