From owner-freebsd-doc@FreeBSD.ORG Sun Sep 24 18:14:42 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 319D516A416; Sun, 24 Sep 2006 18:14:42 +0000 (UTC) (envelope-from duane@dwlabs.ca) Received: from smtpout.eastlink.ca (smtpout.eastlink.ca [24.222.0.30]) by mx1.FreeBSD.org (Postfix) with ESMTP id 8E6EA43D45; Sun, 24 Sep 2006 18:14:41 +0000 (GMT) (envelope-from duane@dwlabs.ca) Received: from ip02.eastlink.ca ([24.222.10.10]) by mta01.eastlink.ca (Sun Java System Messaging Server 6.2-4.03 (built Sep 22 2005)) with ESMTP id <0J6300FDKZW8RC61@mta01.eastlink.ca>; Sun, 24 Sep 2006 15:12:08 -0300 (ADT) Received: from blk-224-199-230.eastlink.ca (HELO [192.168.0.103]) ([24.224.199.230]) by ip02.eastlink.ca with ESMTP; Sun, 24 Sep 2006 15:14:29 -0300 Date: Sun, 24 Sep 2006 15:13:58 -0300 From: Duane Whitty In-reply-to: <4516C36B.7030701@dwlabs.ca> To: Marc Fonvieille Message-id: <4516CAE6.40601@dwlabs.ca> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AQAAAMBnFkUNi2QB X-IronPort-AV: i="4.09,210,1157338800"; d="scan'208"; a="853449520:sNHT46853964" References: <20060905223444.GA33935@dwpc.dwlabs.ca> <20060924070721.GA961@gothic.blackend.org> <4516C36B.7030701@dwlabs.ca> User-Agent: Thunderbird 1.5.0.4 (X11/20060617) Cc: Paul Wilson , freebsd-doc@freebsd.org, Joel Dahl 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 18:14:42 -0000 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 >