Dave Burgess wrote:

> > I am keen to help you on this project.  I have some recommendations:
> > 
> > - use CVS
> > - use *roff and friends (ala mdoc) rather than Word
> 
> Ick.
> 
> I develop documentation and research technology for a living.  I have all 
> of the tools to do this in Word, and have the boss' approval to spend a 
> few hours a week documenting this.  I'm not very familiar with *roff, and
> learning a type-setting language, in addition to the research, might make 
> the project more trouble than I'd like to endure....  
> 
> I'll look into it, but I won't promise anything.

I can see now that you're willing to take a leadership role.  If this
is the case, then use what you're happy with.  If it turns out to
require more collaborative work, then perhaps something which is more
accessible would be useful.

> > - attempt to align the document with section 9 manpages
> 
> This, I think, is something I can do.
> 
> I'm trying to parallel McKusick's BSD4.4 book - that's why the outline
> is the way it is not.  My theory there is that the structure of the two
> books should be close enough that comparison between the two source will
> be easier.

Good idea.

> My goal is to produce a book that, when complete, presents a comprehensive
> view into the internals of NetBSD.  I'm not hoping, however, to duplicate
> the man pages in a conversational form.  Reaching into the man pages is a 
> good idea, though, so I will look seriously and completely changing the
> way I produce documentation.  Still, I don't want this to devolve into a 
> TOC on the front of the man -9 pages.  The trickiest part (for me, anyway)
> will be to find a balance between these two extremes.

Certainly the manpages tend to be concise.  I don't know whether I agree
with that approach though.  I have been told by many people that
manpages are too cryptic.   By the same token, I can't see why manpages
cannot be explanatory.
 
	-- Gregory McGarry <g.mcgarry@ieee.org>