From owner-freebsd-doc Thu Dec 5 9:54:12 2002 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 DCA1937B401 for ; Thu, 5 Dec 2002 09:54:10 -0800 (PST) Received: from fledge.watson.org (fledge.watson.org [204.156.12.50]) by mx1.FreeBSD.org (Postfix) with ESMTP id 59E0843EA9 for ; Thu, 5 Dec 2002 09:54:10 -0800 (PST) (envelope-from robert@fledge.watson.org) Received: from fledge.watson.org (fledge.pr.watson.org [192.0.2.3]) by fledge.watson.org (8.12.6/8.12.5) with SMTP id gB5Hs5BF099760 for ; Thu, 5 Dec 2002 12:54:05 -0500 (EST) (envelope-from robert@fledge.watson.org) Date: Thu, 5 Dec 2002 12:54:04 -0500 (EST) From: Robert Watson X-Sender: robert@fledge.watson.org To: doc@FreeBSD.ORG Subject: Man page entities in the handbook: 5.0? Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org As we've been adapting the system documentation for 5.0-RELEASE, I've added some man page entities for 5.0 concepts. However, when I build the handbook and follow cross-references for man pages, they by default search 4.7-RELEASE. Should I individually modify entities for strictly 5.0 concepts to use a vendor of current, or do we need do make some more wholesale change? A related question has to do with the general issue of differences between 4.x and 5.0. In some areas, there are few or any differences (user management). In other, there are minor differences (no need to use MAKEDEV, we have devfs). In yet others, it's almost completely different -- the kernel configuration section is rapidly become more than text in the first place. I'm wondering if either of the following two models would make sense: (1) Build a handbook5 version of the handbook from the same handbook source, only conditionally use 5.x-only sections, dropping 4.x-only sections, and use the 5.x man page cross references. (2) Simply have two versions of chapters or sections that are substantially different, such as kernel configuration. Both have their merits -- (1) sounds like a much more complicated task, but might be more effective -- 5.x users would view their version of the page and get the right man pages when they clicked, etc. 4.x users would view either handbook/ or handbook4/. Either course would reflect the similarity of the two branches, but as they diverge (1) might provide a better way to manage the differences, especially where users might find markably different things in the man pages. (newfs, fsck, etc). In any case, it's not immediately pressing as 5.0 is really an early adtopers' release, other than that I'd like to get the man entities working, I just want to make sure I do it the right way. Robert N M Watson FreeBSD Core Team, TrustedBSD Projects robert@fledge.watson.org Network Associates Laboratories To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message