Writing, Testing, and Using a Customization Layer

The procedure for creating, testing, and using a customization layer is always about the same. In this section, we'll go through the process in some detail. The rest of the sections in this chapter describe a range of useful customization layers.

Deciding What to Change

If you're considering writing a customization layer, there must be something that you want to change. Perhaps you want to add an element or attribute, remove one, or change some other aspect of the DTD.

Adding an element, particularly an inline element, is one possibility. If you're writing documentation about an object-oriented system, you may have noticed that DocBook provides ClassName but not MethodName. Suppose you want to add MethodName?

Deciding How to Change a Customization Layer

Figuring out what to change may be the hardest part of the process. The organization of the parameter entities is quite logical, and, bearing in mind the organization described in the Section called Understanding DocBook Structure, finding something similar usually provides a good model for new changes.

Two online resources may be useful. First, the parameter entity reference section of the online book provides more detail than the print version. Second, there is an alternate version of the book online that shows all of the element content models in terms of the parameter entities that define them, rather than the "flattened" versions shown here.

One resource that may be useful is the alternate version of this book that shows all of the element content models in terms of the parameter entities which define them, rather than the "flattened" versions shown here. The alternate version is on the CD-ROM and online at the book web site: http://docbook.org/.

MethodName is similar to ClassName, so ClassName is probably a good model. ClassName is an inline element, not a hierarchy element, so it's in dbpool.mod. Searching for "classname" in dbpool.mod reveals:


<!ENTITY % local.tech.char.class "">
<!ENTITY % tech.char.class
        "Action|Application|ClassName|Command|ComputerOutput
        |Database|Email|EnVar|ErrorCode|ErrorName|ErrorType|Filename
        |Function|GUIButton|GUIIcon|GUILabel|GUIMenu|GUIMenuItem
        |GUISubmenu|Hardware|Interface|InterfaceDefinition|KeyCap
        |KeyCode|KeyCombo|KeySym|Literal|Constant|Markup|MediaLabel
        |MenuChoice|MouseButton|MsgText|Option|Optional|Parameter
        |Prompt|Property|Replaceable|ReturnValue|SGMLTag|StructField
        |StructName|Symbol|SystemItem|Token|Type|UserInput|VarName
        %local.tech.char.class;">

Searching further reveals the element and attribute declarations for ClassName.

It would seem (and, in fact, it is the case) that adding MethodName can be accomplished by adding it to the local extension mechanism for tech.char.class, namely local.tech.char.class, and adding element and attribute declarations for it. A customization layer that does this can be seen in Example 5-1.

Example 5-1. Adding MethodName with a Customization Layer


<!ENTITY % local.tech.char.class "|MethodName">     (1)

<!-- load DocBook -->                               (2)
<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
%DocBookDTD;

<!ELEMENT MethodName - - ((%smallcptr.char.mix;)+)  (3)>
<!ATTLIST MethodName                                (4)
        %common.attrib;
        %classname.role.attrib;
        %local.classname.attrib;
>
(1)
Declare the appropriate parameter entity (these are described in the Section called DocBook Parameterization). The declaration in your customization layer is encountered first, so it overrides the definition in the DocBook DTD (all the local classes are defined as empty in the DTD).
(2)
Use a parameter entity to load the entire DocBook DTD.
(3)
Add an element declaration for the new element. The content model for this element is taken directly from the content model of ClassName.
(4)
Add an attribute list declaration for the new element. These are the same attributes as ClassName.

Using Your Customization Layer

In order to use the new customization layer, you must save it in a file, for example mydocbk.dtd, and then you must use the new DTD in your document.

The simplest way to use the new DTD is to point to it with a system identifier:


<!DOCTYPE chapter SYSTEM "/path/to/mydocbk.dtd">
<chapter><title>My Chapter</title>
<para>
The Java <classname>Math</classname> class provides a 
<methodname>abs</methodname> method to compute absolute value of a number.
</para>
</chapter>

If you plan to use your customization layer in many documents, or exchange it with interchange partners, consider giving your DTD its own public identifier, as described in the Section called If You Change DocBook, It's Not DocBook Anymore!

In order to use the new public identifier, you must add it to your catalog:


PUBLIC "-//Your Organization//DTD DocBook V3.1-Based Extension V1.0//EN"
       "/share/sgml/mydocbk.dtd"
and use that public identifier in your documents:


<!DOCTYPE chapter 
  PUBLIC "-//Your Organization//DTD DocBook V3.1-Based Extension V1.0//EN">
<chapter><title>My Chapter</title>
<para>
The Java <classname>Math</classname> class provides a 
<methodname>abs</methodname> method to compute absolute value of a number.
</para>
</chapter>

If you're using XML, remember that you must provide a system identifier that satisfies the requirements of a Uniform Resource Identifier (URI).