From owner-freebsd-doc@FreeBSD.ORG Sun Sep 24 07:07:32 2006 Return-Path: X-Original-To: freebsd-doc@freebsd.org Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7C6FA16A407 for ; Sun, 24 Sep 2006 07:07:32 +0000 (UTC) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (blackend.org [212.11.35.229]) by mx1.FreeBSD.org (Postfix) with ESMTP id 63F5D43D49 for ; Sun, 24 Sep 2006 07:07:30 +0000 (GMT) (envelope-from marc@blackend.org) Received: from gothic.blackend.org (gothic.blackend.org [192.168.1.203]) by abigail.blackend.org (8.13.4/8.13.3) with ESMTP id k8O77MQb049325; Sun, 24 Sep 2006 09:07:22 +0200 (CEST) (envelope-from marc@abigail.blackend.org) Received: from gothic.blackend.org (localhost.blackend.org [127.0.0.1]) by gothic.blackend.org (8.13.8/8.13.3) with ESMTP id k8O77Mse001051; Sun, 24 Sep 2006 09:07:22 +0200 (CEST) (envelope-from marc@gothic.blackend.org) Received: (from marc@localhost) by gothic.blackend.org (8.13.8/8.13.3/Submit) id k8O77L4o001050; Sun, 24 Sep 2006 09:07:21 +0200 (CEST) (envelope-from marc) Date: Sun, 24 Sep 2006 09:07:21 +0200 From: Marc Fonvieille To: Duane Whitty Message-ID: <20060924070721.GA961@gothic.blackend.org> Mail-Followup-To: Duane Whitty , freebsd-doc@freebsd.org References: <20060905223444.GA33935@dwpc.dwlabs.ca> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20060905223444.GA33935@dwpc.dwlabs.ca> X-Useless-Header: blackend.org X-Operating-System: FreeBSD 6.2-PRERELEASE User-Agent: Mutt/1.5.11 Cc: freebsd-doc@freebsd.org Subject: Re: man pages and handbooks X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 24 Sep 2006 07:07:32 -0000 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