man pages and handbooks

[Marc Fonvieille]

On Tue, Sep 05, 2006 at 07:34:44PM -0300, Duane Whitty wrote:
> I've been spending a lot of time recently reading how SMP works, kernel
> threads, SA/KSE, callouts, the differences between SCHED_4BSD and SCHED_ULE,
> locking, caches, etc.  I've still got a lot to learn and a lot to actually
> start trying to apply in code.
> 
> I've often thought this might be easier if some of the great material
> available in the man pages was perhaps streamlined into the evolving
> FreeBSD Architecture Handbook.  This is just my opinion of course and
> those of you with more experience than me may have good reasons for
> not doing so.
> 
> Barring any objections from the community in general and the DOC
> project comitters in particular I would like to volunteer to
> start adding some material from the man pages into the
> FreeBSD Architecture Handbook.  My first targets would be integrating
> the material on mutex(9), mtx_*(9), pthread_*(9), lock*(9), atomic_*(9),
> sched_4bsd(4), and sched_ule(4) into the material already present in the
> handbook.  I would also like to try my hand at creating diagrams to illustrate
> the data structures used in our kernel code.  Obviously as I learn more
> I will probably find more material which would be interesting to have
> integrated as well.
>
[...]

If you want to just merge/copy some manual pages parts in the
arch-handbook then you miss the point since there's no gain in
duplicating the information.  For example if you want to talk about the
ULE schedule we are not looking for a sched_ule(4) manual page copy but
a documented text covering the features, how to use it or code with it,
etc.; another example would be the USB devices, if your look at the
current chapter, the text explain how the USB stack works (it's quite
the case) but miss a part explaining how to write a simple USB (HID?)
driver.  To sum up, most of time, beside the outdated info, the book
miss the detailed information on the layout/features of a subject and
the application (driver, etc.) examples, i.e, what need a vanilla C
coder to write/port something To FreeBSD.

Marc