[Axiom-developer] Documentation of Axiom

[Ralf Hemmecke]

Dear Tim,

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?

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?

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?)

Ralf