Date: Sun, 24 Sep 2006 09:07:21 +0200 From: Marc Fonvieille <blackend@freebsd.org> To: Duane Whitty <duane@dwlabs.ca> Cc: freebsd-doc@freebsd.org Subject: Re: man pages and handbooks Message-ID: <20060924070721.GA961@gothic.blackend.org> In-Reply-To: <20060905223444.GA33935@dwpc.dwlabs.ca> References: <20060905223444.GA33935@dwpc.dwlabs.ca>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060924070721.GA961>