Date: Thu, 30 Sep 1999 00:13:29 +0100 From: Nik Clayton <nik@freebsd.org> To: jkoshy@FreeBSD.org Cc: Jeroen Ruigrok/Asmodai <asmodai@wxs.nl>, nik@FreeBSD.org, doc@freebsd.org Subject: Re: FreeBSD versions in the docs Message-ID: <19990930001329.A48969@catkin.nothing-going-on.org> In-Reply-To: <199909270950.CAA76053@freefall.freebsd.org>; from jkoshy@FreeBSD.org on Mon, Sep 27, 1999 at 02:50:11AM -0700 References: <199909270950.CAA76053@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990930001329.A48969>