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

[Page, Bill]

Ralf, 

On Tuesday, August 22, 2006 11:08 AM you wrote:
> Bill Page wrote: 
> > 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.

???


On Sunday, August 20, 2006 6:55 PM Martin Rubey wrote:
> ...
> Note that a (rudimentary) converter from pile to nopile is 
> included in the axiom compiler. just say
> 
> (1) -> )co test.spad )tr
>    Compiling AXIOM source code from file test.spad using old
>       system  compiler.
>    Warning: translation of an old-style source code ".spad"
>       file to a new-style ".as" file changes the old system
>       compiler. 
> If you wish to use the old system compiler for regular
> compilation, you must exit and re-enter AXIOM.
>    Creating output file with name test.as .
> #include "axiom.as"
>    Compiling AXIOM source code from file test.spad using old
>       system compiler.
>    TEST abbreviates package Test 
>    compiling exported tst : Integer -> Integer
> --)abbrev package TEST Test
> No documentation for tst
> No documentation for tst
> 
> +++ 
> Test(): with tst: Integer -> Integer;  == {
>         add {
>                 import from PositiveInteger; 
>                 import from SingleInteger; 
>                 import from String; 
>                 import from OutputForm; 
>                 import from NoValueMode; 
>                 tst(n:Integer):Integer == {
>                     for (free i) in 1..n repeat {
>                         i = 2 => 0; 
>                         output(i::OutputForm)$OutputPackage; 
>                     }
>                     0; 
>                 }
>                 
>         }
> }
> 
> Note that it makes many mistakes, but that's probably fixable.
> 
> ...
> 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. :(

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

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?

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

Agreed. I think you might find it very interesting to study
how this was handled in the Sage project. A very large
amount of program-level documentation is coded as a LaTeX
document in the docstring of each Python module. This text
is extracted and processed by LaTeX to create the 1000+ page
reference manual and also available for online help in the
interpreter.

It is not literate programming in the style of Knuth, but
is a **lot** better than what we have sprinkled throughout
Axiom's SPAD code. And this is a project that is only two
years old...

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

Again I wonder about the need for a database. The web pages
on the Axiom Wiki for example are stored in the Zope Database.
This allows pages to carry additional attributes such as the
list of "parents" that define the subtopic lattice, last editor,
dates, etc. This information is being searched dynamically to
create the left sidebar navigation for the wiki. A similar
thing could be code for navigating between pages containing
literate source code. But this does require a web site interface
and does not translate easily to a printed format.

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

In principle there is no reason why the Axiom Wiki could not
directly consult the Axiom database (daase files) the way
hyperdoc does now.

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

Sometimes I wonder just how appropriate LaTeX-oriented tools
are for this task...

Regards,
Bill Page.