This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: details of DocBook versioning policy
- To: docbook at lists dot oasis-open dot org
- Subject: DOCBOOK: Re: details of DocBook versioning policy
- From: "Matt G." <matt_g_ at hotmail dot com>
- Date: Mon, 15 Oct 2001 06:41:39 +0000
- List-Id: <docbook.lists.oasis-open.org>
On Fri, 12 Oct 2001 08:53:35 -0400, Norman Walsh <ndw@nwalsh.com> said:
>/ "Matt G." <matt_g_@hotmail.com> was heard to say:
>| Isn't there a possibility that a patch release will alter the DTD in
>| an incompatible fashion, such that a valid XML DocBook x.y.z
>| document might not be valid for x.y.(z+n) (for n > 0)? Or is this
>| explicitly prevented, requiring that the issue be addressed in the
>| next major revision?
>
>The latter. The TC does not make backwards incompatible changes in
>point releases. It's even "worse" than that. If the TC decided
BTW, does the TC use any sort of regression suite (e.g. documents that use
each aspect of the content model from a given DTD version that are validated
against each new DTD from the same major rev)? It doesn't seem like it'd be
much work to maintain, once setup.
>| If the latter, then it would seem convenient to treat minor
>| revisions as RCS branch revisions, such that it aliases to the
>| latest
>
>There is no direct correlation between the revision numbers (or
>branch numbers) in CVS and the actual DTD releases. I do, as a
I was only using this as an analogy. When you check out from CVS or RCS,
with a branch tag or revision, you get the latest revision on that branch.
For example, if I 'cvs update -r 1.27.2 foo.c', I may actually get version
1.27.2.3 of foo.c (the 3rd commit of foo.c on the 1.27.2 branch). The
branch tag or revision aliases the latest single revision on that branch.
I was meaning to suggest that DTD version numbers could use a similar
scheme. If there wasn't a real release of 4.1, then 4.1 could be used to
refer to latest 4.1.x release. In a sense, X.Y would specify a branch (with
a new branch for each new batch of features and/or incompatibilities) and
X.Y.Z would be actual DTD releases.
However, I've decided that it doesn't actually make much sense to use
virtual identifiers in XML files, since every other XML tool, using a
validating parser, that is used on the file will have to somehow be coerced
into validating against a real DTD. Perhaps the best solution would be to
consider a recommendation for versioning syntax & semantics within
identifiers. (perhaps, if there's ever an XML v2.0...)
>| If the above versioning policy is followed, then documents should
>| only reference a specific minor revision, while the application
>| is free to use the latest compatible patch/superset. This could
>| be done through catalog files.
>
>You can arrange for this behavior using catalogs without changing
>the versioning policy. Just make your catalog point to the most
>recent point release for all public identifiers and URIs that are
>appropriate.
This is exactly what I'm doing. As I said, I've decided that documents must
reference *real* DTD versions, for the sake of XML tools that don't accept
catalog files. However, I've integrated the machinery into our document
build system to automatically generate a catalog file mapping all known DTD
identifiers to the latest, supposedly compatible, locally installed version.
The advantage is that, if someone imports a foreign docbook file (only
4.x, since we haven't installed any 3.x DTDs), it will build w/o also having
to install that DTD.
>| I was also wondering whether it's possible that stylesheets
>| (DSSSL or XSL) might be dependent on a minimum minor revision
>| (e.g. requiring DTD version 4.7 or greater), or should the only
>| dependency they have be on the major revision (e.g. requiring
>| version 4 of the DTD)?
>
>I've tried to make the stylesheets support all versions of the DTD.
>Most of our backwards incompatible changes have, in fact, been
>fairly minor.
How big of a limitation has this been? How much additional work has it
required?
I'd like to think that the best approach for writing stylesheets is to
maintain them as specific to the DTD's major rev. Perhaps all the
commonality between the various major revs can be factored out into a common
module that they all share, though it's debatable which approach results in
a higher maintenance burden. This is certainly the approach I'll consider,
in devising my customization layer.
Anyhow, I appreciate the information.
BTW, I noticed that the Apache XML group used a non-DocBook documentation
format, for their fairly substantial, XML-based documentation on Xerces
(their C++/Java validating DOM/SAX XML parser). Does anyone know why (I
asked them, but have yet to receive a reply)? I couldn't even find a
mention of docbook, in the mailing list archives (other than regarding
issues their libraries had w/ it).
Matt
_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com/intl.asp
----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>