Customization Specifics

Customizing Classes and Mixtures

Elements in the information pool are generally grouped by "class." For example, one class consists of all the list-related elements. (In some cases, classes consist of non-element keywords, such as the names of non-SGML notations.) Each class is stored in a parameter entity with the naming pattern xxx.class, or xxx.char.class if it contains inline elements. The general form of a class entity is a series of names, along with a placeholder entity, separated by vertical bars. For example:

"element1|element2|element3 %local.elem.class;"

References to class entities are used primarily as building blocks in the construction of "mixtures,"repeatable-OR groups that appear in multiple content models. An example of a mixture is the "component mixture," which contains all the block-oriented elements in DocBook and is used in many content models.

Each mixture is stored in a parameter entity with the naming pattern xxx.mix, or xxx.char.mix if it contains inline elements and #PCDATA. The general form of a mixture entity is a series of references to class entities, along with a placeholder entity, separated by vertical bars. For example:

"%foo.class;|%bar.class; %local.elem.mix;"

Mixture entities are referenced only from within content models. The references are always surrounded with group delimiters and always have an * or + occurrence indicator on them.

A unique placeholder entity appears in every class and mixture entity. Each placeholder entity has the naming pattern local.xxx, and is defined to be an empty string by default.

To extend the available choices of elements in either a class (which will affect all the mixtures that reference the class) or a mixture (which will affect only the elements that reference the mixture), redeclare the appropriate placeholder entity to contain first a vertical bar (|) and then any number of additional elements, themselves separate by vertical bars. For example, to extend the list class:

<!ENTITY % local.list.class "|LaundryList|ShoppingList">

To remove elements from the available choices in a class or mixture, or to remove some elements and add some others, redeclare the whole class or mixture entity, leaving out the placeholder entity reference. For example, to restructure the list class to remove SimpleList and Add LaundryList:

<!ENTITY % list.class
                "GlossList|ItemizedList|OrderedList|SegmentedList
                |VariableList|LaundryList">

Customizing Content Model Fragments

Some content model fragments (other than element mixtures) are common to multiple elements. For example, all the formal block-oriented elements (such as Example and Figure) require a Title and allow it to be followed by a TitleAbbrev. In cases where there may be a need to customize the fragment, it is stored in a parameter entity with the naming pattern xxx.content. The general form of a content model entity is a fragment that can function as a group. For example:

"Title, TitleAbbrev?"

To customize a fragment, either to extend it or to create a subset, redeclare the entity. For example, to eliminate TitleAbbrev from formal elements (which creates a subset):

<!ENTITY % formalobject.title.content "Title">

Customizing Attribute Lists and Attributes

Some attributes and sets of attributes appear on multiple elements. For example, the "common attributes" appear on nearly every element available in DocBook. Each such attribute and attribute set is stored in a parameter entity with the naming pattern xxx.attrib. The general form of an attribute entity is to have all three attribute definition fields—name, declared value, and default value—for each entity, along with a placeholder entity in some cases. For example:

"Id      ID              #IMPLIED
Class    (Value1|Value2) Value1
%local.foo.attrib;"

To extend the list of attributes on a set of elements that refer to the same attribute entity, redeclare the appropriate placeholder entity to contain a one or more sets of attribute fields. For example, to extend the common attribute entity:

<!ENTITY % local.common.attrib
"Secur   (None|Confid)   None">

To remove attributes from a set of elements that refer to the same attribute entity, or to remove some attributes and add some others, redeclare the whole attribute entity (leaving out the placeholder entity reference). For example, to restructure the common attributes to remove everything but ID and to add Secur:

<!ENTITY % common.attrib
"Id      ID              #IMPLIED
 Secur   (None|Confid)   None">

The attribute list declaration for every element in DocBook has a placeholder for the addition of new attributes. Each such placeholder is stored in a parameter entity with the naming pattern local.xxx.attrib. By default, the entity is empty. Typically, this entity would be redeclared to provide #FIXED attribute values that map the DocBook elements to architectural forms.

Some attribute declared values ("data types") and default values are stored in parameter entities for reasons of self-documentation. Attribute declared values are stored in a parameter entity with the naming pattern xxx.attvals, and attribute default values use the naming pattern xxx.attval.

Removing, Replacing, and Renaming Elements

Every pair of ELEMENT/ATTLIST declarations, and some groupings of these pairs, can be considered a miniature module in a DocBook "element library" that you may or may not want to use in your variant, with or without further customization. For example, if you plan not to support SegmentedList processing in your environment, you may want to remove the element and all its subelements from your variant of DocBook so that authors do not mistakenly insert segmented lists into their documents.

