DOCBOOK: Re: details of DocBook versioning policy

["Matt G." <matt_g_@hotmail.com>]

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