Although not directly supported by RELAX NG, in some cases it may still be valuable to identify a DocBook V5.0 customization layer with a public identifier. A public identifier for DocBook V5.0 is:

-//OASIS//DTD DocBook V5.0//EN

If you make any changes to the structure of the schema, it is imperative that you alter the public identifier that you use to identify it.

You should change both the owner identifier and the description. Formal public identifiers for the base DocBook modules would have identifiers with the following syntax:

-//OASIS//text-class DocBook description Vversion//EN

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

-//your-owner-ID//text-class DocBook Vversion-Based [Subset|Extension|Variant] your-descrip-and-version//lang

For example:

-//O'Reilly//DTD DocBook V5.0-Based Subset V1.1//EN

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.

There are two standard syntaxes for RELAX NG, an XML syntax and a “compact” text syntax. The two forms have the same expressive power; it is possible to transform between them with no loss of information.

Many users find the relative terseness of the compact syntax makes it a convenient form for reading and writing RELAX NG. That is the form we will use in the following examples.

The names of the patterns used in a RELAX NG grammar are arbitrary, they have nothing to do with the names of the elements and attributes defined by the schema. The DocBook RELAX NG grammar employs a number of naming conventions in order to make it easier to navigate.

These are conventions, not hard and fast rules. There are patterns that don't follow these conventions.

If you're considering writing a customization layer, there must be something that you want to change. Perhaps you want to add an element or attribute, remove one, or change some other aspect of the schema.

Adding an element, particularly an inline element, is one possibility. If you're writing about cryptography, you might want to add a “cleartext” element, for example.

Figuring out what to change may be the hardest part of the process. Finding something similar usually provides a good model for new changes.

Depending on the exact focus of your document, there are probably several candidates. In this case, all of the following look plausible: technical inlines, programming inlines, and domain inlines. Let's suppose you chose the domain inlines.

As shown in Example 5.1, “Adding cleartext with a Customization Layer”, your customization would import the DocBook schema, extend the domain inlines, and then provide a pattern that matches the new element.

namespace db = "http://docbook.org/ns/docbook"
default namespace = "http://docbook.org/ns/docbook"

include "docbook.rnc"

db.domain.inlines |= db.cleartext                

# Define a new cleartext element:                

db.cleartext.role.attribute = attribute role { text }   
db.cleartext.attlist =                           
   db.cleartext.role.attribute?
 & db.common.attributes
 & db.common.linking.attributes

db.cleartext =                                   
   element cleartext {
      db.cleartext.attlist,
      db._text
   }

Using a customization layer is as simple as referring to it instead of the base DocBook schema where your tools offer the option.

MsgSet is a favorite target. It has a complex internal structure designed for describing interrelated error messages, especially on systems that may exhibit messages from several different components. Many technical documents can do without it, and removing it leaves one less complexity to explain to your authors.

Example 5.2, “Removing msgset” shows a customization layer that removes the msgset element from DocBook:

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.msgset = notAllowed
}

The complexity of msgset is really in its msgentry children. DocBook V4.5 introduced a simple alternative, simplemsgentry. Example 5.3, “Removing msgentry” demonstrates how you could allow msgset but only support the simpler alternative.

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.msgentry = notAllowed
}

Closer examination of the msgentry content model will reveal that it contains a number of descendants. It isn't necessary, but it wouldn't be wrong, to define their patterns as notAllowed as well.

DocBook contains a large number of computer inlines. The DocBook inlines define a domain-specific vocabulary. If you're working in another domain, many of them may be unnecessary.

They're defined in a set of patterns that ultimately roll-up to the “db.domain.inlines” pattern. If you make that pattern “notAllowed”, you'll remove them all in one fell swoop.

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.domain.inlines = notAllowed
}

If you want to be more selective, you might consider making one or more of the set not allowed instead: “db.error.inlines”, errors and error messages; “db.gui.inlines”, GUI elements; “db.keyboard.inlines”, key and keyboard elements; “db.markup.inlines”, markup elements; “db.math.inlines”, mathematical expressions; “db.os.inlines”, operating system inlines; and “db.programming.inlines”, programming-related inlines.

It's likely that a customization layer that removed this many technical inlines would also remove some larger technical structures (msgset, funcsynopsis).

