This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: DocBook-XML and conditional sections
On Tue, Sep 28, 1999 at 10:02:02AM -0400, Fred L. Drake, Jr. wrote:
> Stephane Bortzmeyer writes:
> > I don't see which one to use for a revision level ("Revision" refers to the
> > level of the document, not the level of the software we document.) May be
>
> Stephane,
> I know Norm suggested "OS", but here's my take:
> Since you're dealing with document revisions rather than revisions
> of what's documented, perhaps including all the versions in your text
> isn't the right approach. Why not use a traditional revisions control
> system for this? Each "release" can be tagged, and updates to that
> revision can be made on a patches branch for that tag.
This problem's popped up on the FreeBSD -doc list in the past week as well.
We didn't solve it the last time we had the discussion either :-(
> This is completely different from Norm's approach; you'll have to
> determine which would work best for your requirements (esp. revision
> patterns) and environment. I just wanted to make sure that a common
> way of handling such things isn't overlooked; a lot of people place
> code under revision control but not the related documentation, and
> I've never figured out a good reason for that.
Our docs are under revision control, but we don't branch them with the OS.
There's too much common documentation, and you'd end up doing frequent
merges from one branch to another. That's a lot of overhead, and
complicates things for the average documentor.
Also, sometimes you want to generate a formatted document that includes
information about two different versions of the OS. One SA might only
have FreeBSD 3.x machines installed, so wants to generate documentation
that's only appropriate for that (with all the 3.x specific <note>s
intact), another SA might have a mix of 3.x and 2.x installed. Rather
than have two substantially similar documents to hand, it's easier if
the differences between versions are picked out in the text. It saves
trees.
I'm going to include part of a message I sent to doc@FreeBSD.org about
this, which summarises the problem. As I say, we're still thrashing this
issue out on the FreeBSD list, informed comment from this list would be
appreciated.
N
==========================================================================
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>