> I'd like to introduce some kind of standard to the documentation of > Axiom a bit similar to what I have done in ALLPROSE. I know that this > will be a lot of work, but I believe it is really necessary. At the > moment I don't easily find in the Axiom tree what I am looking for. > (I should perhaps say that I am usually not online when I work on Axiom, > so MathAction does not help me.) > > But before I make my hands dirty, I'd like to learn a bit more about the > current structure and your plans, Tim, of how this should be developed > further. > > As I understand, there should be several book volumes treating the > various parts of axiom. (I only don't know where in the source tree I > can find those volumes. I use axiom--main--1--patch-46 at the moment.) > I can only see src/interp/bookvol5.pamphlet. That makes me think that > each directory corresponds to a book volume. However, I am somehow sure > that this is not (yet) the case. Is it planned that way?
The books were being developed in arch under book--main--1, a separate branch (see http://arch.axiom-developer.org) but since the material in the book is the actual source code for the system it is not practical to develop them in a separate branch. One effort I've been making is to walk backward thru the email archive to find useful emails and add them to the books. See the bottom of each file for the appends. These emails need to be incorporated where they fit. Axiom Volume 1: Tutorial is about to be published by lulu.com I have the "proof" version coming in the mail any day now. --patch-47 contains the source and pdf for the lulu version in src/doc Once the proof version has been reviewed it should be on sale. (the proceeds will likely go to the axiom foundation) I expect this to be available in the next week or so. Volume 2: Programming is in arch under book--main--1. I've started rewriting this from scratch. I have permission from Joel Cohen to quote from his texts. For the programming example in the book I'm developing a "Cohen Algebra" which is a tree-structured expression language that everyone keeps asking about. At least that is the current plan. These things change as time progresses. (Cohen, Joel, "Computer Algebra and Symbolic Computation: Elementary Algorithms" A.K. Peters (2002) ISBN 1-56881-158-6 and Cohen, Joel, "Computer Algebra and Symbolic Computation: Mathematical Methods" A.K. Peters (2002) ISBN 1-56881-159-4) Volume 3: Reference is in arch under book--main--1 Volume 4: Developers Guide is in arch under book--main--1. This gets updated whenever a mailing list discussion opens another topic. Volume 5: Interpreter is being developed. It will take a long time. The first part of this work showed up in --patch-46 and now has engulfed a few more interpreter files. The work is slow going because of the volume of documentation that needs to be written. Working pieces of this will dribble out with each --patch Volume 6: Compiler -- title only Volume 7: Graphics -- title only Volume 8: Hyperdoc -- title only Volume 9: Algebra is where I'm hoping you'll take the lead. Find research papers and PhD thesis work and get permission to use it for documentation of the theory. we have permission to use trager's thesis work and bronstein's thesis work which covers most of the integration theory. William Sit has done the PODE work and is a likely source of good theory as well as good code. Larry Lambe is also a good source along with Cliff Williamson, Patricia Gianni and numerous other "friends of axiom". Volume 10: Numerics is in process and will also take a long time. I have permission from a couple authors of research papers in numerics to quote their work and I'm in the process of doing that documentation as well as looking for other sources of theory. there is a lot to learn here and the theory is most enlightening. And, oh by the way, i'm trying to get it to work correctly. > > As I see now bookvol5.pamphlet includes quite a lot of code, but it does > not incorporate the other pamphlets under src/interp. Intentionally? > I assume that also the other pamphlets should eventually be included > into bookvol, right? time, time, time.... the process involves ingesting a file, rearranging it so it fits the logical progression, fully documenting it, and at all times making sure the system still builds with the newly rearranged files. it is agonizingly slow and very tedious to do a quality job. and it is hard to "write for the reader" rather than "write for the machine". plus there is so much to understand if you're going to explain a small piece of code. i figure that the whole process for volume 5 will take about a year or more. along the way volumes 6, 7, and 8 will get broken out as the parts of the system get combed into their proper piles. and each of those volumes will take a while to write. the graphics routines will have to be reverse-engineered and documented. > > So I like to suggest the following conventions. > > * Convention 1: > There is a bookvoli.tex.pamphlet file (for each i) that is intended as > the main entry point for a bookvolume. It contains a chapter/section > that list all the files that are relevant for that volume together with > a short explanation of what each file is about and later includes those > files (via LaTeX \input). bookvoli.tex.pamphlet is responsible for > \documentclass{book} > \usepackage{axiom} > \begin{document} > > and > > \printindex > \bibliographystyle{alpha} > \bibliography{axiom} > \end{document} > > > * Convention 2: > There is one axiom.bib.pamphlet file for all bibliographic data related > to these axiom book volumes. > > > * Convention 3: > Each "ordinary" .pamphlet file contains just text that would normally go > between \begin{document} and \end{document} and matches the following > template: > \begin{History} %chronological order, similar to ChangeLog files. > \logitem{DATE1}{AUTHOR1} DESCRIPTION1 > \logitem{DATE2}{AUTHOR2} DESCRIPTION2 > \end{History} > \begin{abstract} ... \end{abstract} > \begin{ExecutiveSummary} ... \end{ExecutiveSummary} > \begin{Content} ... \end{Content} > > > * Convention 4: > Each "ordinary" .pamphlet leads to a section in the book whose name is > automatically given by the filename. > (There is no \chapter command appearing a .pamphlet file.) > > > * Convention 5: > Either each bookvolume corresponds to one sub directory of the src > directory or there is a book directory at the same level as the src > directory. The book-dir should contain all bookvoli.tex.pamphlet files > together with axiom.bib.pamphlet and axiom.sty.pamphlet. > (I prefer the book directory.) > > > * Convention 6: > LaTeX commands should be preferred to TeX equivalents. > The definition of new LaTeX should be kept very local and at best > avoided at all. > Style related commands should be avoided (like \hspace,\vspace,\newpage, > etc.) > > Is there someone against those conventions? Where should we write them > so that they would be common knowledge? > > I am sorry if there are already some conventions in Axiom that I have > not found and thus I am not aware of them. (Pointers?) > the "conventions", if you can call them that, are just what seemed to make sense at the time. since "exposing" my boilerplate here i've since learned a bit and changed how i do things. (e.g. \printindex) i agree that we need to discuss and complain about them as this is the only way to develop a group mindset. but the conventions are hard to invent without real situations. hyperlinking and the endpaper discussion is a good example. Bill Page's work is really driving a lot of new constraints on this. for the 5th volume i've been slowly merging files and re-sorting the code into a more logical structure. there are chapters on various topics (which you can already see in the --patch-46 version) just as you'd expect in any book. eventually the interpreter, compiler, graphics, and browser will each be in their own books and not all globed together in src/interp. at which point we should be able to replace/upgrade/rewrite/extend the compiler without breaking the rest of the world. the bibliography stuff i use is broken and i have to spend a little time on bibtex to incorporate src/doc/axiom.bib properly. it used to work but apparently i lost the thread somewhere. i fully agree that we should create a single bibtex file with a fully annotated bibliography. in fact, we should probably put out a call for annotated entries of existing works that could be reference materials. constructing a good annotated computer algebra bibliography would be worthwhile in itself. old latex/new latex? who knows. \eject was the only command i knew until you mentioned \newpage. i've started recoding \eject into \newpage when i open a source file for other changes. but either one works so it's purely a matter of style. we'll get flak eventually because THIS version of axiom today will use "OLD" commands tomorrow when latex17m arrives. i'd suggest that you try to write volume 9 as a real book that includes real algebra files with real documentation that still works in a real system and see what comes of the effort. clearly the conventions used in the algebra are going to be a dominant force throughout the rest of the system and you get to make them up as you go along. it may turn out that the algebra conventions are wildly different from the rest of the system because of your ALLPROSE technology. but that's ok as long as it builds, it works, and the algebra is fully documented. volume 9 is probably a 5 year effort. t _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer