[Openmcl-devel] Interest in documentation reorganization?

[Dan Knapp]

> [...] but I eventually reaslized that the program in question is
> called "osx".

   That's rather amusing.  Well, excellent.

   I expect you're right with your analogy: it isn't realistic to assume 
that the
internals docs can be updated as fast as the code, but that doesn't mean
they don't have some value.  It would be surprising, actually, if 
anyone not
on the development list had a good reason for looking at them; but the
general principle is that, since there's no way of knowing what 
information
will be needed in the future, at least what's written down now won't 
have to
be rediscovered.

   Also, even if it's never read down the road, internals documentation 
is
useful immediately.  The process of writing it ensures that a developer 
has
everything clear in his own mind, and it allows other developers on the 
team
to keep pace with changes as they are made.

   This is probably all over-thinking it, though.  The most important 
reason to
have good documentation is that it gives new and prospective users a 
reason
to respect the project, and helps to attract users and developers.

   As to whether to revise and update the internals notes right now, I'd 
still say
that it's just a question of whether you think you have the time.

> In at least a few cases that I can think of (threads, for instance)
> the user-level and implementation-level documentation should ideally
> be very different.

   Well, that's certainly true.

   I've redone the way the html is built, a little bit.  It now uses a 
wrapper
.xsl file to set parameters, and Doc/ is now one .xml file which 
generates
all of the .html files.  I did it that way because it made it easy for 
me to
change the order of things, and, while I might split it up again later, 
I
don't see a strong reason to.

   Currently I'm only working with the contents of Doc/; I'm leaving the
main site (such as it is) alone.  I think it might be desirable at some
point to include the old news in the table of contents of the docs,
but I haven't thought it through yet.

   I'm pretty sure I can replace the menu.mc kludge with some xsl code,
which would be desirable as the kludge prevents the pages' real titles
from being used.

   I'm going to append for your perusal the table of contents of what 
I've got
so far.  This is very much first-draft, but it's the state I have 
things in at the
moment.  It is quite easy to change the order or grouping of material.

   You may notice that some chapters ("installation") have many
subsections, while others ("threads"; "sockets") have only one.  I 
consider
those short chapters to have equal importance to the long ones, so
they should be given equal prominence.

   Ignore that "Preface", that's the old front-page of the docs, which 
I'm
just leaving in until I'm sure everything in it is redundant.

   I'm going to try to give more informative titles to the subsections;
each title should answer the question, "When should I read this?"

   My next large undertaking will be to separate function and macro
descriptions into "dictionary" sections at the ends of their respective
chapters.  DocBook actually has a set of tags for this purpose, and can
even build an index of them automatically.

-- Dan Knapp


Preface
	1. General
	2. Obtaining OpenMCL sources
	3. Building OpenMCL for LinuxPPC or for DarwinPPC
	4. Using OpenMCL
	5. Implementation notes
	6. OpenMCL's Foreign Function Interface
	7. Interface database and translation
1. Obtaining, Installing, and Running OpenMCL
	1.1. OpenMCL system requirements
	1.2. OpenMCL installation
	1.3. Using the openmcl shell script
	1.4. OpenMCL invocation
	1.5. OpenMCL directory organization
	1.6. CVS Documentation
	1.7. OpenMCL CVS information
	1.8. Using ILISP with OpenMCL
	1.9. Using ILISP with OpenMCL - old version
	1.10. OpenMCL example programs
2. Programming with Threads
	2.1. Threads in OpenMCL
	2.2. Background terminal input in OpenMCL
3. Programming with Sockets
	3.1. OpenMCL Sockets
4. Running Other Programs as Subprocesses
	4.1. Running external programs in OpenMCL
5. Creating Your Own Stream Classes
	5.1. Extending READ-SEQUENCE and WRITE-SEQUENCE
	5.2. Multibyte I/O in OpenMCL
6. Writing Portable Extensions to the Object System  using the 
MetaObject Protocol
	6.1. Using the MOP in OpenMCL
7. The Foreign-Function Interface
	7.1. Specifying And Using Foreign Types in OpenMCL
	7.2. Foreign Function Calls in OpenMCL
	7.3. Referencing and using foreign memory addresses in OpenMCL
	7.4. OpenMCL interface database
	7.5. Using interface directories in OpenMCL
	7.6. Using shared libraries in OpenMCL
	7.7. The OpenMCL interface translator
	7.8. Case-sensitivity of foreign names in OpenMCL
8. Using OpenMCL with Mac OS X, the Darwin Kernel,  and the Cocoa GUI 
API
	8.1. Using OpenMCL under Darwin and MacOS X
	8.2. Cocoa Programming in OpenMCL
	8.3. Line termination in OpenMCL
9. Understanding and Configuring the Garbage Collector
	9.1. OpenMCL memory usage
10. Rebuilding and Developing OpenMCL Itself
	10.1. Building OpenMCL's heap image
	10.2. OpenMCL kernel build procedure
	10.3. Using OpenMCL in "development" and in "user" mode
	10.4. Debugging facilities in the lisp kernel
	10.5. Using AltiVec in OpenMCL LAP functions
	10.6. OpenMCL implementation notes