Tim, On Wednesday, October 19, 2005 8:24 PM you wrote: > ... > There is much work to be done and I have no time estimate. > Documentation is vital and good documentation takes much > longer than anyone expects.
Understood. "takes longer that anyone wants to admit", too I think. > I'm looking into parts of the system and have decided to > write some debugging techniques and documentation on > writing pamphlet files so most of my effort is going > into volume 4. Sounds good to me. > > We can try putting the volumes online. Provided they still > retain their pamphlet format (ie latex) I think it's a > reasonable idea. Yes, the pamphlet files on MathAction now have **exactly** the same format as in the source code distribution (latex, noweb markup and code). You can access the volumes on-line here: http://wiki.axiom-developer.org/book--main--1 Clicking on a volume displays it's first page (in png graphics format). You can click on either the 'pdf' or 'dvi' links to view or download the full document 'src' for the full pamphlet source 'tex' for the output of noweave 'log' for the contents of the LaTeX log file and on pamphlet files that contain code chunks you can also select a chunk name and click 'tangle' to extract the code For example of pamphlets with source code see: http://wiki.axiom-developer.org/axiom--test--1/src/algebra Please let me know what you think of this approach. > I'm a little concerned about changes that would use things > like structured text, html, or other non-latex information > in the files. Those are fine for the wiki but not for the > system files, of which the book volumes are the cornerstone > in my mind. I agree. > > Vol 5: Categories, Domains, and Package Internals > Vol 6: The compiler > Vol 7: The interpreter > Vol 8: The algebra > ... > The system would be built from the books. > Great. > Eventually modifying Axiom becomes a job of authoring or > editing a section of one of the volumes. > > I have a bit of machinery already (due to David Mentre) > that extends the pamphlet idea to "booklets". etc. > We can create our own protocols as needed. > I don't see any problem implementing that but I think we should look carefully at what doing this implies for the eventual structure of the Axiom code and documentation. More and more these days I think we need to shift to a more dynamic and richer model for source code then just the relatively static literate program document. I think one way to work towards this is through web-based services like we are building on the Axiom wiki. So instead of a "dead" book, a complex program becomes a dynamically changing web site, freely mixing source code and documentation; and allowing fast and efficient navigation, multiple "crystal" views of the same pages in different contexts etc. > > > > I wonder if there is anyone out there who would like to take > > on the task to prepare such a CD? I could help but I don't > > want to lead the effort. > > I can look into the installable CDRom issue. > I've already built iso images for ISSAC. > Well, as usual you are pretty busy and your time might best be spent other ways but ... Anyway, lets try to plan to get it out "before Christmas", ok? :) Regards, Bill Page. _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer