DocBook has a large number of elements. In some authoring environments, it may be useful or necessary to remove unneeded elements.
The msgset
element 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 shows a customization layer that
removes the msgset
element.
Example 5-2. Removing msgset
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 demonstrates how you could allow
msgset
but only support the simpler
alternative.
Example 5-3. Removing msgentry
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. Example 5-4 is a customization that
does this.
Example 5-4. Removing computer inlines
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 following
notAllowed
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
db.programming.inlines
: programming-related
inlines
Be aware that a customization layer that removed this many technical inlines would also remove some larger technical structures or make them unusable.
Another possibility is removing the complex synopsis
elements. The customization layer in Example 5-5
removes cmdsynopsis
and
funcsynopsis
.
Perhaps you want to restrict your authors to only three
levels of sectioning. To do that, you could remove the
sect4
and sect5
elements, as shown
in Example 5-6.
Example 5-6. Removing the 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,
which you could require them to do by removing the
section
element. But suppose instead you want to
allow them to use recursive sections, but 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.
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.
Example 5-8. Limiting recursive sections to three levels using Schematron
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* } }
In this example, we’ve put the Schematron pattern inline in the RELAX NG grammar. If your validation strategy requires that they be in a separate document, it may be more convenient to simply create them separately.
Sometimes what you want to do is not as simple as entirely removing an element. Instead, you may want to remove it only from some contexts. The way to do this 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 the
entry
element, as shown in Example 5-9.
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. If you think some refactoring would make your job easier, feel free to ask.