Each of these pairs and groupings of pairs is in its own marked section, with the status keyword for the marked section stored in a parameter entity. The expected content for a module entity is either the INCLUDE keyword or the IGNORE keyword; INCLUDE is defined for all the module entities (except one special entity discussed in the Section called Redeclaring Entities That Reference Other Entities) by default.

The parameter entities have the naming pattern xxx.module (for individual pairs) or xxx.content.module (for groupings of pairs where the subelements are referenced only in the content models of the higher-level elements). For example, the revhistory.content.module marked section controls the ELEMENT/ATTLIST declarations for RevHistory, Revision, RevNumber, and RevRemark declarations (but not Date, since it can be used without appearing in RevHistory); the revhistory.module marked section controls only the declarations for RevHistory.

These marked section entities are very powerful because they allow you to remove an element entirely or to remove it and replace it with your own variant ELEMENT/ATTLIST declarations. Use them judiciously, and if possible, use regular entity redeclaration instead of redeclaring the whole element.

To remove an element or group of elements, redeclare its marked section entity as IGNORE and redeclare any entities (and elements, by ignoring them as well) whose definitions mention the removed element(s). For example, to remove SegmentedList:

<!ENTITY % segmentedlist.content.module "IGNORE">
<!ENTITY % list.class
                "GlossList|ItemizedList|OrderedList
                |SimpleList|VariableList">

Note that you have a choice about removing the module. For example, if your editing software will present SegmentedList to authors even once it is removed from all content models, you may want to remove the module through the IGNORE value, but if authors will never have the chance to insert SegmentedList mistakenly, the redeclaration of the marked section entity isn't strictly necessary. However, doing so serves a documentation function for DTD readers.

To replace an element or group of elements with a variant set of declarations, redeclare its marked section entity as IGNORE, and provide replacement ELEMENT/ATTLIST declarations. For example, to restrict the content of Chapter:

<!ENTITY % chapter.module "IGNORE">
⋮
after referencing the doc hierarchy module, so the sect1.content entity can be referenced
<!ELEMENT Chapter - - (Title, (%sect1.content;)) +(%ubiq.mix;)>
<!ATTLIST Chapter
        %common.attrib;
        %label.attrib;
>

To rename an element or group of elements with a variant set of declarations, redeclare its marked section entity as IGNORE, provide replacement ELEMENT/ATTLIST declarations, and redeclare any entities (and elements, by ignoring them as well) whose definitions mention the renamed element(s). Renaming elements through DTD customization is not recommended; instead, you should investigate customizing your authoring software to have it present alternative element names to users.

Redeclaring Entities That Reference Other Entities

DocBook's architecture results in several well-defined general cases where the declarations of some entities contain references to other entities;

• Some mixture entities and content models in the information pool and document hierarchy modules reference pool-specific class entities.

• Some mixture entities and content models in the document hierarchy module reference hierarchy-specific class entities.

• Some declarations in the document hierarchy module reference pool-specific content model fragment entities.

Any entity declaration that contains a reference to another entity has a dependency on the referenced entity; it requires that the referenced entity be defined at a point before its reference, since forward references to entities aren't allowed in SGML.

Such dependencies can make it difficult to redeclare certain entities in a maintainable way. For example, if you want to redeclare a mixture entity defined in either one of the modules (for example, component.mix or divcomponent.mix), you are likely to want to reference at least some of the class entities that were in the original declaration (such as list.class), because doing so makes it easier to maintain your variant DTD with maximum fidelity. To accomplish such a "dependent redeclaration," you must position it between the declarations of the class entities and that of the targeted mixture entity.

Corresponding to the three types of entity dependency, the three locations where most dependent redeclarations must be accomplished are:

• Between the class and mixture entities in the information pool

• Between the class and mixture entities in the document hierarchy

• Between the references to the information pool and document hierarchy modules in the driver file

These locations in the DocBook modules and driver file contain special placeholders that you can activate and use if you need to make dependent redeclarations. The placeholders consist of external entity declarations and references that are stored in inactive ("IGNOREd") marked sections.

For example, to create a set of dependent redeclarations for an information pool mixture, first activate the marked section by declaring the dbpool.redecl.module entity as INCLUDE. Then create a file (for which the suggested name is rdbpool.mod) that contains the entity redeclarations. For the document hierarchy module, the marked section entity is called dbhier.redecl.module and the suggested file name is rdbhier.mod. For the driver file, the marked section entity is called intermod.redecl.module and the suggested file name is rdbmods.mod.

Note that you will probably be able to make most dependent redeclarations for the document hierarchy by placing them in the rdbpool.mod file, because many of the document hierarchy's mixture entities reference only pool-specific class entities, and thus can be redeclared at this location.

See Example 1-4 and Example 1-5 for examples of how information pool and document hierarchy redeclarations are done from within rdbpool.mod.