DocbookSchemas

Docbook v5 Schema changes

A section to record schema extensions and restrictions so that others can learn how its done and perhaps re-use work done by others.

Schema restrictions

Constraining the relax NG schemas.

Schema additions

Adding features to the relax NG schema, to create a variant on docbook.

A block level addition

This example adds a block level entity to those of docbook at a similar level to a para element. I.e. Anywhere I can have a para I can also have a poem. I've created a separate file containing the poem schema (everything except the start element). The top level element is poem, which is in the same namespace as the other docbook elements, for ease of editing. The Schema location is assumed to be /dir/docbook/ so please change it to include the main docbook v5 schema.

<include href="/dir/docbook/v5/docbook.rng"/>
<include href="poem.rng"/>

<define name="db.para.blocks" combine='choice'>
<oneOrMore> <ref name="poem"/> </oneOrMore>
</define>

Note that the poem inclusion is outside the include for the two files and the method of combination is choice. This means that the processor combines or merges the two grammars, and the new item (the poem) is added as a choice at the named point.

Now, when writing docbook, I can add poetry! Simple.

An inline addition

This example adds two minor inline elements to the main schema. The Schema location is assumed to be /dir/docbook/ so please change it to include the main docbook v5 schema.

<include href="/dir/docbook/v5/docbookxi.rng">
<define name="db.ubiq.inlines">
<choice>
<ref name="shLft"/>
<ref name='shRt'/>
</choice>
</define>
</include>

<!-- DP Addition -->
<define name="shLft">
<element name="shLft">
<empty/>
</element>
</define>

<define name="shRt">
<element name="shRt">
<empty/>
</element>
</define>

Explanation.

Initially the main stylesheet is imported using the include statement. Next, a definition is created, which updates the matching one in the docbook schema. Note that it is within the include. This means that this definition is used instead of the original one (in the main schema). If I want to merge the definitions in some way, then the extra definition should be placed outside the include for the main schema.

In the example, the addition is that of two elements. db.ubiq.inlines is copied from the main schema and modified here.

The combine="choice" attribute specifies how the pattern will be folded back into the main schema. This gives a choice.

Finally, outside the include statement, the new elements are defined.

That's it. All that is needed now is an XSLT customization layer to style the new elements as I'd like them, or the docbook stylesheets will warn you about the new elements. See DocBookCookbook for that

References

docbook.org on customization for v5