Customizing the DocBook DTD
An Excerpt from DocBook: The Definitive Guide
DocBook is a system for writing structured documents using SGML and XML. DocBook provides all the elements you'll need to author and publish technical documents of all kinds. Many computer companies use DocBook for their documentation, as do several Open Source documentation groups. DocBook allows these groups to readily share and exchange information.
DocBook: The Definitive Guide is the complete and official documentation of the DocBook Document Type Definition (DTD) and many of its associated tools.
This excerpt is from Chapter 5, Customizing DocBook. Not surprisingly, the specific examples in this excerpt relate to DocBook, but the principles apply to any DTD that you may write or use. The only real requirement is that the DTD be appropriately parameterized. In particular:
-
Content models must be defined in parameter entities.
-
It's very useful to have element and attribute declarations inside marked sections (so that they can be selectively removed).
-
Common content models should be parameterized the same way. (With the same parameter entity.)
-
Content model parameter entities can be made much more useful for parameterization by including a "local" extension mechanism.
A close examination of DocBook, particularly the dbpool.mod module provides good examples of each of these techniques. With these concepts in mind, let's look at Chapter 5:
For the applications you have in mind, DocBook out of the box may not be exactly what you need. Perhaps you need additional inline elements or perhaps you want to remove elements that you never want your authors to use. By design, DocBook makes this sort of customization easy.
This chapter explains how to make your own customization layer. You might do this in order to:
-
Add new elements
-
Remove elements
-
Change the structure of existing elements
-
Add new attributes
-
Remove attributes
-
Broaden the range of values allowed in an attribute
-
Narrow the range of values in an attribute to a specific list or a fixed value
You can use customization layers to extend DocBook or subset it. Creating a DTD that is a strict subset of DocBook means that all of your instances are still completely valid DocBook instances, which may be important to your tools and stylesheets, and to other people with whom you share documents. An extension adds new structures, or changes the DTD in a way that is not compatible with DocBook. Extensions can be very useful, but might have a great impact on your environment.
Customization layers can be as small as restricting an attribute value or as large as adding an entirely different hierarchy on top of the inline elements.
Should You Do This?
Changing a DTD can have a wide-ranging impact on the tools and stylesheets that you use. It can have an impact on your authors and on your legacy documents. This is especially true if you make an extension. If you rely on your support staff to install and maintain your authoring and publishing tools, check with them before you invest a lot of time modifying the DTD. There may be additional issues that are outside your immediate control. Proceed with caution.
That said, DocBook is designed to be easy to modify. This chapter assumes that you are comfortable with SGML/XML DTD syntax, but the examples presented should be a good springboard to learning the syntax if it's not already familiar to you.
Note that if you change DocBook, it isn't DocBook anymore! You must change the public identifiers used.
Customization Layers
SGML and XML DTDs are really just collections of declarations. These declarations are stored in one or more files. A complete DTD is formed by combining these files together logically. Parameter entities are used for this purpose. Consider the following fragment:
<!ENTITY % dbpool SYSTEM "dbpool.mod"><!ENTITY % dbhier SYSTEM "dbhier.mod">
%dbpool;
%dbhier;
- This line declares the parameter entity dbpool and associates it with the file dbpool.mod.
- This line declares the parameter entity dbhier and associates it with the file dbhier.mod.
- This line references dbpool, which loads the file dbpool.mod and inserts its content here.
- Similarly, this line loads dbhier.mod.
It is an important feature of DTD parsing that entity declarations can be repeated. If an entity is declared more than once, then the first declaration is used. Given this fragment:
<!ENTITY foo "Lenny"> <!ENTITY foo "Norm">
The replacement text for &foo; is Lenny.
These two notions, that you can break a DTD into modules referenced with parameter entities and that the first entity declaration is the one that counts, are used to build “customization layers.” With customization layers you can write a DTD that references some or all of DocBook, but adds your own modifications. Modifying the DTD this way means that you never have to edit the DocBook modules directly, which is a tremendous boon to maintaining your modules. When the next release of DocBook comes out, you usually only have to make changes to your customization layer and your modification will be back in sync with the new version.
Customization layers work particularly well in DocBook because the base DTD makes extensive use of parameter entities that can be redefined.
