Date: Tue, 4 Apr 2000 22:53:05 -0500 (CDT) From: Michael Chin-yuan Wu <mwu@ece.utexas.edu> To: Nik Clayton <nik@freebsd.org> Cc: jim@freebsd.org, freebsd-doc@freebsd.org Subject: Re: Handbook: FreeBSD Internals- Request for Review Message-ID: <Pine.SOL.3.93.1000404224145.13055B-100000@tick.ece.utexas.edu> In-Reply-To: <20000404181923.A64168@catkin.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 4 Apr 2000, Nik Clayton wrote: > On Sun, Apr 02, 2000 at 11:26:28AM -0500, Michael Chin-yuan Wu wrote: > > The most up-to-date version will be on > > http://www.ece.utexas.edu/~mwu/_working_copy_new_chapter24.txt I had offered Jim to send him the SGML version. He decided that it would be better for himself to "docbook" it and I agreed. :) > 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. I agree. I think we should consolidate the currently messy documentations in the man pages for the functions, the various small documents existing on developers' own websites, and much of the docs in the www collection. > 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. Agreed. > 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. *nod nod nod* > 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? All of this should go into the same document to avoid confusion. We want just *one true source* for all the developers. And, I have another idea. :) After much work, it can become the backbone for: "The Design and Implementations of the FreeBSD Operating System" Coauthored by the FreeBSD developers. It may not be as coherent a document as the 4.4BSD one, and since we "live on the bleeding edge," it may get outdated soon. However, I still think we should publish a book of FreeBSD's own. Ideas would appreciated. :) -- keichii@bsdconspiracy.net 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?Pine.SOL.3.93.1000404224145.13055B-100000>