From owner-freebsd-doc@FreeBSD.ORG Mon Dec 6 21:16:39 2004 Return-Path: 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 9A6CE16A4CF; Mon, 6 Dec 2004 21:16:39 +0000 (GMT) Received: from mail.freebsdmall.com (ns1.freebsdmall.com [69.50.233.146]) by mx1.FreeBSD.org (Postfix) with ESMTP id 6FC6943D6A; Mon, 6 Dec 2004 21:16:39 +0000 (GMT) (envelope-from murray@freebsdmall.com) Received: by mail.freebsdmall.com (Postfix, from userid 2074) id 53AB31CDA6; Mon, 6 Dec 2004 13:23:57 -0800 (PST) Date: Mon, 6 Dec 2004 13:23:57 -0800 From: Murray Stokely To: Nik Clayton Message-ID: <20041206212357.GE84191@freebsdmall.com> References: <20041205114254.GD23252@clan.nothing-going-on.org> <41B3617B.3080507@centtech.com> <20041206192017.GE72462@clan.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20041206192017.GE72462@clan.nothing-going-on.org> User-Agent: Mutt/1.4.2.1i X-GPG-Key-ID: 1024D/0E451F7D X-GPG-Key-Fingerprint: E2CA 411D DD44 53FD BB4B 3CB5 B4D7 10A2 0E45 1F7D cc: doc@freebsd.org Subject: Re: Time for a Network Handbook? X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 06 Dec 2004 21:16:39 -0000 On Mon, Dec 06, 2004 at 07:20:18PM +0000, Nik Clayton wrote: > Partly to move closer (as others have said) to having a collection of > Handbooks. But mainly because I was glancing over the existing content Yes, we got consensus this summer to move out the system admin part into an administrator handbook, and I'd still support someone doing that at the same time as the network is moved out. It would be great if this was done in a transparent way... One thing we should think about is using link entities to allow the different chapters to be included in different books without breaking the build due to broken references. Currently, the single-chapter builds often fail because xrefs to other chapters can not be looked up. If we replaced all xrefs to other chapters with entities like: &link.chapter.sect; Then we could define that entity depending on the presence of the -i parameter entity for the given chapter file. If the chapter to be linked to is included in the build (and it's -i entity defined), then the is created. If it is not included in the build, then descriptive text is used instead 'The Blah Chapter in the Handbook'. In this way, we could more easily move chapters around between books without having to update all of the cross-chapter references. This would also allow us to easily maintain a full version of the Handbook that includes all of the chapters, in addition to the split off 'network handbook', 'admin handbook', etc. It's a stop-gap until we get proper olink support, basically. I explored a little of this work for the printed third edition, when we split it into two volumes, and it worked well for that purpose. We created a new links.ent file with the necessary parameters defined as I specified above. - Murray