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

[C Y]

Ralf, I know you have undertaken a number of times to explain the
ALLPROSE idea to us, so feel free to laugh at me and send me to the
archives if my questions have been answered already.  I'm trying for
the "aha!" experience with ALLPROSE's ideas but haven't gotten there
yet.

--- Ralf Hemmecke <address@hidden> wrote:

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

OK, that jibes with what I understood about ALLPROSE.  Most of our SPAD
literate programming files consist primarily of code at this stage
anyway, so the re-writes of those files will be TRUE rewrites -
incorporating ideas, research paper ideas and references, etc.  In
those conditions incorporating ALLPROSE will be a relatively minor
point.
 
> 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.

This is where I start to get a little fuzzy.  I'm still working on the
idea of code chuncks and literate programming (as one look at the Emacs
mode work will clearly show) but I thought the idea of literate
programming was to break things down to the point where the code
chuncks are clearly explained as part of the surrounding context and
don't need any special documentation themselves.  If comments are
included in the programming code as such, they are no more than
convenience notes for someone who doesn't use literate programming at
all (and perhaps a bit of a liability as such, come to think of
it.)ALLPROSE appears to make the distinction between API and user level
documentation (good) but I guess I'm not quite following how this will
work - I tend to view any user level document as distinct from any
detailed discussion of the source/file/program, although I concede this
is not an issue that Axiom as yet has any mechanism at all to handle.

Maybe a better question would be this - is it possible, using ALLPROSE,
to produce a "user handbook" of functionality intended for the user in
each package, and even better a "toplevel" summary of available
packages and their intended functionality?  If so, then I am very much
interested in digging as deep as I can into the ideas of ALLPROSE,
because I currently don't see any way for a user to discover and use
the functionality in a pamphlet except for reading the entire pamphlet,
and that's just not practical in many cases.

When I was using Mathematica in Physics years ago, my biggest single
problem was that I didn't know what I didn't know - e.g. there were
often options for commands that would do what I wanted, but I didn't
know they were there to find, let alone how to use them.  Axiom in some
ways is even worse because it is a CAS with a truly mathematical focus,
as opposed to an engineering focus.  I like this in principle, since at
some level I want to know that those issues we "ignore" in an
engineering problem have in fact been delt with sensibly and are
subject to verification of those solutions, but it makes navigation in
the system a daunting prospect.

> 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.
>
> [snip] But Tim, I hope you can live with another dependency.
> ALLPROSE heavily uses PERL. Fortunately, I just need the standard
> PERL no additional modules.

Arrgh.  Nothing against perl, but how much work would it be to
re-create the logic of ALLPROSE in Lisp or Aldor?  This might, if done
correctly, resolve the GPL (non?)issue as well, although I personally
am not particularly concerned with that detail (we use GCL, after all.)
 
> 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 principle this worries me a bit.  I personally like having
individual dvi files for each pamphlet - I had envisioned Axiom
becoming like (eventually) a conference proceeding publication with one
idea+implementation per pamphlet file, and a categorization system
based on the standard categories to make sense of it all.  It might
even tie in with Tim's literate journal idea - as papers are published
they are incorporated into Axiom and become part of both code and
documentation.  A single dvi of the algebra directory, once fully
documented, would be many thousands of pages - I usually would want to
view/print just the particular pamphlet(s) relevant to my current area
of interest.

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

This is useful for "volumes" of algebra perhaps, but I think viewing
the whole of the algebra directory this way is like trying to consume
the whole salad bar for a meal.  Most people will want only a few bits
of Axiom's literature at any one time.

I was hoping Axiom could become like the best of all worlds in
conference proceedings - grouped by subject with individual ideas
documented in academic paper style, but with those subject groupings
being always coherent and together rather than spread across 10 years
of publications.  Then when compmiled the system will assemble a user
level summary of working commands and functionality based on the
pamphlets in the system at the time, perhaps with examples incorporated
into and also used by the unit test system.

Sorry if I'm misconstruing the idea of ALLPROSE - I know my grasp of it
still isn't there yet.

Cheers,
CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com