From owner-freebsd-doc Thu Dec 5 10:32:18 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 3760F37B401; Thu, 5 Dec 2002 10:32:16 -0800 (PST) Received: from abigail.blackend.org (blackend.org [212.11.50.35]) by mx1.FreeBSD.org (Postfix) with ESMTP id DB62943E4A; Thu, 5 Dec 2002 10:32:14 -0800 (PST) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (localhost [127.0.0.1]) by abigail.blackend.org (8.12.3/8.12.3) with ESMTP id gB5IWDH6065536; Thu, 5 Dec 2002 19:32:13 +0100 (CET) (envelope-from marc@abigail.blackend.org) Received: (from marc@localhost) by abigail.blackend.org (8.12.3/8.12.3/Submit) id gB5IWDiH065535; Thu, 5 Dec 2002 19:32:13 +0100 (CET) (envelope-from marc) Date: Thu, 5 Dec 2002 19:32:13 +0100 From: Marc Fonvieille To: Robert Watson Cc: doc@FreeBSD.ORG Subject: Re: Man page entities in the handbook: 5.0? Message-ID: <20021205193213.A65511@abigail.blackend.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5.1i X-Useless-Header: blackend.org X-Operating-System: FreeBSD 5.0-CURRENT 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 On Thu, Dec 05, 2002 at 12:54:04PM -0500, Robert Watson wrote: > > 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. > We talked about that manual page problem in past when I worked on vendor attributes. There are many solution to "fix" the problem: - changing the default manual pages in the http://www.FreeBSD.org/cgi/man.cgi?query= but 4.X Handbook will be useless - using current attritute everywher, painful and not good for the future when 5.X will replace 4.X - using this fix for -CURRENT/5.X Handbook: Index: freebsd.dsl =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/share/sgml/freebsd.dsl,v retrieving revision 1.17 diff -u -r1.17 freebsd.dsl --- freebsd.dsl 17 Oct 2002 21:54:53 -0000 1.17 +++ freebsd.dsl 5 Dec 2002 18:12:06 -0000 @@ -60,11 +60,10 @@ (u (string-append "http://www.FreeBSD.org/cgi/man.cgi?query=" (data r) "&" "sektion=" (data m)))) (case v - (("current") (string-append u "&" "manpath=FreeBSD+5.0-current")) (("xfree86") (string-append u "&" "manpath=XFree86+4.2.0")) (("netbsd") (string-append u "&" "manpath=NetBSD+1.5")) (("ports") (string-append u "&" "manpath=FreeBSD+Ports")) - (else u)))) + (else (string-append u "&" "manpath=FreeBSD+5.0-current"))))) ]]> http://people.freebsd.org/~blackend/doc/en_US.ISO8859-1/books/handbook/ use that diff. Marc To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message