ALLPROSE was: Re: [Axiom-developer] Re: patch for coercePreImagaesImages in perm.spad.pamphlet

[Ralf Hemmecke]

> > We really should switch to using ALLPROSE, it's MUCH better than the current
> > pamphlet stuff.

Thank you, Martin, for pushing this.

> augh. perhaps if/when we switch to an open source aldor. 
> i'd rather not take another 6 months away from my current work
> just to recode the system into a different literate form without
> adding additional content. i'd rather the process be incremental
> as we recode in aldor and write documentation for the domains.

Tim, there is nothing really fancy about ALLPROSE. There is no need to 
rewrite lots of text. It uses Noweb and the documentation is compiled 
through TeX so what do you fear?

However, there are a few things that have to be done until something 
like ALLPROSE can be applied to the Axiom sources.

1) ALLPROSE is currently made to support programming libraries written 
in Aldor. That basically says that it would first of all apply to the 
ALGEBRA subdirectory of Axiom. And it is probably best suited if it is 
applied during the translation/documenation of SPAD to Aldor.

2) ALLPROSE adds a few LaTeX commands in order to introduce a long 
missing convention of how the ++ comments should be documented.
That means rewriting the ALGEBRA sources and adding documentation in a 
predefined way.

3) ALLPROSE or better some ideas of it could be used also for other 
parts of the Axiom sources, but that will need some more thoughts. I had 
once started it, but got lost into the version control world and then 
had other things to do.

4) ALLPROSE is GPL2.0 and I don't want to change it (currently). So the 
way to go is to include ALLPROSE under the zips directory and add code 
to the Makefiles to extract it to the appropriate place.

> i am, however, willing to try to use ALLPROSE if someone is willing
> to do the patches to the makefiles to integrate the ALLPROSE machinery
> as well as rewriting one of the files into ALLPROSE. That's a big task.

I'll do this if I find time. It is certainly a big task for someone not 
so familiar with that machinery. But Tim, I hope you can live with 
another dependency. ALLPROSE heavily uses PERL. Fortunately, I just need 
the standard PERL no additional modules.

> an even more useful subtask would be to recode the literate tool into aldor.
> then we can use and enhance our own literate tool without requiring the
> awk/gawk/nawk/sed/perl/C pile.

If someone is going to do this, then I would very much like to keep as 
compatible as possible to noweb.

> it might be easier to accomplish an ALLPROSE rewrite once i finish the
> next release of volume 4 of the books. in response to a criticism,
> i've been trying to update the "developer's guide" (volume 4) to
> include a detailed description of the build process. once that
> completes i'm going to clean up volume 4 some more and add it to the
> release. of course, adding ALLPROSE means rewriting this description
> but that will have to happen anyway.

Once again, I don't think that adding ALLPROSE means lots of rewriting.
It rather means to group files together to get one big .dvi for each 
group, for example for the algebra or interp directory, instead of one 
.dvi for each .pamphlet file. In the ALLPROSE (documentation) view. 
.pamphlet files are rather considered to be like .tex files that are 
included into a master document. The gain is that one can hyperlink over 
different .pamphlet files (well, of course one has to tag at certain 
places, for example using the \defineterm and \useterm commands.

Ralf (the author of ALLPROSE)