From owner-freebsd-doc Wed Sep 29 16:26:51 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id BFA2215004; Wed, 29 Sep 1999 16:26:38 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id AAA49802; Thu, 30 Sep 1999 00:13:29 +0100 (BST) (envelope-from nik) Date: Thu, 30 Sep 1999 00:13:29 +0100 From: Nik Clayton To: jkoshy@FreeBSD.org Cc: Jeroen Ruigrok/Asmodai , nik@FreeBSD.org, doc@freebsd.org Subject: Re: FreeBSD versions in the docs Message-ID: <19990930001329.A48969@catkin.nothing-going-on.org> References: <199909270950.CAA76053@freefall.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <199909270950.CAA76053@freefall.freebsd.org>; from jkoshy@FreeBSD.org on Mon, Sep 27, 1999 at 02:50:11AM -0700 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Mon, Sep 27, 1999 at 02:50:11AM -0700, jkoshy@FreeBSD.org wrote: > asmodai> The problem is that the interfaces/applications/whole system [pick yon > asmodai> poison] tends to change dramatically in CURRENT, diverging a lot from > asmodai> STABLE. > > Documenting -current is not the issue here. We are looking at ways to keep > ONE set of documentation sources that could be used to generate OS release > specific versions of processed documentation. This is primarily aimed at > serving multiple -STABLE branches, and not -CURRENT, if I understood Nik > correctly. > > Today, in those places where there was a change, our documentation is > correct for either FreeBSD 2.X or 3.X, but not both. We currently don't > have the infrastructure in place to handle text which is slightly > different depending on the OS version. Exactly. Ideally, the one source text can contain information for any and all releases of FreeBSD. I don't want to be put in a position where we have to say "That's a great explanation of the kernel architecture, but it only applies to -current, and we're documenting -stable, sorry, can't accept it". We should have a way of building a -current version of the docs that only contains the common content + the -current content. Similarly, a way to build a -stable version, that contains common content and -stable content. [ On branching the docs in to -current and -stable ] > This may not be a good idea, because: > > (a) In most cases the changes between the -STABLE-1 and -STABLE-2 will not > be extensive (a few filenames will change etc). Branching the > FDP source just because descriptions are slightly different is > IMO overkill. > > (b) A lot of documentation is only loosely dependent on the exact > OS version or branch. > > (c) Other side effects on the FDP build infrastructure (tracking > content reorganizations or tool changes across multiple CVS > branches, for example). Agreed. One of the reasons the docs are in their own repository hierarchy is so that we don't have a -stable/-current split. N -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message