From 8b07d3e004f01b88737e0e73519b69c3c75e33a3 Mon Sep 17 00:00:00 2001
From: Jirka Kosek <jirka@kosek.cz>
Date: Thu, 6 Apr 2006 20:32:17 +0000
Subject: [PATCH] Added proposal of versioning section

---
 docbook/relaxng/docbook/howto/howto.xml | 70 ++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 7 deletions(-)

diff --git a/docbook/relaxng/docbook/howto/howto.xml b/docbook/relaxng/docbook/howto/howto.xml
index 64303b358..6e8244f72 100644
--- a/docbook/relaxng/docbook/howto/howto.xml
+++ b/docbook/relaxng/docbook/howto/howto.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>  <!-- -*- nxml -*- -->
 <!DOCTYPE article [
 <!ENTITY version "5.0b3">
 ]>
@@ -1593,12 +1593,68 @@ db.spacing.enumeration |= "large"]]></programlisting>
 </example>
     </section>
   </section>
-  <section xml:id="cust-naming">
-    <title>Naming and versioning DocBook customizations</title>
-    <para>
-      TBD
-    </para>
-  </section>
+
+<section xml:id="cust-naming" status="draft">
+<title>Naming and versioning DocBook customizations</title>
+
+<para>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 (&lt;!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
+<uri>http://docbook.org/ns/docbook</uri> 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 <tag
+class="attribute">version</tag> attribute on a root element.</para>
+
+<programlisting><![CDATA[<book xmlns="http://docbook.org/ns/docbook"
+      version="5.0">
+  …
+</book>]]></programlisting>
+
+<para>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.</para>
+
+<para>If you create DocBook schema customization you must change <tag
+class="attribute">version</tag> attribute to distinguish your
+customization from the <quote>official</quote> 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.</para>
+
+<para>Your own version identifiers should use the following syntax in
+order to record their DocBook derivation:</para>
+
+<programlisting><replaceable>base_version</replaceable> [Subset|Extension|Variant]? [<replaceable>name</replaceable> [<replaceable>version</replaceable>]]+</programlisting>
+
+<para>For example:</para>
+
+<programlisting>5.0 Subset Simplified 1.0
+5.0 Variant ASMBook
+5.0 ASMBook 2006
+5.0 Extension MathML 2.0 SVG 1.1</programlisting>
+
+<para>The first part of version identifier is a version number of the
+DocBook schema from which you derived your customization.</para>
+
+<para>If your schema is a proper subset, you can advertise this status
+by using the <literal>Subset</literal> keyword in the description. If
+your schema contains any markup model extensions, you can advertise
+this status by using the <literal>Extension</literal> 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 <literal>Variant</literal> keyword.</para>
+
+<para>After these keywords you can place whitespace separated list of
+customization identifiers. Each name can be optionally followed by its
+version number.</para>
+
+</section>
 
 </section>
 
-- 
2.40.0