Another possibility is removing the complex synopsis elements. The customization layer in Example 5.5, “Removing CmdSynopsis and FuncSynopsis” removes cmdsynopsis and funcsynopsis.

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.funcsynopsis = notAllowed
   db.cmdsynopsis = notAllowed
}

Perhaps you want to restrict your authors to only three levels of sectioning. To do that, you must remove the sect4 and sect5 elements, as shown in Example 5.6, “Removing sect4 and sect5 Elements ”.

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.sect4 = notAllowed

   # Strictly speaking, we don't need to remove sect5 because, having removed
   # sect4, there's no way to reach it. But it seems cleaner to do so.
   db.sect5 = notAllowed
}

This technique works if your authors are using numbered sections. You could require them to do so by removing section. But suppose instead you want to allow them to use recursive sections and still limit them to only three levels.

One way to do this would be to define new “section2” and “section3” patterns, as shown in Example 5.7, “Limiting recursive sections to three levels”.

namespace db = "http://docbook.org/ns/docbook"
default namespace = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.section =
      element section {
         db.section.attlist,
         db.section.info,
         db.recursive.blocks.or.section2s,
         db.navigation.components*
      }
}

db.recursive.section2s = (db.section2+, db.simplesect*) | db.simplesect+

db.recursive.blocks.or.section2s =
  (db.all.blocks+, db.recursive.section2s?) | db.recursive.section2s

db.section2 =
   element section {
      db.section.attlist,
      db.section.info,
      db.recursive.blocks.or.section3s,
      db.navigation.components*
   }

db.recursive.section3s = (db.section3+, db.simplesect*) | db.simplesect+

db.recursive.blocks.or.section3s =
  (db.all.blocks+, db.recursive.section3s?) | db.recursive.section3s

db.section3 =
   element section {
      db.section.attlist,
      db.section.info,
      db.all.blocks+
      db.navigation.components*
   }

Another solution, assuming your validation environment supports Schematron, is simply to add a new rule, as shown in Example 5.8, “Limiting recursive sections to three levels”.

namespace db = "http://docbook.org/ns/docbook"
namespace s = "http://www.ascc.net/xml/schematron"
default namespace = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.section =
      [
         s:pattern [
            name = "Limit depth of sections"
            s:rule [
               context = "db:section"
               s:assert [
                  test = "count(ancestor::db:section) < 2"
                  "Sections can be no more than three levels deep"
               ]
            ]
         ]
      ]
      element section {
         db.section.attlist,
         db.section.info,
         db.recursive.blocks.or.sections,
         db.navigation.components*
      }
}

Sometimes what you want to do is not as simple as entirely removing an element. Instead, you want to remove it only from some contexts. The way to accomplish this task is to redefine the patterns used to calculate the elements allowed in those contexts.

Standard DocBook allows any inline element or any block element to appear in a table cell. You might decide that it's unreasonable to allow admonitions (note, caution, warning, etc.) to appear in a table cell.

In order to remove them, you must change what is allowed in an entry, as show in Example 5.9, “Removing Admonitions from Tables”.

namespace db = "http://docbook.org/ns/docbook"
default namespace = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.entry = element entry {
      db.entry.attlist,
      (db.all.inlines* | db.some.blocks*)
   }
}

db.some.blocks =
   db.somenopara.blocks
 | db.para.blocks
 | db.extension.blocks

db.somenopara.blocks =
   db.list.blocks
 | db.formal.blocks
 | db.informal.blocks
 | db.publishing.blocks
 | db.graphic.blocks
 | db.technical.blocks
 | db.verbatim.blocks
 | db.bridgehead
 | db.remark
 | db.revhistory
 | db.indexterm
 | db.synopsis.blocks

The extent to which any particular change is easy or hard depends in part on how many patterns need to be changed. The DocBook Technical Committee is generally open to the idea of adding more patterns if it improves the readability of customization layers. Feel free to ask, if you think some refactoring would make your job easier.

Suppose your processing system doesn't support “continued” lists. You want to remove the continuation attribute from the orderedlist element. There are two ways you could accomplish this. One way would be to redefine the “db.orderedlist.continuation.attribute” as not allowed; the other would be to redefine the “db.orderedlist.attlist” pattern so that it does not include the continuation attribute. Either would accomplish the goal.

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.orderedlist.continuation.attribute = empty
}

namespace db = "http://docbook.org/ns/docbook"

include "docbook.rnc" {
   db.common.base.attributes =
      db.version.attribute?
    & db.xml.lang.attribute?
}