Date: Fri, 30 Oct 1998 11:05:43 +0100 From: Eivind Eklund <eivind@yes.no> To: Nik Clayton <nik@nothing-going-on.demon.co.uk>, doc@FreeBSD.ORG Subject: Re: RFC: Handbook reorganisation Message-ID: <19981030110542.02444@follo.net> In-Reply-To: <19981029221106.19143@nothing-going-on.org>; from Nik Clayton on Thu, Oct 29, 1998 at 10:11:06PM %2B0000 References: <19981029221106.19143@nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Oct 29, 1998 at 10:11:06PM +0000, Nik Clayton wrote:
> Folks,
> 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".
Kerberos and S/Key belongs under an explict 'Security' heading
somewhere, I think. And they're not exactly add-on applications -
especially S/Key is just something you use with the existing apps
(those that support it - I hate the SSH protocol design!)
> 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.
"Using remote serial terminals" or somesuch? Is this what you mean?
> 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.
SMB fit fine in 'Internet networking', but AppleTalk and IPX/SPX/NCP
does not. I think a 'Networking with properitary systems' or
'Networking with foreign systems' part might be in order.
> 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.
I'm hoping to one day have a 'Kernel Hackers Guide' or similar. I'm
not sure how we should handle that - pull up the 'Contributing code'
to a part 'Working with FreeBSD code' or similar?
> 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.
How will this affect anybody that want to print the FreeBSD Handbook
as an actual book? On paper, for sale in the stores...
> 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. . .
Thanks! May I suggest that you attempt to directly solicit chapters
from people, trying to get them to do it stagewise (ie, if the domain
expert don't have time to write a full chapter, at least try to get an
outline of one, etc)? (I know, it is much easier to be an armchair
general...)
Eivind.
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?19981030110542.02444>