Menu

Customizing the DocBook DTD, Part 3

October 20, 1999

Leonard Muellner and Norman Walsh

The General Structure of Customization Layers

Although customization layers vary in complexity, most of them have the same general structure as other customization layers of similar complexity.

In the most common case, you probably want to include the entire DTD, but you want to make some small changes. These customization layers tend to look like this:

(1) Overrides of Entity Declarations Here



(2) <!ENTITY % orig-docbook "-//OASIS//DTD DocBook V3.1//EN">

 %orig-docbook;



(3) New/Modified Element and Attribute Declarations Here
(1) Declare new values for parameter entities (%local.*;, %*.element;, %*.attlist;) that you wish to modify.
(2) Include the entire DocBook DTD by parameter entity reference.
(3) Add new element and attribute declarations for any elements that you added to the DTD.

In slightly more complex customization layers, the changes that you want to make are influenced by the interactions between modules. In these cases, rather than including the whole DTD at once, you include each of the modules separately, perhaps with entity or element declarations between them:

Overrides of Most Entity Declarations Here



<!ENTITY % orig-pool "-//OASIS//ELEMENTS DocBook Information Pool V3.1//EN">

%orig-pool;



Overrides of Document Hierarchy Entities Here



<!ENTITY % orig-hier "-//OASIS//ELEMENTS DocBook Document Hierarchy V3.1//EN">

%orig-hier;



New/Modified Element and Attribute Declarations Here



<!ENTITY % orig-notn "-//OASIS//ENTITIES DocBook Notations V3.1//EN">

%orig-notn;



<!ENTITY % orig-cent "-//OASIS//ENTITIES DocBook Character Entities V3.1//EN">

%orig-cent;



<!ENTITY % orig-gen "-//OASIS//ENTITIES DocBook Additional General Entities V3.1//EN">

%orig-gen;

Finally, it's worth noting that in the rare case in which you need certain kinds of very simple, "one-off" customizations, you can do them in the document subset:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [

Overrides of Entity Declarations Here

New/Modified Element and Attribute Declarations Here

]>

<book>...</book>

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.

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 1.

Example 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.

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).

Testing Your Work

DTDs, by their nature, contain many complex, interrelated elements. Whenever you make a change to the DTD, it's always wise to use a validating parser to double-check your work. A parser like nsgmls from James Clark's SP can identify elements (attributes, parameter entities) that are declared but unused, as well as ones that are used but undeclared.

A comprehensive test can be accomplished with nsgmls using the -wall option. Create a simple test document and run:

nsgmls (1)-sv  

(2)
-wall test.sgm
(1)
The -s option tells nsgmls to suppress its normal output (it will still show errors, if there are any). The -v option tells nsgmls to print its version number; this ensures that you always get some output, even if there are no errors.
(2)
The -wall option tells nsgmls to provide a comprehensive list of all errors and warnings. You can use less verbose, and more specific options instead; for example, -wundefined to flag undefined elements or -wunused-param to warn you about unused parameter entities. The nsgmls documentation provides a complete list of warning types.

DocBook V3.1 Warnings

If you run the preceding command over DocBook V3.1, you'll discover one warning generated by the DTD:

nsgmls:I: SP version "1.3"

nsgmls:cals-tbl.dtd:314:37:W: content model is mixed but does not allow #PCDATA everywhere

This is not truly an error in the DTD, and can safely be ignored. The warning is caused by "pernicious mixed content" in the content model of DocBook's Entry element. See the Entry reference page for a complete discussion.

Removing Elements

DocBook has a large number of elements. In some authoring environments, it may be useful or necessary to remove some of these elements.

Removing MsgSet

MsgSet 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 2 shows a customization layer that removes the MsgSet element from DocBook:

Example 2. Removing MsgSet

<!ENTITY % compound.class "Procedure|SideBar"> (1)

<!ENTITY % msgset.content.module "IGNORE">     (2)

<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;
(1)
Remove MsgSet from the %compound.class;. This is the only place in the DTD where MsgSet is referenced.
(2)
Exclude the definition of MsgSet and all of its subelements from the DTD.

Removing Computer Inlines

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. You can remove a bunch of them by redefining the %tech.char.class; parameter entity and then excluding the declarations for the elements removed. The initial definition of %tech.char.class; is:

