[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: Re: details of DocBook versioning policy
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC