A RELAX NG grammar is a collection of patterns. These patterns can be stored in a single file or in a collection of files that import each other. Patterns can augment each other in a variety of ways. A complete grammar is the union of the specified patterns.
For convenience, the DocBook grammar is distributed in a single file.
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. We will use compact syntax in our examples.
The DocBook RELAX NG schema is highly modular, using named patterns extensively. Every element, attribute, attribute list, and enumeration has its own named pattern. In addition, there are named patterns for logical combinations of elements and attributes. These named patterns provide “hooks” into the schema that allow you to do a wide range of customization by simply redefining one or more of the named patterns.
The names of the patterns used in a RELAX NG grammar can be defined in any way the schema designer chooses. To make it easier to navigate, the DocBook RELAX NG grammar employs the following naming conventions:
db.*
.attlist
Defines the list of attributes associated with an element.
For example, db.emphasis.attlist
is the pattern
that matches all of the attributes of the
emphasis
element.
db.*
.attribute
Defines a single attribute. For example,
db.conformance.attribute
is the pattern that
matches the conformance
attribute on all of the elements where it occurs.
db.*
.attributes
Defines a collection of attributes. For example,
db.effectivity.attributes
is all of the
effectivity attributes (arch
,
audience
, etc.).
db.*
.blocks
Defines a list (a choice) of a set of related block
elements. For example, db.list.blocks
is a
pattern that matches any of the list elements.
db.*
.contentmodel
Defines a fragment of a content model shared by several elements.
db.*
.enumeration
Defines an enumeration, usually one used in an attribute
value. For example, db.revisionflag.enumeration
is a pattern that matches the list of values that can be used as
the value of a revisionflag
attribute.
db.*
.info
Defines the info
element for a particular
element. For example, db.example.info
is the
pattern that matches info
on the
example
element.
Almost all of the info
elements are the
same, but they are described with distinct patterns so that
customizers can change them individually.
db.*
.inlines
Defines a list (a choice) of a set of related inline
elements. For example, db.link.inlines
is a
pattern that matches any of the linking-related elements.
db.*
.role.attribute
Defines the role
attribute for a particular element. For example,
db.emphasis.role
is the pattern that matches
role
on the
emphasis
element.
All of the role
attributes are the same, but they are described with distinct
patterns so that customizers can change them selectively.
db.*
Defines a particular DocBook element. For example,
db.title
is the pattern that matches the
title
element.
RELAX NG allows multiple patterns to match the same element,
so sometimes these patterns come in flavors, for example,
db.indexterm.singular
,
db.indexterm.startofrange
, and
db.indexterm.endofrange
. Each of these patterns
matches indexterm
with varying
attributes.
These are conventions, not hard and fast rules. There are patterns that don’t follow these conventions.
Creating a customized schema is similar to creating a customization layer for XSL. The schema customization layer is a new RELAX NG schema that defines your changes and includes the standard DocBook schema. You then validate using the schema customization as your schema. Although customization layers vary in complexity, most of them have the same general structure as other customization layers of similar complexity.
In the most common case, you probably want to include all of DocBook, but you want to make some small changes. These customization layers tend to look like this:
namespace db = "http://docbook.org/ns/docbook" # perhaps other namespace declarations include "docbook.rnc" # new patterns and augmented patterns
If you want to completely replace a pattern (e.g., to remove or completely change an element), the template is a little different.
namespace db = "http://docbook.org/ns/docbook" # perhaps other namespace declarations include "docbook.rnc" { # redefinitions of DocBook patterns } # new patterns and augmented patterns
There are other possibilities as well; these examples are illustrative, not exhaustive.