5 Customizing DocBook

$Revision: 1.2 $

$Date: 2005/07/07 16:41:50 $

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.

If You Change DocBook, It's Not DocBook Anymore!

The DocBook DTD is usually referenced by its public identifier:

  -//OASIS//DTD DocBook V3.1//EN

Previous versions of DocBook, V3.0 and the V2 variants, used the owner identifier Davenport, rather than OASIS.

If you make any changes to the structure of the DTD, it is imperative that you alter the public identifier that you use for the DTD and the modules you changed. The license agreement under which DocBook is distributed gives you complete freedom to change, modify, reuse, and generally hack the DTD in any way you want, except that you must not call your alterations “DocBook.”

You should change both the owner identifier and the description. The original DocBook formal public identifiers use the following syntax:

-//OASIS//text-class DocBook description Vversion//EN

Your own formal public identifiers should use the following syntax in order to record their DocBook derivation:

-//your-owner-ID//text-class DocBook Vversion-Based [Subset|Extension|Variant] your-descrip-and-version//lang

For example:

-//O'Reilly//DTD DocBook V3.0-Based Subset V1.1//EN

If your DTD is a proper subset, you can advertise this status by using the Subset keyword in the description. If your DTD contains any markup model extensions, you can advertise this status by using the Extension keyword. If you'd rather not characterize your variant specifically as a subset or an extension, you can leave out this field entirely, or, if you prefer, use the Variant keyword.

There is only one file that you may change without changing the public identifier: dbgenent.mod. And you can add only entity and notation declarations to that file. (You can add anything you want, naturally, but if you add anything other than entity and notation declarations, you must change the public identifier!)

Customization Layers

FIXME: discuss customizing DocBook V5.0


Publishing DocBook Documents		Part II. Reference