Date: Thu, 5 Dec 2002 20:40:53 +0100 From: Marc Fonvieille <blackend@FreeBSD.ORG> To: Robert Watson <rwatson@FreeBSD.ORG> Cc: doc@FreeBSD.ORG Subject: Re: Man page entities in the handbook: 5.0? Message-ID: <20021205194053.GC575@nosferatu.blackend.org> In-Reply-To: <Pine.NEB.3.96L.1021205123823.70896I-100000@fledge.watson.org> References: <Pine.NEB.3.96L.1021205123823.70896I-100000@fledge.watson.org>
next in thread | previous in thread | raw e-mail | index | archive | help
In my previous mail, I just gave a quick fix about the manual page problem since I am "guilty of some vendor attributes" :)) 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 Indeed, the differences between 4.X and 5.X are often a problem when it's time to update docs. > -- 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). > I have a question: when 5.0 will be released, what will be the Handbook version available online? 5.0, right? Well we need to keep a 4.X version online. Many people asked, these days, for previous Handbook version. I have a few remarks about that problem: - 1st: http://docs.freebsd.org/handbook/en/ must be up-to-date, we miss some previous Handbook versions on that server. - 2nd: After 5.0 release, we have to decide if we have to continue to maintain 4.X Handbook, or just keeping it online and only working on the 5.X one (this latter could keep some references about 4.X). Since, I don't think there will be many important changes between 4.7 and 4.8, this will not be annoying for the end-user to have an "old" 4.X Handbook. - Some people could think: "we need to use -CURRENT/-STABLE scheme for all docs". For manual pages, it's mandatory, I don't think we have to do it for the Handbook... - We miss an (up to date) official tasks list about docs, for example, we are/were late in the Handbook updates for 5.X, and many things have to be updated/written in general. - We have to think about the future of the Handbook, the "beast" is growing up everyday :) - freebsd-doc list is the right place to talk about docs however sometimes I missed a DOCeng team, especially when we talk about a structure change or evolution, or when a sort of management is needed and many of us are too busy to help and give their opinion. Ok, I stop now :) Marc 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?20021205194053.GC575>