Subject: Re: I've started on the "Design and Implementation of NetBSD"
To: Gregory McGarry <>
From: Dave Burgess <>
List: netbsd-docs
Date: 07/18/2001 20:06:11
> Hi Dave,
> I had to strip the first two and last two lines off the .ps file
> for it to be useful.

Sorry.  I was using a LaserJet Postscript driver to produce the file.
'cupsd' was fine with it (it ignored the noise).

> I am keen to help you on this project.  I have some recommendations:
> - use CVS
> - use *roff and friends (ala mdoc) rather than Word


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.

> - 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.

> I have committed some jumbo patches to section 9 recently which
> cover some of these things already.  Keeping the document,
> code and manpages synchronised is critical IMHO.  In fact, it
> was be useful to have the ability to "reachover" into the manpages
> so we could share documentation.

I'll be counting on things like the man pages being correct and up-to-date.

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.

Looking forward to working with you -