Date: Tue, 4 Apr 2000 18:19:23 +0100 From: Nik Clayton <nik@freebsd.org> To: Michael Chin-yuan Wu <mwu@ece.utexas.edu> Cc: dillon@backplane.com, nik@freebsd.org, briggs@ninthwonder.com, jim@freebsd.org, freebsd-doc@freebsd.org Subject: Re: Handbook: FreeBSD Internals- Request for Review Message-ID: <20000404181923.A64168@catkin.nothing-going-on.org> In-Reply-To: <Pine.SOL.3.93.1000402112529.9056A-100000@tick.ece.utexas.edu>; from mwu@ece.utexas.edu on Sun, Apr 02, 2000 at 11:26:28AM -0500 References: <Pine.SOL.3.93.1000402112529.9056A-100000@tick.ece.utexas.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Apr 02, 2000 at 11:26:28AM -0500, Michael Chin-yuan Wu wrote: > I have finally finished editing and rewriting the > FreeBSD Handbook's section on the FreeBSD VM System > > The most up-to-date version will be on > http://www.ece.utexas.edu/~mwu/_working_copy_new_chapter24.txt Looks good. I assume you've been doing this in DocBook, and that's just the result of converting it to text. > This document is very long. What should we do about it? > A. Split it into several chapter. > B. Leave it as is. C. Create the "FreeBSD Hackers Handbook" I favour option C. :-), possibly calling it the "FreeBSD Developer's Handbook" instead. The <sect1>s in your doc then become <chapter>s in their own right. Trying to stuff everything in to the Handbook is, IMHO, a bad idea. The existing Handbook can be the "Users' Handbook", this new document can be for developers. The two audiences are separate. Other topics for a developer's handbook would be "Writing KLDs", "Writing device drivers", "Writing syscons screensavers", ... Probably a structure akin to: Introduction Architectural Overview The Kernel The VM System IPv4 IPv6/IPsec [...] Kernel Loadable [ er, what does the 'd' in 'kld' stand for? ] Syscons We might be able to pull in chapters 21 ("Adding new Kernel Configuration Options") and 22 ("Kernel Debugging") as well. 21 isn't really needed in a user-level document, although I can see a case for keeping 22 in the main Handbook. FWIW, IMHO Chapter 4.4 ("Making a port yourself") can be ripped out of the Handbook and in to its own "Porters Handbook"). It's a huge amount of text, most of which isn't useful to a 'normal' FreeBSD user. The "Contributing to FreeBSD" chapter can then point people at these documents ("Hackers Handbook", "Porters Handbook", "FDP Primer") depending on what potential contributors want to do. Thoughts? N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000404181923.A64168>