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

[Ralf Hemmecke]

> To deal with pile syntax maybe we could make use of the
> SPAD to Aldor translation option built into Axiom that
> you mentioned in another thread? Even if it is not perfect,
> perhaps it is good enough to enable ALLPROSE to more easily
> extract the necessary information?

Don't leave me in the dark. Specify exactly what you want to do/achieve 
otherwise I cannot follow.

> > For compiling, we would have to change the extension .as to 
> > .spad and change calls to aldor to axiom. This is beyond my
> > knowledge of allprose though.
>
> > 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. Instead you write the 
documentation into a \begin{+++} ...\end{+++} environment. And all that 
appears in the Latex part of the noweb file. Of course, inside that 
environment you use latex as usual, but you should not just write 
arbitrary latex, you should follow some style.

\begin{+++}
  \begin{adusage}
     -- write here aldor code to demonstrate hoe the function type
     -- is used in a common situation (kind of example code)
  \end{adusage}
  \begin{adparameters}
    % Describe here the input parameters by using
    % \adparameter{foo: A->B} instead of \item
  \end{adparameters}
  \begin{addescription}{Short docu goes here}
    Extensive documentation of the function/type
  \end{addescription}
  \begin{adexceptions}
    % Use \adthrows{SyntaxException} instead of \item to
    % describe all the exceptions this function throws.
  \end{adexceptions}
  \begin{adremarks}
    % Here you should mention exceptional stuff, maybe your function
    % works in a destructive way
  \end{adremarks}
  \begin{adseealso}
    % Give links to relates things.
  \end{adseealso}
\end{+++}

If you don't follow that convention/structure, it's also fine, but then 
it is the same as it is now. Every one invents his/her own style for the 
+++ comments and it is hard (if not impossible) to write good tools that 
handle all the various stiles.

> And also to create appropriate hyperlinks to this stuff.
> Is that right? In that case, in the end will it be at least
> a partial replacement for the hyperdoc browser?

Right. That part of ALLPROSE aims at replacing hyperdoc. But as I said 
before, I would rather like to take a set of libraries, extract all the 
+++ comments and then produce a hyperlinked document (website or such) 
as an API description just from the libraries. No .as source code should 
be needed.

> I think we need to talk more about how this would work both
> in a stand alone desktop environment and on the Axiom Wiki.

The stand alone way, I just describe above. The Wiki way is maybe as 
simple as extracting the +++ environments and the corresponding code 
chunk and putting it together. But note, in order to get links from one 
piece of code to another you have to noweave all the files together (for 
getting links inside the codechunks) and latex them all together for 
latex taking care of the hyperlinks across different files. Maybe the 
latter could also done separately but sharing .aux files, but that is 
beyond my abilities.

Ralf