docbook extensions policy

["Bob Stayton" <bobs@sagehill.net>]

Per my DocBook Tc action item to research our policy on DocBook extensions, 
here is what I gleaned from the minutes.  The October 2011 entry is our 
official namespace usage policy, which Norm published somewhere.


> > > From the May 2010 minutes:

7b.  DocBook modules in namespaces?

Should we put DocBook modules in namespaces, now that
we have a namespace for DocBook?
There was general agreement that the existing elements
in DocBook 5.0 should be in the DocBook namespace, and
not separated into their own or no namespace.
We will consider using namespaces for newly proposed
modules.


> > > From the August 2010 minutes:

10b.  API extensions.

One project of the Google Summer of Code was developing
schema extensions for documenting programming APIs.
The developer asked the Committee about whether these should
be in the DocBook namespace, or a separate namespace?

The Committee felt that people are free to develop extensions
that make use of the DocBook namespace, because of the complications
in mixing namespaces.  However, the Committee wants to
distinguish between ad hoc extensions and those that are
reviewed and approved by the Committee as part of the
DocBook standard 11.



> > > From the June 2011 minutes:

     1575537  allow markup from other namespaces in info

There were only positive comments when Scott asked the list.
The processing expectation is to not render these elements.
The RNG pattern would be any element in a non-DocBook
namespace.  The Committee approved this change for V5 CR1.

> > > From the October 2011 minutes:

6.  Namespace usage policy

The committee agreed that the TC cannot police efforts by
users to add elements to the DocBook namespace in their
local applications.  They just should not call it DocBook
if they do.

The committee is proposing the following text submitted by
Norm to be included in the DocBook documentation:

"DocBook is used throughout the world. As one would expect in such a
broad context, DocBook is often customized to satisfy the requirements
of specific organizations or projects. The DocBook TC encourages such
customization and works hard to make sure that the schemas are as
amenable to customization as possible.

When customizers add new elements to DocBook, they often place those
elements in the DocBook namespace (http://docbook.org/ns/docbook).
There is historical precedent for this approach as DocBook's history
pre-dates namespaces and even XML. Even without precedent, users would
almost certainly encourage customizers to use the same namespace. In
many cases it simplifies authoring and almost always simplifies the
training of new authors.

However, a new element introduced into the DocBook namespace by a
local customization is not officially part of DocBook. Only the
DocBook TC can introduce new elements into DocBook officially by
publishing a new version of the standard with those elements.

That means that the practice of adding new elements comes with a cost:
the potential for confusion among authors familiar with different
customizations and the costs associated with resolving any conflicts
between interchange partners.

The DocBook TC encourages customizers to think carefully about these
costs and weight the potential tradoffs between unofficially adding
elements to DocBook and using elements in their own namespace with
care."

ACTION: Norm to incorporate this into the official docs with
appropriate links to the "If you change DocBook, it's not
DocBook any more.


> > > From the November 2011 minutes:

.  MathML and SVG support in 5.0 (Jirka)

The Committee debated two choices for adding MathML and
SVG support to Docbook 5.0:
 a.  Add the elements to the schema.
 b.  Document how to incorporate them as a customization
     in their own namespaces.

The Committee decided on (b).


Bob Stayton
Sagehill Enterprises
bobs@sagehill.net