Date: Sat, 25 Sep 1999 22:42:06 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: FreeBSD versions in the docs Message-ID: <19990925224206.A25199@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
-doc,
As various people have commented in the past months, various parts of the
FAQ and Handbook have been targetted at 2.x users, and there have been
various submissions updating them for the 3.x line.
The question has arisen as to how best to handle this. Do we want the
documentation to be targetted at one specific version of FreeBSD (and if
we did, which version -- -stable, I imagine)? Or do we want to be able
to document as many versions as we can? I'm conscious of the fact that
as we update the docs for new versions we're obliterating information
that's probably useful to people who have older systems. Yes, they can
pull the information about of the CVS repository as necessary, but it's
not a particularly user friendly thing to force them to do.
On 22 April this year a message from me to -doc talked about this.
I'm repeating the whole thing below in the hope it will kick start a
discussion this time.
N
n Wed, Apr 21, 1999 at 11:36:35AM +0530, A Joseph Koshy wrote:
> Docbook has some features to handle versioning of text (using one of
> the common attributes of all the elements if I remember right).
Do you mean the OS attribute? The DTD says
--OS: Operating system to which element applies; no default--
which is the closest match I can think of. I thought there was another
one that was more appropriate but a quick scan through the DTD doesn't
show anything promising (of course, we could always add one).
> There are a couple of places where version specific text would be
> really useful: e.g., the Handbook currently refers to disks by their
> pre-3.x names `sd[0-9]', while post 3.1 disks are named `da[0-9]'
> (see PR docs/11215).
>
> Can/should we use Docbook's facilities to handle version specific
> documentation? If so (or if not), do you have any guidelines on
> writing version specific text?
I haven't given it a lot of thought yet. The same question had occured to
me when I was doing the conversion, but I ignored it then because I had
too much else to concentrate on :-)
First, I think it's a good idea if the Handbook covers more than just the
latest version of FreeBSD, so including content that refers to previous
versions is a good thing, and to be encouraged.
Having said that, I'm not convinced as to the best way to do it. A number
of possible approaches spring to mind.
1. You can use <note>s (or other elements, possibly <sidebar>) with a
suitable <title> to indicate the version that it applies to. See
http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html
for an example of that approach.
I don't think this scales well, and it makes it difficult to pull out
a version of the documentation which (for example) only contains text
appropriate for version 3.1 or 2.2.8.
2. You can use the OS attribute, and duplicate elements with different
values for this attribute. Perhaps
<para os="RELENG_22">Disk devices look like
<devicename>sd<replaceable/nn/s<replaceable/n/</devicename>.</para>
<para os="RELENG_3">Disk devices look like
<devicename>da<replaceable/nn/s<replaceable/n/</devicename>.</para>
Or even
<para>Disk devices look like
<devicename os="RELENG_22"/sd<replaceable/nn/s<replaceable/n//
<devicename os="RELENG_3"/da<replaceable/nn/s<replaceable/n//.</para>
A pre-processor would go through the SGML, leaving only those elements
that either have no OS attribute, or have a specific value in it.
3. Use parameter entities;
<!DOCTYPE book .... [
<!ENTITY % releng.22 "IGNORE">
<!ENTITY % releng.30 "IGNORE">
<!ENTITY % releng.31 "IGNORE">
]>
...
<![ %releng.22 [
<para>Disk devices look like <devicename/sd/.</para>
]]>
<![ %releng.30 [
<para>Disk devices look like <devicename/da/.</para>
]]>
<![ %releng.31 [
<para>Disk devices look like <devicename/da/.</para>
]]>
and so on. Still quite cumbersome, but doesn't need a pre-processor
to strip out elements with the wrong OS attribute value.
4. Use general entities and parameter entities
<!DOCTYPE book ... [
<!ENTITY % releng.22 "IGNORE">
<!ENTITY % releng.30 "IGNORE">
<!ENTITY % releng.31 "IGNORE">
<![ %releng.22 [
<!ENTITY disk.device "sd">
]]>
<![ %releng.30 [
<!ENTITY disk.device "da">
]]>
<![ %releng.31 [
<!ENTITY disk.device "da">
]]>
]>
...
<para>Disk devices look like <devicename/&disk.device;/.</para>
This would also work, but would quickly lead to a profusion of general
entities, which is probably over confusing.
Incidentally, none of these tackle an important issue -- some changes might
only affect certain releases before being superceded.
For example, for a long time, the main config file was /etc/sysconfig.
Then it was /etc/rc.conf. Then /etc/rc.conf.local. And now it's back
to /etc/rc.conf again. The time line was something like
2.0 -> 2.2.5 /etc/sysconfig
2.2.6 -> 2.2.8 /etc/rc.conf
3.0 -> 3.1 /etc/rc.conf.local
3.1 -> -current /etc/rc.conf
[ I might have some of the details wrong, but it'll illustrate this point ]
There were 10 releases between 2.0 and 2.2.5, and 3 between 2.2.6 and 2.2.8.
We need some way of either saying
(a) This content applies to all these versions
or
(b) This content applies to all versions between these two values
Whichever way we do this, a third application is going to need to parse
this information out of the document, as I don't think this can be done in
SGML.
Perhaps we should extend the DocBook DTD and add two new attributes,
OSVersionMin and OSVersionMax for the minmum and maximum FreeBSD versions
that the element applies to?
As you can see, I don't have any quick answers to this problem.
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?19990925224206.A25199>