<!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|Markup|MediaLabel|MenuChoice

    |MouseButton|MsgText|Option|Optional|Parameter|Prompt|Property

    |Replaceable|ReturnValue|SGMLTag|StructField|StructName

    |Symbol|SystemItem|Token|Type|UserInput

    %local.tech.char.class;">

When examining this list, it seems that you can delete all of the inlines except, perhaps, Application, Command, Email, Filename, Literal, Replaceable, Symbol, and SystemItem. The following customization layer removes them.

Example 3. Removing Computer Inlines

<!ENTITY % tech.char.class

        "Application|Command|Email|Filename|Literal

        |Replaceable|Symbol|SystemItem">

<!ENTITY % action.module "IGNORE">

<!ENTITY % classname.module "IGNORE">

<!ENTITY % computeroutput.module "IGNORE">

<!ENTITY % database.module "IGNORE">

<!ENTITY % envar.module "IGNORE">

<!ENTITY % errorcode.module "IGNORE">

<!ENTITY % errorname.module "IGNORE">

<!ENTITY % errortype.module "IGNORE">

<!--<!ENTITY % function.module "IGNORE">-->

<!ENTITY % guibutton.module "IGNORE">

<!ENTITY % guiicon.module "IGNORE">

<!ENTITY % guilabel.module "IGNORE">

<!ENTITY % guimenu.module "IGNORE">

<!ENTITY % guimenuitem.module "IGNORE">

<!ENTITY % guisubmenu.module "IGNORE">

<!ENTITY % hardware.module "IGNORE">

<!ENTITY % interface.module "IGNORE">

<!ENTITY % interfacedefinition.module "IGNORE">

<!--<!ENTITY % keycap.module "IGNORE">-->

<!ENTITY % keycode.module "IGNORE">

<!--<!ENTITY % keycombo.module "IGNORE">-->

<!--<!ENTITY % keysym.module "IGNORE">-->

<!ENTITY % markup.module "IGNORE">

<!ENTITY % medialabel.module "IGNORE">

<!ENTITY % menuchoice.module "IGNORE">

<!--<!ENTITY % mousebutton.module "IGNORE">-->

<!--<!ENTITY % msgtext.module "IGNORE">-->

<!--<!ENTITY % option.module "IGNORE">-->

<!--<!ENTITY % optional.module "IGNORE">-->

<!--<!ENTITY % parameter.module "IGNORE">-->

<!ENTITY % prompt.module "IGNORE">

<!ENTITY % property.module "IGNORE">

<!ENTITY % returnvalue.module "IGNORE">

<!ENTITY % sgmltag.module "IGNORE">

<!ENTITY % structfield.module "IGNORE">

<!ENTITY % structname.module "IGNORE">

<!ENTITY % token.module "IGNORE">

<!ENTITY % type.module "IGNORE">

<!ENTITY % userinput.module "IGNORE">

<!-- load DocBook --> 

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

Initially we removed several more elements from %tech.char.class; (%function.module;, %keycap.module;), but using the testing procedure described in the section called Testing Your Work, we discovered that these elements are used in other content models. Because they are used in other content modules, they cannot simply be removed from the DTD by deleting them from %tech.char.class;. Even though they can't be deleted outright, we've taken them out of most inline contexts.

It's likely that a customization layer that removed this many technical inlines would also remove some larger technical structures (MsgSet, FuncSynopsis), which allows you to remove additional elements from the DTD.

Removing Synopsis Elements

Another possibility is removing the complex Synopsis elements. The customization layer in Example 4 removes CmdSynopsis and FuncSynopsis.

Example 4. Removing CmdSynopsis and FuncSynopsis

<!ENTITY % synop.class "Synopsis">

<!-- Instead of "Synopsis|CmdSynopsis|FuncSynopsis %local.synop.class;" -->



<!ENTITY % funcsynopsis.content.module "IGNORE">

<!ENTITY % cmdsynsynopsis.content.module "IGNORE">



<!-- load DocBook --> 

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

Completely removing all Synopsis elements would require a more extensive customization. You can't make any of the %*.class; parameter entities completely empty without changing all of the parameter entities that use them. See the section called Removing an Entire Class.

Removing Sectioning Elements

Perhaps you want to restrict your authors to only three levels of sectioning. To do that, you must remove the Sect4 and Sect5 elements, as shown in Example 5.

Example 5. Removing Sect4 and Sect5 Elements

