Date: Tue, 26 Oct 1999 22:21:11 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: doc@freebsd.org Subject: [bortzmeyer@debian.org: Re: DOCBOOK: DocBook-XML and conditional sections] Message-ID: <19991026222111.A19720@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
I'm forwarding this (somewhat late) as requested.
Stephane's on holiday at the moment, and back at the beginning of November.
I like the solution though, and think it's something we should probably
adopt to solve our versioning problems.
I've asked Stephane to consider making the attribute names OS neutral
(i.e., osversionmin, and so on) so that documents are more easily portable
between us. I would have no qualms about recommending that we write
something like
<note osversionequal="RELENG_2_2_2_RELEASE">
<para>The <devicename>foo</devicename> was is called
<devicename>bar</devicename> in FreeBSD 2.2.2.</para>
</note>
or similar.
That's a bit of a mouthful to write, and we could use general entities
relatively easily, something like
<ENTITY r2.2.2 "RELENG_2_2_2_RELEASE">
...
<note osversionequal="&r2.2.2">
...
</para>
What's also nice about this is that we can put constraints in (our) DTD
(which can be turned on or off with a parameter entity) to ensure that
mistakes like
<note osversionequal="REENG_2_2_2_RELEASE">
(i.e., a typo in the attribute value) are spotted by the SGML parser and
flagged as errors.
Thoughts? Assuming everyone likes this I'll wait for Stephane to get
back from holiday, check out the issues above, and then commit something
that implements it.
N
----- Forwarded message from Stephane Bortzmeyer <bortzmeyer@debian.org> -----
From: Stephane Bortzmeyer <bortzmeyer@debian.org>
To: Nik Clayton <nik@nothing-going-on.demon.co.uk>
Subject: Re: DOCBOOK: DocBook-XML and conditional sections
Date: Thu, 30 Sep 1999 12:24:56 +0200
[You can forward that on freebsd-doc if you think it's worth it.]
On Thursday 30 September 1999, at 0 h 18, the keyboard of Nik Clayton
<nik@nothing-going-on.demon.co.uk> wrote:
> 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.
Well, Debian has several branches and the documentation manager merges them
from time to time. But I wanted to try a pure SGML solution.
> 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.
I finally added THREE attributes: debianversionequal, debianversionmin and
debianversionmax. The first one is for info which depends on one specific
release, the other two (which can be combined) is for more traditional info
("Starting from 2.2...", "Until version 1.1").
In the filtering program, you just have to write a comparison function which
works for you (RELENG_3 > RELENG_22, despite what the math says).
> 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.
I have written such a pre-processor, if you like (a few lines of Perl +
XML::DOM).
> 3. Use parameter entities;
Does not allow ranges, such as 2.2 < version < 3.1.
> and so on. Still quite cumbersome, but doesn't need a pre-processor
> to strip out elements with the wrong OS attribute value.
And do not work with XML.
----- End forwarded message -----
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?19991026222111.A19720>