Re: [Axiom-developer] RE: Another question

[Ralf Hemmecke]

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

\addefinename{foo: Type1 -> Type2}{...}{...}{...}

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