From owner-freebsd-doc@FreeBSD.ORG Sun Sep 24 17:42:35 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 48E3616A403; Sun, 24 Sep 2006 17:42:35 +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 DADBB43D45; Sun, 24 Sep 2006 17:42:33 +0000 (GMT) (envelope-from duane@dwlabs.ca) Received: from ip01.eastlink.ca ([24.222.10.5]) by mta01.eastlink.ca (Sun Java System Messaging Server 6.2-4.03 (built Sep 22 2005)) with ESMTP id <0J6300DD6YKB5X51@mta01.eastlink.ca>; Sun, 24 Sep 2006 14:43:23 -0300 (ADT) Received: from blk-224-199-230.eastlink.ca (HELO [192.168.0.103]) ([24.224.199.230]) by ip01.eastlink.ca with ESMTP; Sun, 24 Sep 2006 14:42:31 -0300 Date: Sun, 24 Sep 2006 14:42:03 -0300 From: Duane Whitty In-reply-to: <20060924070721.GA961@gothic.blackend.org> To: Marc Fonvieille Message-id: <4516C36B.7030701@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: AQAAAHVeFkUNi2QB X-IronPort-AV: i="4.09,210,1157338800"; d="scan'208"; a="834404743:sNHT44562800" References: <20060905223444.GA33935@dwpc.dwlabs.ca> <20060924070721.GA961@gothic.blackend.org> User-Agent: Thunderbird 1.5.0.4 (X11/20060617) 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 17:42:35 -0000 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. Best Regards, Duane Whitty