help needed with mach.texi

[Marcus Brinkmann]

Hi,

if you are interested in Mach and interested in working on documentation,
here is something for you to work on.

I started to incorporate the CMU manual pages for Mach into a GNU Mach
reference manual.  This work requries three steps:

1. Incorporate all of the relevant manual page content into the texi document.
2. Go over all GNU Mach interfaces, and verify if the actual definitions
   of the RPCs and data types match the info document.  Correct the info
   document where it is wrong, add a least stubs for those which are
   lacking a documentation.  Remove those from the document which are obsolete.
3. Write missing documentation for the new interfaces, verify that
   the documentation matches the actual implementation (!) and add more
   documentation of important concepts.  Add cross references and concept
   index entries!
4. Split off the Mach parts from the GNU Mach specific parts.  Provide a
   framework that allows to collect them to a single book.  Write OSKit Mach
   specific parts that go along with the generic parts.  Collect them into a
   book.

4 is independent from 1-3.  1-3 are independant for each large section of
the whole, although at some time we might want to clean up the structure to
reflect global concepts better.  Currently, the order of things is close to
kernel_principles.ps.  Because of copyright reasons, we can not copy from
that or the other ps files, though :-/

The following table shows the progress made:
* Inter Process Communication:: Step 1 is done.
* Virtual Memory Interface::    Step 1 is done.
* External Memory Management::  Missing.
* Threads and Tasks::           Step 1 is done.
* Host Interface::              Step 1 is done.
* Processor Interface::         Missing.
* Device Interface::            Missing.

Also missing is a section on the history of Mach, and about the bootstrap
procedure.  Some more parts not documenting interfaces are also in the first
draft stage.

The current snapshot is available at
http://people.debian.org/~brinkmd/mach/mach-0.0.tar.gz

If you want to work on it, please post your intentions, and for step 1,
please follow the existing chapters in style.  Style can be discussed, but
it is better to stay with "something" consistently until the whole is
converted to a new style, rather than having a mixture of various ideas.
You don't need to know texinfo, the existing pieces show you how it is done,
and I will go over everything you submit and clean up bumps etc to achieve
consistency.

Thanks to Gibran Hasnaoui for the conversion of the Threads and Tasks
section.

Thanks,
Marcus

-- 
`Rhubarb is no Egyptian god.' Debian http://www.debian.org brinkmd@debian.org
Marcus Brinkmann              GNU    http://www.gnu.org    marcus@gnu.org
Marcus.Brinkmann@ruhr-uni-bochum.de
http://www.marcus-brinkmann.de