Re: help needed with mach.texi

[Douglas Hanks]

I'm the lowest guy on the totem pole, so I probably need to volunteer and
complete this task.  It would ultimately give me a good kick in the pants
to start learning the insides and outs of Hurd if I expect to make any
relevant contributions later on.

Marcus:  I'll need a little guideance; from there on I'm fine.

Marcus Brinkmann [Marcus.Brinkmann@ruhr-uni-bochum.de] wrote:
> 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
> 
> _______________________________________________
> Bug-hurd mailing list
> Bug-hurd@gnu.org
> http://mail.gnu.org/mailman/listinfo/bug-hurd

-- 
- Doug Hanks = dhanks(at)gnu(dot)org
  Finger dhanks(at)gnu.org for GPG key