Date: Mon, 27 Sep 1999 02:50:11 -0700 (PDT) From: <jkoshy@FreeBSD.org> To: Jeroen Ruigrok/Asmodai <asmodai@wxs.nl> Cc: nik@FreeBSD.org, doc@freebsd.org Subject: Re: FreeBSD versions in the docs Message-ID: <199909270950.CAA76053@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
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.
Think of tutorials that attempt to explain PPP setup, or e-mail
configuration. Most (99%?) of the tutorial could be common to all
FreeBSD releases, with a few version specific differences.
asmodai> I think that the best way is to make a CURRENT/STABLE split of doc.
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).
nik> 3. Use parameter entities;
[snip]
asmodai> How does DocBook know where to get the appropriate OS version
asmodai> from then?
As part of the document build process, we would define the appropriate
entities to be either "INCLUDE" or "IGNORE", (e.g:- from the
command line).
This technique as provides a simple (crude?) way to conditionally include
portions of the document into the processing run.
asmodai> Just take a look at every commercial related Operating System out
[snip]
asmodai> but otherwise they don't document the different versions
asmodai> all in one document.
True, the final product typically is about one version only but
internally they could be using a common set of documentation sources
to generate the version specific documentation.
Koshy
<jkoshy@freebsd.org>
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?199909270950.CAA76053>