man pages and handbooks

[Duane Whitty]

Duane Whitty wrote:
> Marc Fonvieille wrote:
>> 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.
>>>
>> [...]
> 
> Hi,
> 
> First let me say thanks for your interest and feedback.
> Input from experienced people such as yourself is very,
> very appreciated.
> 
> I'm CCing docs@ so that the other interested or potentially interested 
> parties can stay involved.
> 
>>
>> 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,
> 
> I agree.
> 
>> 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.
> 
> I somewhat agree but I also don't believe that the
> Architecture Handbook is the best location for detailed
> tutorial information on how to develop for a specific
> subsystem; Just my opinion.  Is that not be what the
> Developers' Handbook is for? [Not meant as a rhetorical
> question]
> 
>   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
> 
> 
> I guess my understanding of the FreeBSD Architecture
> Handbook is that it tries to answer the questions
> 
> a) What does a particular subsystem do?
> 
> b) How are the goals of this subsystem accomplished
>    i.e., what are its data structures, what are its
>    algorithms?
> 
> c) Why does the subsystem use the data structures and
>    algorithms that it does?  What are the trade-offs with
>    alternative methods and perhaps even the Handbook should
>    discuss past methods which did not work and why.
> 
May be the above should also include, in the same document,

   c.1) What doesn't work as well as we'd like it to in this
        subsystem?

   d) When and how should I use a particular subsystem

   e) Example code for using a particular subsystem

   f) Debugging methods specific to each subsystem

Best Regards,

Duane Whitty

> Best Regards,
> 
> Duane Whitty
>