Date: Thu, 5 Dec 2002 12:54:04 -0500 (EST) From: Robert Watson <rwatson@FreeBSD.ORG> To: doc@FreeBSD.ORG Subject: Man page entities in the handbook: 5.0? Message-ID: <Pine.NEB.3.96L.1021205123823.70896I-100000@fledge.watson.org>
next in thread | raw e-mail | index | archive | help
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 <note> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.NEB.3.96L.1021205123823.70896I-100000>