The procedure for writing, testing, and using a customization layer is always about the same. In this section, we’ll go through the process in some detail. The rest of the sections in this chapter describe a range of useful customization layers.
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. For example, if you’re writing about cryptography, you
might want to add a “cleartext
” element.
The next section describes how to create a customization layer to do
this.
Figuring out what to change may be the hardest part of the
process. For the cleartext
example, there are several patterns that you could possibly change. The
choice will depend on the exact focus of your document. Here are several
candidates, all of which look plausible: technical inlines, programming
inlines, and domain inlines. Let’s suppose you chose the domain
inlines.
As shown in Example 5-1, your customization would import the DocBook schema, extend the domain inlines, and then provide a pattern that matches the new element.
Example 5-1. Adding cleartext with a customization layer
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 }
The |=
operator adds a new choice to a
pattern. So this line makes the db.cleartext
pattern a valid option anywhere that
db.domain.inlines
appears.
Next, we create a pattern for the
cleartext
element. The convention in the
DocBook schema is to create three patterns, one for the role
attribute, one for all the
attributes, and one for the element. By following this convention,
we make it easier for someone to customize our
customization.
Defining a separate pattern for the role
attribute makes it easy for customizers to change it on a
per-element basis.
Defining a separate pattern for the attributes makes it easy
for customizers to change them on a per-element basis. This
pattern includes the pattern we just created for the role
attribute.
The pattern for the element pulls it all together. The
pattern db._text
matches text plus a number of
ubiquitous or nearly ubiquitous inlines. Use this pattern unless
you really want only text.
Using a customization layer is simple. Just put the customization
into a file—for example, mycustomization.rnc
—and
then refer to that file instead of the DocBook schema when your tools
offer the option.
Schemas, by their nature, contain many complex, interrelated patterns. Whenever you make a change to the schema, it’s always wise to use a validator to check your work.
Start by validating a document that’s plain, vanilla DocBook, one that you know is valid according to the DocBook standard schema. This will help you identify any errors that you’ve introduced to the schema. Once you are confident the schema is correct, begin testing with instances that you expect (and don’t expect) to be valid against it.
The following sections contain examples for several common customizations.