From owner-freebsd-doc Thu Oct 29 14:16:34 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id OAA00920 for freebsd-doc-outgoing; Thu, 29 Oct 1998 14:16:34 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id OAA00865 for ; Thu, 29 Oct 1998 14:16:01 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.8.8/8.8.8) id WAA26926; Thu, 29 Oct 1998 22:11:06 GMT (envelope-from nik) Message-ID: <19981029221106.19143@nothing-going-on.org> Date: Thu, 29 Oct 1998 22:11:06 +0000 From: Nik Clayton To: doc@FreeBSD.ORG Subject: RFC: Handbook reorganisation Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=UQ4RcSpAwQNkOnpT X-Mailer: Mutt 0.89.1i Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --UQ4RcSpAwQNkOnpT Content-Type: text/plain; charset=us-ascii Folks, What follows is my collected thoughts after staring hard at the Handbook for the past seven months. I think it's reasonably widely acknowledged that the Handbook could use some reorganisation (and, eventually, tighter editing), and this is how I'm (currently) thinking of doing it. This is long. Sorry about that. There's a lot to cover. If you'd find it easier to manage, this is also available on the web, at For reference, the old Handbook structure is listed (to the chapter level) at Note that this is the Handbook as it was 7 months ago. Some new chapters or sections have been added here or there, but there haven't been any major architectural changes in that time. The layout that I'm proposing will look something like this In some cases this lists down to the section level to make things clearer. I've attached both these files to this message for the web impaired. [ Note: When I'm talking about books, parts, chapters, and sections, I'm using the terms to mean the DocBook definitions. Briefly, a book is organised as a hierarchy like so book part chapter sect1 sectn chapter chapter ... part chapter ... Also, the precise ordering of PARTS under this layout is not up for discussion. By that I mean it's so trivial to change ("Hey, I think Printing should be number 7, not number 3" ... "OK ") that there's no point in getting bogged down it. ] Part 1: Pretty good. Covers how to install FreeBSD (could use expanding, with screenshots). A basic introduction to Unix, and how to use the ports system. "Installing applications" can be split in two -- "Installing from the ports system" and "Installing a new piece of software by hand". The latter would talk (briefly) about how to download a typical piece of software, compile it, and install it. It does need something at the front that talks about the conventions adopted in presenting the handbook (i.e., '#' = root prompt, '%' = user prompt, commands in bold typewriter font, manpages referred to as command(n), and so on). This is pretty easy to do. Part 2: System Administration Rename to "Configuring FreeBSD". This part will talk about how you configure FreeBSD and *most* of the applications that come with it. This should not (IMHO) include things like Sendmail or Printing. Sendmail is really part of the wider application set, and Printing deserves a part to itself. Create an overview section that discusses the sort of configuration knobs that can be tweaked with a FreeBSD installation, and an explanation of where to find out how to tweak those things. Break the FreeBSD configuration process into "While the system is starting", "While the system is running", and "Configuring the FreeBSD kernel". Document how to configure the kernel (done) and how to tweak the boot/run time options (/etc/rc.*, sysctl and so on). Keep disk quotas in this part. Move Security out of this part, into both the Applications and Networking parts. The IPFW discussion belongs in "Internet Communications" and the Kerberos and S/Key discussions in "Applications". Part 3: Printing Based heavily on the existing Printing chapter, and only slightly reorganised; Start with an overview chapter. Then have a "Hardware setup" chapter. This is independent of which particular spooler you're using. Then a chapter that talks about LPD. This will consist of most of the existing Printing chapter. Placeholder chapters to talk about printing use LPNG and other alternatives. Placeholder chapters to talk about Network printing. This may or may not be necessary, depending on how generic the information about the LPD spooler is. I'm thinking in particular of things like "Printing to a Windows NT printer" which isn't covered. Part 4: Network Communications Rename to "Serial Communications" Split up "Serial Communications" and "PPP and SLIP". Create a "Serial Overview" chapter, and a "Dialling in to remote hosts/receiving calls" chapter. These names are misleading. "Serial communications" can, I think, encompass high speed serial lines (i.e., the thing you'd plug into the back of a Cisco router), and you might get to a remote host using methods other than dialling (a hard wired serial line for example). Perhaps "Before using a modem with FreeBSD" is a better title? Then a "Using a modem/serial line to talk to remote hosts" chapter? The title is too wordy. Part 5: Internet Communication Create an "Internet Communication" part. Explain the basics of communicating over the Internet (IP address, gateways, routing, netmasks, ports). "PPP and SLIP" become two distinct chapters under this part. Both refer back to the "Before using a modem with FreeBSD" chapter. Also add a (placeholder) "Ethernet" chapter, for using Ethernet cards with FreeBSD Additional chapters to talk about DNS, NFS, NIS, NTP, SMTP, ... as necessary. These would talk about the protocols and prerequisites for using them, but wouldn't deal with their implementation in specific applications. That's covered in part 5 (i.e., "SMTP" would talk about what it is, how it relates to the DNS, the ports daemons listen on, the role of MTAs, MUAs and so forth, but wouldn't actually show anything from sendmail.cf. . .) Then pull some of the security information from ealier into this part in its own chapter (the firewall stuff). This is not quite right -- logically, information about SAMBA should sit in here as well. Or do we need a "NetBEUI" part as well to cover things like that? Or perhaps a couple of chapters, one called "Networking with Windows" and one called "Networking with Macs" or similar? But then that's not really a part of "Internet Communications" which is what this part is about. Part 6: Applications Create a (mostly empty) part 5 (part 4 now being "Internet Communications"). This part contains information about specific applications. Off the top of my head, "X" (and related topics, such as window managers and useful X apps), "SMTP servers" (sendmail, qmail et al), "Web servers" (Apache and others?). Also covers printing, Kerberos and S/Key. Should definitely include Quake and Doom :-) Part 7: Advanced topics Bring the "Making a port" section up to chapter level. Possibly make the "Contributing to FreeBSD" chapter a part in its own right. Create an "Emulation" chapter, and put "Linux Emulation" in there as a section, with additional section placeholders for SCO. Talk about the DOS Emulator, and pcemu. "Booting Diskless" belongs in here I think. Part 8: Contributing to FreeBSD Pull "Contributing to FreeBSD" out of "Advanced Topics" and into its own part (with everything under moving up to chapter level). Under there, reorganise the structure -- in particular, pull out the contents from the existing "How to Contribute" section and make them chapters in their own right. Move the "Source tree guidelines and policies" and "Adding new Kernel Configuration options" from the old Part 4 ("Advanced Topics") to under the "Contributing code" section. Part 9: Appendices These should become proper DocBook appendices. The Bibliography should become a proper DocBook bibliography. It should also include links to Amazon.com (or Amazon.co.uk) and FreeBSD Inc. should sign up for the Amazon Associates program to try and get money for the project. Obtaining FreeBSD should probably move into Part 1, immediately before "Installing FreeBSD". The more I look at this, the more I think that calling the Handbook a single DocBook 'book' is a mistake. Having it as a 'set' (which can contain multiple books) would be more useful. By doing this, everything moves up one level in the hierarchy. All the s listed above become s, s become s and so on. I think this makes more sense, as the documentation for FreeBSD becomes a set of books. A book that introduces FreeBSD, a book that talks about using modems with FreeBSD, a book that talks about Networking (one part would deal with TCP/IP and the Internet, one part with Windows, one part with Macs, and so on). Feedback welcomed. And yes, I am the one planning on donning the magic hat of handbook editorship, picking up my trusty copy of Emacs (+3 to manual dexterity, +3d6 to Control spells, but a massively increased chance of a fumble) and fighting the SGML elements at the end of this discussion. . . N -- C.R.F. Consulting -- we're run to make me richer. . . --UQ4RcSpAwQNkOnpT Content-Type: text/plain Content-Disposition: attachment; filename="old-layout.txt" Existing Handbook structure (to level) Part 1: Introduction Installing FreeBSD Unix Basics Installing Applications: The ports collection Part 2: System Administration Configuring the FreeBSD kernel Security Printing Disk Quotas The X Window system PC Hardware Compatibilty Localization Part 3: Network Communications Serial Communications PPP and SLIP Advanced Networking Electronic Mail Part 4: Advanced Topics The Cutting Edge: FreeBSD-current and FreeBSD-stable Contributing to FreeBSD Source Tree Guidelines and Policies Adding new Kernel Configuration Options Kernel Debugging Linux Emulation FreeBSD Internals Part 5: Appendices Obtaining FreeBSD Bibliography Resources on the Internet FreeBSD Project Staff PGP Keys --UQ4RcSpAwQNkOnpT Content-Type: text/plain Content-Disposition: attachment; filename="new-layout.txt" Proposed Handbook structure v1.1 (mostly to level, occasionally to level) Part 1: Conventions in this documentation (foreward? preface?) Introduction Installing FreeBSD - PC Hardware Compatibility Unix Basics Installing Applications: - Using the ports collection to install applications - Installing applications by hand Part 2: Configuring FreeBSD Overview - What you can configure While the system is starting While the system is running Configuring the FreeBSD kernel Disk Quotas Localization Part 3: Printing Overview Hardware setup The LPD Spooler ... The LPNG Spooler ... Printing to Windows NT Printers Part 4: Serial Communications Serial Overview Before using a modem with FreeBSD Using a modem/serial line to talk to remote hosts Part 5: Internet Communications Internet Overview - IP addresses - Gateways and routing PPP SLIP Ethernet SMTP NFS NIS NTP Security (firewalls) ? Networking with Windows ? Networking with Macs Part 6: Applications X - XFree86 / XiG - Window Managers - Useful X applications Electronic mail (SMTP) servers - Sendmail - Qmail Web servers ... Part 7: Advanced Topics The Cutting Edge: FreeBSD-current and FreeBSD-stable Kernel Debugging Emulation - Linux - SCO - DOS - dosemu - pcemu FreeBSD Internals Part 8: Contributing to FreeBSD Overview - What is needed? Bug reports Documentation Code - Source tree guidelines and policies - Changes to existing code - New code Application ports Hardware/architecture ports Money, hardware, or Internet access Donors gallery Contributors - Donors Gallery - Derived Software Contributors - Additional FreeBSD Contributors - 386BSD Patch Kit Contributors Part 9: Appendices Obtaining FreeBSD Bibliography Resources on the Internet FreeBSD Project Staff PGP Keys --UQ4RcSpAwQNkOnpT-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message