axiom-developer
[Top][All Lists]

## [Axiom-developer] Re: Documentation of Axiom

 From: root Subject: [Axiom-developer] Re: Documentation of Axiom Date: Tue, 13 Dec 2005 12:31:18 -0500

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

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