In order to completely remove an element that isn't in the information pool, it is usually necessary to redefine the elements that include it. In this case, because we're removing the Sect4 element, we must redefine the Sect3 element that uses it.

Removing Admonitions from Table Entries

All of the customization layers that we've examined so far have been fairly straightforward. This section describes a much more complex customization layer. Back in the section called DocBook Modules we mentioned that several additional modules existed for redeclaration. The customization layer developed in this section cannot be written without them.

The goal is to remove admonitions (Warning, Caution, Note) from table entries.

Example 6 is a straightforward, and incorrect, attempt.

Example 6. Removing Admonitions (First Attempt: Incorrect)

<!-- THIS CUSTOMIZATION LAYER CONTAINS ERRORS -->

<!ENTITY % tabentry.mix

        "%list.class;

        |%linespecific.class;

        |%para.class;        |Graphic

        %local.tabentry.mix;">

<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

Because the parameter entity %tabentry.mix; defines the mixture of elements allowed in table entries, you should remove admonitions.

If you attempt to parse this DTD, you'll find that the declaration of %tabentry.mix; contains errors. While you can redefine parameter entities, you cannot make reference to entities that have not been defined yet, so the use of %list.class;, %linespecific.class;, and so on, aren't allowed.

Your second attempt might look like Example 7.

Example 7. Removing Admonitions (Second Attempt: Incorrect)

<!-- THIS CUSTOMIZATION LAYER DOESN'T WORK -->

<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

<!ENTITY % tabentry.mix

        "%list.class;

        |%linespecific.class;

        |%para.class;        |Graphic

        %local.tabentry.mix;">

Declaring %tabentry.mix; after the DTD has been loaded removes the errors.

This example contains no errors, but it also doesn't have any effect. Remember, only the first entity declaration counts, so the declaration of %tabentry.mix; in dbpool.mod is the one used, not your redeclaration.

The only way to fix this problem is to make use of one of the redeclaration placeholders in DocBook.

Redeclaration placeholders are spots in which you can insert definitions into the middle of the DTD. There are four redeclaration placeholders in DocBook:

Parameter Entities Description
%rdbmods;

 

Inserted in docbook.dtd, between dbpool.mod and dbhier.mod. This placeholder is controlled by the %intermod.redecl.module; marked section.

%rdbpool; Inserted in the middle of dbpool.mod, between the %*.class; and %*.mix; entity declarations. This placeholder is controlled by the %dbpool.redecl.module; marked section.
%rdbhier;

Inserted in the middle of dbhier.mod, between the %*.class; and %*.mix; entity declarations. This placeholder is controlled by the %dbhier.redecl.module; marked section.

%rdbhier2;

Also inserted into dbhier.mod, after the %*.mix; entity declarations. This placeholder is controlled by the %dbhier.redecl2.module; marked section.

Use the redeclaration placeholder that it occurs nearest to, but before the entity that you want to redeclare. In our case, this is %rdbpool;, as seen in Example 8.

Example 8. Removing Admonitions (Third Attempt: Correct, if confusing)

<!ENTITY % dbpool.redecl.module "INCLUDE">

<!ENTITY % rdbpool

'<!ENTITY % local.tabentry.mix "">

<!ENTITY % tabentry.mix

        "&#37;list.class;

        |&#37;linespecific.class;

        |&#37;para.class;        |Graphic

        &#37;local.tabentry.mix;">'>



<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

Example 8 uses numeric character entity references to escape the % signs in the entity declarations and nests an entity declaration in another parameter entity. All of this is perfectly legal, but a bit confusing. A clearer solution, and the only practical solution if you're doing anything more than a single redeclaration, is to place the new declarations in another file and include them in your customization layer by reference, like this:

Example 9. Removing Admonitions (Fourth Attempt: Correct)

In your customization layer:

<!ENTITY % dbpool.redecl.module "INCLUDE">
<!ENTITY % rdbpool SYSTEM "rdbpool.mod">

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

In rdbpool.mod:

<!ENTITY % local.tabentry.mix "">
<!ENTITY % tabentry.mix
        "%list.class;
        |%linespecific.class;
        |%para.class;        |Graphic
        %local.tabentry.mix;">

Removing an Entire Class

