Re: [docbook-tc] DocBook Technical Committee Meeting Minutes: 15March 2006

[Jirka Kosek <jirka@kosek.cz>]

Bob Stayton wrote:

> Jirka suggested we create a naming scheme for customizations
> similar to the formal public identifiers for DTDs.
> 
> ACTION: Bob to add RNG customization naming schemes to
> next meeting agenda.

To kick-off discussion I crafted short versioning proposal that is 
modeled very closely after the policy used for DTD FPIs. See attachment. 
Comments are welcomed.

				Jirka

-- 
------------------------------------------------------------------
   Jirka Kosek     e-mail: jirka@kosek.cz     http://www.kosek.cz
------------------------------------------------------------------
   Profesionální školení a poradenství v oblasti technologií XML.
      Podívejte se na náš nově spuštěný web http://DocBook.cz
        Podrobný přehled školení http://xmlguru.cz/skoleni/
------------------------------------------------------------------
                    Nejbližší termíny školení:
      ** XSLT 13.-16.3.2006 ** XML schémata 24.-26.4.2006 **
        ** DocBook 15.-17.5.2006 ** XSL-FO 12.-13.6.2006 **
------------------------------------------------------------------
   http://xmlguru.cz    Blog mostly about XML for English readers
------------------------------------------------------------------

Title: 5.5. Naming and versioning DocBook customizations

5.5. Naming and versioning DocBook customizations

DocBook V5.0 is not tightly coupled with some particular validation technology like DTDs. This also means that DocBook V5.0 documents doesn't have to (and usually really doesn't) start with document type declaration (<!DOCTYPE…>) which can specify schema (DTD) to use. Instead, DocBook V5.0 instance can be easily distinguished from other XML vocabularies by using elements in http://docbook.org/ns/docbook namespace. This namespace is enough to distinguish DocBook from other XML based formats. But DocBook schema evolves over the time and there are several versions of DocBook (e.g. 3.1, 4.2, 4.5 and 5.0). Since DocBook version 5.0 the actual version used is indicated in the version attribute on a root element.

<book xmlns="http://docbook.org/ns/docbook"
      version="5.0">
  …
</book>

Future version of DocBook will start with the same markup, only version number will be raised like 5.1 or 6.0. The namespace will remain same until semantic of elements will change in a backward incompatible way which is very unlikely to happen.

If you create DocBook schema customization you must change version attribute to distinguish your customization from the “official” DocBook. Namespace change is not recommended because it would break all processing tools. Remember that changing namespace is the same as renaming all elements in the namespace.

Your own version identifiers should use the following syntax in order to record their DocBook derivation:

base_version [Subset|Extension|Variant]? [name [version]]+

For example:

5.0 Subset Simplified 1.0
5.0 Variant ASMBook
5.0 ASMBook 2006
5.0 Extension MathML 2.0 SVG 1.1

The first part of version identifier is a version number of the DocBook schema from which you derived your customization.

If your schema is a proper subset, you can advertise this status by using the Subset keyword in the description. If your schema contains any markup model extensions, you can advertise this status by using the Extension keyword. If you'd rather not characterize your variant specifically as a subset or an extension, you can leave out this field entirely, or, if you prefer, use the Variant keyword.

After these keywords you can place whitespace separated list of customization identifiers. Each name can be optionally followed by its version number.

S/MIME Cryptographic Signature