axiom-developer
[Top][All Lists]

## [Axiom-developer] Documentation of Axiom

 From: Ralf Hemmecke Subject: [Axiom-developer] Documentation of Axiom Date: Tue, 13 Dec 2005 01:16:47 +0100 User-agent: Thunderbird 1.4 (X11/20050908)

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