Perhaps the modification that you want to make is to completely remove an entire class of elements. (If you have no need for synopsis elements of any sort, why not remove them?) In order to remove an entire class of elements, you must not only redefine the class as empty, but you must also redefine all of the parameter entities that use that class. The customization layer below completely removes the % synop.class; from DocBook. It requires a customization layer, shown in Example 10, that includes both a redeclaration module in dbpool.mod and a redeclaration module in dbhier.mod.

Example 10. Removing %synop.class;

In the customization layer:

<!ENTITY % synop.class "">



<!ENTITY % dbpool.redecl.module "INCLUDE">

<!ENTITY % rdbpool SYSTEM "remv.synop.class.rdbpool.mod">



<!ENTITY % dbhier.redecl.module "INCLUDE">

<!ENTITY % rdbhier SYSTEM "remv.synop.class.rdbhier.mod">



<!-- load DocBook --> 

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> 

%DocBookDTD;

In remv.synop.class.rdbpool.mod:

<!ENTITY % local.component.mix "">

<!ENTITY % component.mix

		"%list.class;		|%admon.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;		|%compound.class;

		|%genobj.class;		|%descobj.class;

		%local.component.mix;">



<!ENTITY % local.sidebar.mix "">

<!ENTITY % sidebar.mix

		"%list.class;		|%admon.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;		|Procedure

		|%genobj.class;

		%local.sidebar.mix;">



<!ENTITY % local.footnote.mix "">

<!ENTITY % footnote.mix

		"%list.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		%local.footnote.mix;">



<!ENTITY % local.example.mix "">

<!ENTITY % example.mix

		"%list.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		%local.example.mix;">



<!ENTITY % local.admon.mix "">

<!ENTITY % admon.mix

		"%list.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;		|Procedure|Sidebar

		|Anchor|BridgeHead|Comment

		%local.admon.mix;">



<!ENTITY % local.figure.mix "">

<!ENTITY % figure.mix

		"%linespecific.class;

					|%informal.class;

		%local.figure.mix;">



<!ENTITY % local.glossdef.mix "">

<!ENTITY % glossdef.mix

		"%list.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;

		|Comment

		%local.glossdef.mix;">



<!ENTITY % local.para.char.mix "">

<!ENTITY % para.char.mix

		"#PCDATA

		|%xref.char.class;	|%gen.char.class;

		|%link.char.class;	|%tech.char.class;

		|%base.char.class;	|%docinfo.char.class;

		|%other.char.class;	|%inlineobj.char.class;

		%local.para.char.mix;">

In remv.synop.class.rdbhier.mod:

<!ENTITY % local.divcomponent.mix "">

<!ENTITY % divcomponent.mix

		"%list.class;		|%admon.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;		|%compound.class;

		|%genobj.class;		|%descobj.class;

		%local.divcomponent.mix;">



<!ENTITY % local.refcomponent.mix "">

<!ENTITY % refcomponent.mix

		"%list.class;		|%admon.class;

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|%formal.class;		|%compound.class;

		|%genobj.class;		|%descobj.class;

		%local.refcomponent.mix;">



<!ENTITY % local.indexdivcomponent.mix "">

<!ENTITY % indexdivcomponent.mix

		"ItemizedList|OrderedList|VariableList|SimpleList

		|%linespecific.class;

		|%para.class;		|%informal.class;

		|Anchor|Comment

		|%link.char.class;

		%local.indexdivcomponent.mix;">

Removing Attributes

Just as there may be more elements than you need, there may be more attributes.

Removing an Attribute

Suppose you want to remove the RenderAs attribute from the Sect1 element. RenderAs allows the author to cheat in the presentation of hierarchy by specifying that the stylesheet should render a Sect1 as something else: a Sect3, perhaps. Example 11 details the removal of RenderAs.

Example 11. Removing RenderAs from Sect1

<!ENTITY % sect1.module "IGNORE">                (1)



<!-- load DocBook -->                            (2)

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;



<!ENTITY % local.sect1.attrib "">                (3)

<!ENTITY % sect1.role.attrib "%role.attrib;">    (4)

<!ELEMENT Sect1 - O (Sect1Info?, (%sect.title.content;), (%nav.class;)*,  (5)

        (((%divcomponent.mix;)+, 

        ((%refentry.class;)* | Sect2* | SimpleSect*))

        | (%refentry.class;)+ | Sect2+ | SimpleSect+), (%nav.class;)*)

        +(%ubiq.mix;)>

