On Wednesday, November 16, 2005 7:53 AM Ralf Hemmecke wrote: > > Martin Rubey wrote: > > > * it would be very useful - if not necessary - if you > > provided a one page summary on how to use ALLPROSE for > > the average A{ldor,xiom} programmer, separate from the > > complete 225 pages documentation. > > I thought there is enough overview material at the beginning > of the ALLPROSE documentation, but seemingly one easily gets > distracted by the vast amount of documentation of all the make > files so that a short section "How to work with ALLPROSE" is > certainly a good idea.
I have read quickly through the 225 pages of documentation of ALLPROSE and I have to agree with Martin. A short concise summary in 1 or 2 pages that gives the basic ideas, motivation and a few **very simple** examples is necessary. The examples can be just partial examples - only enough to get the basic idea across. Although I am strongly in favor of this literate programming methodology, if there is one criticism that I would make against it is it easily leads to excessive verbosity and it does very little to help with documentation organization. In many cases it is often more difficult for the author of a complex program (or any scientific work for that matter) to write 2 really good pages about the work than it is to write 200 pages. As a result the documentation can get so verbose that it becomes inaccessible even though it is complete. I think this is already this is happening in the Axiom documentation. Perhaps too much documentation is a much better situation than none at all, but for the first time user/developer, the result is often the same. > However, I am not quite sure what you would like to see in such a > section. What do you think is missing from Section 6 "How to Start > a New Project"? I find it is rather difficult to say precisely what is missing because I think that really is not the problem. The issue is more the way the information is presented. The best analogy that I can think of is something like this: suppose that you have been invited to create a one page advertisement for the ALLPROSE product that will be placed in a technical journal such as the mythical "IEEE Advanced Computer Algebra Systems". What do you want to say to the experienced readers who are not likely to take more than 10 minutes at most to review your advertisement? I think this is the sort of thing that should appear at the beginning of an literate programming documentation - a sort of technical executive summary. > > > * maybe you can connect yourself with Eitan Gurari to > > enable automatic translation to html/mathml via tex4ht? > > Thank you, I would really be happy if somebody could assist > me with that translation. What problems are you having using tex4ht? Have you tried any of the other packages for converting LaTeX to HTML? > > > * I really want that your documentation format becomes a > > replacement for Axioms Hypertex format. > > Well, I would be happy if ALLPROSE goes this way. I presume that what is most appealing to Martin about the ALLPROSE approach is the automatic "lifting" of the +++ comments from the source code to the documentation and vice-versa. The availability of this documentation coupled with the ability to navigate the algebra hierarchy of parents, ancestors, children, descendants (including those domains that might be their own grandfathers :) and packages is very important for both users and developers. I like the way you have used hyperref to embed a lot of this information directly into the documentation. I think some of this could be quite easily grafted onto the pamphlet files that Tim uses now for the Axiom source code, although right now none of the sections of these pamphlet files is automatically generated. Or can you imagine this going the other way: Can ALLPROSE as it exists now really play the same role as pamphlet files in Axiom? I worry that too much is "hard coded" into the way that the ALLPROSE makefiles are structured to be easily adaptable to Axiom. Is that right? > > > However, there is one bit missing: it is necessary that we > > have an environment that contains Axiom/Aldor commands > > which are then sent to the Axiom/Aldor interpreter and the > > result gets then set in verbatim. Would this be a lot of work? > > Well, the aldordoc.sty is basically an agreement between > Christian Aistleitner and me in order to introduce some kind of > standard for the +++ comments that are possible in Aldor. As you > see, the +++ environments are translated into +++ comments and > put into the .as files. So the Aldor compiler actually sees them > and puts them into the corresponding .ao file. Unfortunately > there is not yet a program which extracts these comments form the > .ao file (or the .al library). This would be on my wish list. This functionality of using the +++ comments is built-in to Axiom's database (daase) and used by the HyperDoc browser, the standalone 'asq' utility and accessed by commands such as )show )what and )display in the interpreter. I haven't checked yet whether this holds true for the +++ comments embedded in Aldor extension for Axiom library programming, but if it is not, then perhaps Peter Broadbery could help to make sure that this bridge exists. Regards, Bill Page. _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer