[Openmcl-devel] docs FAQ and CVS/build cycle sections need revamping

[Hamilton Link]

The single biggest FAQ is "how do i build from CVS" and the 
documentation is only mostly correct in the sections for this. Who is 
up for rewriting it? Dan, if you will at least make the following 
rearrangements and stub something out I will try to get updated and 
accurate content put together soon, and I think everything will be a 
lot clearer for it.

I think personally that sections 1.6, 1.7, 10.1, and 10.2 should be a 
"Building OpenMCL" chapter and the 10.3-10.6 sections should be a 
separate "Modifying OpenMCL" chapter. Something like the following:

;; this chapter really should be chapter 2, given the frequency of such 
questions and the general need to keep up with changes in response to 
fixed bugs, but in order to not renumber everything in my email I've 
put it in as 1.4ish
Chapter sqrt(2).    Building OpenMCL
;; something straightforward saying that the kernel is a C program and 
is built the normal way, but that building lisp requires lisp, 
analogously to building a C compiler requires a C compiler, and so an 
old lisp image needs to be obtained to build the latest sources and 
produce a new boostrapping image and a new lisp image
         sqrt(2).1.  Conceptual model
;; corrected information about CVS, with no more than a footnote about 
where logs went that were older than a certain date, AND how to overlay 
the CVS checkout with a binary-only distro and the darwin-interfaces 
distro. ALSO where to go for a dppccl.image file if the latest distro 
doesn't have quite everything needed for bootstrapping purposes (i.e. 
in the pub/testing ftp directory)
         sqrt(2).2.  What you need, and where to get it
;; saving lisp images is something lots of people might do, but when 
building openmcl i always rebuild the kernel first, and in fact it is a 
simpler thing to do than the bootstrapping loop
         sqrt(2).3.  Building the kernel
         sqrt(2).4.  Building lisp images
;; people are going to start wanting to compile hemlock and use cocoa 
as a matter of course, this is the appropriate place for the 
instructions
         sqrt(2).5.  Building the IDE

Chapter 10.    Modifying OpenMCL
;; in point of fact developing openmcl implies that there could be a 
way to return those changes into the development line... we need to say 
what the oversight process is
         10.1.  CVS access and the check-with-GB process
;; everything else is just from the current chapter 10.
         10.2.  Using OpenMCL in "development" and in "user" mode
         10.3.  Debugging facilities in the lisp kernel
         10.4.  Using AltiVec in OpenMCL LAP functions
         10.5.  Development-Mode Dictionary

I also think that besides the new chapter after Ch.1, that Chapters 10, 
and 11 should be swapped, as Understanding and Configuring the GCer, 
Implementation Details, and then Modifying OpenMCL.
h