<!ATTLIST Sect1                                  (6)

        %label.attrib;

        %status.attrib;

        %common.attrib;

        %sect1.role.attrib;

        %local.sect1.attrib;

>
(1)
Turn off the Sect1 module so that the element and attribute declarations in the DTD will be ignored.
(2)
Include the DocBook DTD.
(3)
By keeping the local attribute declaration, we leave open the possibility of a simple customization layer on top of our customization layer.
(4)
Similarly, we keep the parameterized definition of the Role attribute.
(5)
We're changing the attribute list, not the element, so we've simply copied the Sect1 element declaration from the DocBook DTD.
(6)
Finally, we declare the attribute list, leaving out the RenderAs.

Subsetting the Common Attributes

DocBook defines eleven common attributes; these attributes appear on every element. Depending on how you're processing your documents, removing some of them can both simplify the authoring task and improve processing speed.

Some obvious candidates are:

Effectivity attributes (Arch, OS,...)

If you're not using all of the effectivity attributes in your documents, you can get rid of up to seven attributes in one fell swoop.

Lang

If you're not producing multilingual documents, you can remove Lang.

Remap

The Remap attribute is designed to hold the name of a semantically equivalent construct from a previous markup scheme (for example, a Microsoft Word style template name, if you're converting from Word). If you're authoring from scratch, or not preserving previous constructs with Remap, you can get rid of it.

XrefLabel

If your processing system isn't using XrefLabel, it's a candidate as well.

The customization layer in Example 12 reduces the common attributes to just ID and Lang.

Example 12. Removing Common Attributes

<!ENTITY % common.attrib

"ID   ID    #IMPLIED

 Lang CDATA #IMPLIED">

<!ENTITY % idreq.common.attrib

"ID   ID    #REQUIRED

 Lang CDATA #IMPLIED">

<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

By definition, whatever attributes you define in the %common.attrib; and %idreq.common.attrib; parameter entities are the common attributes. In dbpool.mod , these parameter entities are defined in terms of other parameter entities, but there's no way to preserve that structure in your customization layer.

Adding Elements: Adding a Sect6

Adding a structural (as opposed to information pool) element generally requires adding its name to a class and then providing the appropriate definitions. Example 13 extends DocBook by adding a Sect6 element.

Example 13. Adding a Sect6 Element

<!ENTITY % sect5.module "IGNORE">

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

<!-- Add Sect6 to content model of Sect5 -->

<!ENTITY % sect5.role.attrib "%role.attrib;">

<!ELEMENT Sect5 - O (Sect5Info?, (%sect.title.content;), (%nav.class;)*,

        (((%divcomponent.mix;)+, 

                ((%refentry.class;)* | Sect6* | SimpleSect*))

        | (%refentry.class;)+ | Sect6+ | SimpleSect+), (%nav.class;)*)>

<!ATTLIST Sect5

        %label.attrib;

        %status.attrib;

        %common.attrib;

        %sect5.role.attrib;

>

<!ENTITY % sect6.role.attrib "%role.attrib;">

<!ELEMENT Sect6 - O (Sect6Info?, (%sect.title.content;), (%nav.class;)*,

        (((%divcomponent.mix;)+, ((%refentry.class;)* | SimpleSect*))

        | (%refentry.class;)+ | SimpleSect+), (%nav.class;)*)>

<!ATTLIST Sect6

        %label.attrib;

        %status.attrib;

        %common.attrib;

        %sect6.role.attrib;

>

Here we've redefined Sect5 to include Sect6 and provided a declaration for Sect6. Note that we didn't bother to provide RenderAs attributes in our redefinitions. To properly support Sect6, you might want to redefine all of the sectioning elements so that Sect6 is a legal attribute value for RenderAs.

Other Modifications: Classifying a Role

The Role attribute, found on almost all of the elements in DocBook, is a CDATA attribute that can be used to subclass an element. In some applications, it may be useful to modify the definition of Role so that authors must choose one of a specific set of possible values.

In Example 14, Role on the Procedure element is constrained to the values Required or Optional.

Example 14. Changing Role on Procedure

<!ENTITY % procedure.role.attrib "Role (Required|Optional) #IMPLIED">

<!-- load DocBook -->

<!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

You can read more about DocBook in DocBook: The Definitive Guide available in print from O'Reilly & Associates, Inc. and online at OASIS and docbook.org, the official home page for DocBook: The Definitive Guide.