Date: Thu, 22 Apr 1999 11:17:47 +0100 From: nclayton@lehman.com To: A Joseph Koshy <koshy@postbox.india.hp.com>, nik@freebsd.org Cc: doc@freebsd.org, davenport@berkshire.net Subject: Re: On versioning in DocBook Message-ID: <19990422111747.E14492@lehman.com> In-Reply-To: <199904210606.LAA17864@postbox.india.hp.com>; from A Joseph Koshy on Wed, Apr 21, 1999 at 11:36:35AM %2B0530 References: <199904210606.LAA17864@postbox.india.hp.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Joseph,
[ I'm cc'ing this to freebsd-doc and the Davenport mailing list to open
out discussion -- if you're reading this on one of those two lists,
*please* ensure that you only follow up to the correct list, thanks
(Norm, perhaps you could remove the cc: freebsd-doc from this message
when you moderate it?) ]
On 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. I'd
welcome input from others on the -doc mailing list, and from those
members of Davenport who have had to solve this problem for their own
documentation.
N
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
--+==[ Year 2000 Testing: It's about time. . . ]==+--
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?19990422111747.E14492>