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 <[EMAIL PROTECTED]> 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 _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
