[Axiom-developer] Re: noweb "bug" (was: article "standard" header/footer)

[root]

> But what matters is that there is just a link on the website telling 
> about book--main--1. I cannot remember that I have read much about the 
> different volumes that should be written. So why should I check out 
> book--main--1 if I am new to Axiom and just want to learn how I could 
> contribute? I don't think new developers would want to work on the book 
> in the first place.
> 
> But why is that branch interesting?
> 
>  >Axiom Volume 1: Tutorial of Axiom
>  >Volume 2: Programming
>  >Volume 3: Reference
>  >Volume 4: Developers Guide
>  >Volume 5: Interpreter
>  >Volume 6: Compiler -- title only
>  >Volume 7: Graphics -- title only
>  >Volume 8: Hyperdoc -- title only
>  >Volume 9: Algebra
>  >Volume 10: Numerics
> 
> Can you see Volume 4? THAT is what a new developer would be looking for 
> (IMHO, of course). Unfortunately vol4 is mainly non-existing.
> 
> Tim wanted me to take over volume 9, but after getting an overview of 
> the volume tiltles I think a Developers Guide is much more needed than 
> the Algebra part (although I rather like to do some algebra), in order 
> to get potential new developers more quickly into the system. The 
> biggest problem that Axiom has is the number of active developers. If I 
> count correctly then one decimal digit is enough. That is, of course, 
> nothing given the size of Axiom.
> 
> If the Developers Guide never goes to press, I don't care. It should be 
> evolving and fix certain conventions/standards that the current 
> developers agreed upon and that every developer should follow.
> For example, also the build process could be described there.
> 
> If I understand correctly every sources of Axiom are under the src 
> directory. So I suggest, Tim, you put all the bookvolume?.pamphlet under
> axiom--main--1/src/doc. And make a note in the top-level README about 
> the availability of the src/doc directory with all its volumes. I would 
> then start to work a bit on volume 4 in order to demonstrate how my 
> documentation ideas are. If most of the current developers find that 
> form attractive I could extend to the other volumes.
> 

the whole book came out in april 2004 and there were great plans
to publish it on lulu.com. however we ran into the fact that
lulu has a 700ish page limit and the book is over 1000. plus
we were muttering about adding a CD so the whole lulu push stalled.

next we decided to split the book into 3 volumes: tutorial, 
programming, and reference. rather than ship 2 copies of the
book in the source tree it was broken off into a separate
project. as part of that project i added volume 4, the developers
guide which the original axiom did not need.

in order to capture the accumulated wisdom of the project i started
going back over the email archive and collecting any email that would
apply to each volume. these are appended to the end of the volumes
at the moment. when the volume rewrite occurs these would be added
and blended. there is still much to be done here as there is a lot
of mail to review.

i've been slowly hacking the book project and recently finished
the first volume. it is on lulu.com now and i should have the
proof copy arrive before the weekend. if the proof copy looks
ok then i can open it up for general sale. the bookvol1.pamphlet
and bookvol1.pdf files are part of --patch-47 (in src/doc) which
will be uploaded at the end of the month. 

i've started in on volume 2, the programmers guide which will 
require a complete rewrite. i've outlined it and am writing a
programming example that will be carried throughout the book
(a cohen algebra which i mentioned in a previous posting)

if you're interested in volume 4 go for it. send email and i'll
help you with the details and the writing. the book--main--1
branch is probably better than the axiom--main--1 branch because
we can update more frequently and the changes can be broken for
a long time. we can also mirror them in src/doc every time the
main system update occurs. and i can update the README.

eventually the book--main--1 branch will go away and the book
volumes will be a standard part of the source tree (indeed, in
the fullness of time they WILL be the source tree).

t