axiom-developer
[Top][All Lists]
Advanced

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

Re: [Axiom-developer] Using ALLPROSE for SPAD programming


From: Ralf Hemmecke
Subject: Re: [Axiom-developer] Using ALLPROSE for SPAD programming
Date: Tue, 22 Aug 2006 18:46:36 +0200
User-agent: Thunderbird 1.5.0.5 (X11/20060719)

Bill Page wrote:
From my point of view the objectives of using ALLPROSE are a
little different than the objectives satisfied by the Axiom
pamphlet files. As I understand it, one of the main points
is to be able to extract the comments embedded in the Aldor/SPAD
source code and typeset it along with other parts of the
documentation that are just LaTeX segments of the pamphlet
file.
Wrong. In ALLPROSE there are no places where you should write +++ or ++ inside code chunks. If you do it, ALLPROSE doesn't
care, but such documentation is NEVER extracted by ALLPROSE.

That is a pity. It means that *somebody* has to edit 1,300
packages, domains and categories and manually extract all
that documentation. In order that it can become "proper"
documentation. :(

Come on, if you like I'll write a 10 lines perl script that translates the +++ stuff into \begin{+++}..\end{+++} environments.

But there would be more to do. Take

+++ text
MyDomain: with {
    0: %;
       ++ that is a zero
    +++ This is a one.
    1: %;
    foo: () -> (); ++ and that is a foo.
} == add { ... }

In ALLPROSE that should have the format

\begin{+++}
  text
\end{+++}
<<dom: MyDomain>>=
MyDomain: with {
   <<exports: MyDomain>>
} == add {...}
@

\begin{+++}
  that is a zero
\end{+++}
%
<<exports: MyDomain>>=
0: %;
@


\begin{+++}
  This is a one.
\end{+++}
%
<<exports: MyDomain>>=
1: %;
@

\begin{+++}
  and that is a foo.
\end{+++}
%
<<exports: MyDomain>>=
foo: () -> ();
@

(OK, I guess the Perl script is going to be a bit longer.)

Now if you believe that it becomes unreadable then you forgot that we are actually writing in a literate programming style. All the empty lines above should be filled with your ideas and explain why this or that function is needed here or there, what your overall design is etc.

Wouldn't it be nice if ALLPROSE treated both occurrence
of ++ comments the same way?

NO. A strict NO. The reason is,

a) if I allow several ways for the user, he/she has to deal with several ways to write the documentation. Such a flexibility steepens the learning curve and complicates the code that has to deals with the extraction of the documentation

b) documentation is documentation why would you want to write +++ in front of each line if you can have it in a Latex environment? Code chunks should be code chunks, why would you want documentation inside it? Let's keep it simple.

c) If someone happens to write +++ comments inside code chunks ALLPROSE simply considers them as code (they are in a code chunk), but if you go all the way down, ie, compile the .spad.pamplet or .as.pamphlet file into a library then extract the +++ comments from the .ao files in that library, ALL the +++ comments are there. ALLPROSE simply doesn't use them while it is compiling to dvi. If you go the long way

.nw -> .as -> .ao -> (extract +++ comments) .tex -> .dvi

then everything would be there, but the result is the API description only.

Of course this same information is already extracted by the
SPAD compiler and stored in the Axiom database. This database
is what is consulted by Hyperdoc and the )sh command etc. I
wonder whether a system like ALLPROSE should also have such
a database component?

Yep. Going the 'long way' is exactly that. But I have not yet written the AldorDoc tool to do the "extract +++ comments".

Ralf




reply via email to

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