Re: [docbook] revnumber Required

[Michael Smith <smith at xml-doc dot org>]

Hi John,

You wrote:

> My authoring group is working on making the transition to DocBook.
> We've been discussing the versioning of documents recently.  Until now,
> I had required that when making changes to a document, everyone should
> add a revision element with an incremented revnumber child (as well as
> the other revision content).  However, my group is uncomfortable with
> the use of an internal revnumber, as it does not correspond with the
> external numbers applied to files under version control or product
> releases.

That's understandable. People might assume that the revision
numbers that are in the document instance relate to numbers in
some database or system outside of the document, which it sounds
like they don't in your case. So they don't really add much value
to your revision history.

> What I thought I would do, then, was to make the revnumber optional; we
> could still refer to revisions by date and the revnumber wouldn't
> conflict with other numerical identifiers that we have floating around.
> Then I noticed that DocBook requires revnumber.  I was wondering if
> someone on the list could provide more insight into this decision, both
> so that I can understand the content model better and so that I can
> explain it to my group and work around it.

Revhistory was part of DocBook from the very beginning (DocBook v1
in 1992), and Revnumber was a required part of it from the very
beginning.

But the official rationale behind making it required is lost in
the mists of time now. I would speculate that the reason was because
two revisions might have exactly the same date, so the desire was
to be able to encourage users to put a unique revnumber on each
revision to make it uniquely identifiable.

Also, I don't think the original designers conceived of a revision
as being a thing that might itself be a list of changes (like CVS
Changelog files, for example) rather than a single individual
change.

Anyway, this seems to me like a case where DocBook is being
unnecessarily prescriptive. Part of DocBook's mission is to be
descriptive of the various forms of things that it models
(reference/man page, revision histories, etc.), rather than trying
to prescriptively model "ideal" forms of things.

So, if possible, could you file a Docbook RFE requesting that
Revision be changed to make Revnumber optional? You can do that
here:

  http://sourceforge.net/tracker/?func=add&group_id=21935&atid=384107

Or, if you don't have a Sourceforge account and don't want to
hassle with it, let me know and I will go ahead and file one
myself.

  --Mike

Attachment: pgp00000.pgp
Description: PGP signature