Question

I am trying to make a subtle customization of DocBook that I suspect would most easily be solved by subclassing the <informaltable> element. There are several statements that imply subclassing DocBook elements using the role attribute is possible.

Documentation that Implies Subclassing Using Roles is Possible

Example 1 – From DocBook 5.1: The Definitive Guide – Customizing DocBook

The role attribute, found on almost all of the elements in DocBook, is a text attribute that can be used to subclass an element.

Example 2 – From DocBook 5.1: The Definitive Guide – DocBook Element Reference

While role is a common attribute in the sense that it occurs on all DocBook elements, customizers will find that it is not part of any of the “common attribute” patterns. It is parameterized differently because it is useful to be able to subclass role independently on different elements.

Example 3 – CERN – Writing Documentation Using DocBook

Most DocBook tags contain a common set of attributes. The most often-used such common attributes are lang, which specifies the language of the data inside the element, id labels an element so that it can be referenced by other elements, and role, which allows one to subclass an element, to make it information-wise more specific.

General Google Findings.

Googling combinations of "extend docbook elements role attribute" turns up pages about templates that handle new elements, but doesn’t seem to turn up any pages other than the customization examples below that even contemplate subclassing elements using role attribute.

Customization Examples That Do Exist

There exists examples customizing the formatting of existing DocBook elements, but these are XSLT customizations and do not speak to extending the DocBook schema.

There also exists an example that adds a <sect6> element, but it seems too verbose to be an efficient means of subclassing, and I suspect that technically that example isn’t subclassing at all. Also, that example doesn’t seem to make any special use of the role attribute.

Can Subclassing Using the role Attribute Really be Accomplished?

It seems from the above examples that the DocBook schema was specifically designed to facilitate subclassing of elements using the role attribute, however, no concrete example seems to be published.

I am new to both XML and DocBook. Is subclassing a DocBook element so trivial that it goes unnoted? If so, could someone show how it is acheived?

Is subclassing a DocBook element using role a nice idea that just doesn’t work? If so, why doesn’t it work?

Note 1:
Whether subclassing <informaltable> is the right approach to solving my original problem is another question entirely.

Note 2:
I had more hyperlinks in my question, but apparently my reputation doesn’t allow me to post more than 2 🙁

Answer 1

It seems from the above examples that the DocBook schema was specifically designed to facilitate subclassing of elements using the role attribute, however, no concrete example seems to be published.

Example 5.14 of TDG is a very concrete example that shows how to constrain the role attribute on the <procedure> element so that only two values are allowed (by default, any value is allowed). This customization requires modification of the schema. You can do something similar with <informaltable> if you want to.

And there is nothing stopping you from just using something like

<informaltable role="myspecialtable">
 ...
</informaltable>

This is “subclassing” of the simplest kind; no schema changes are needed. How role="myspecialtable" is supposed to be interpreted or processed is entirely up to you.

There also exists an example that adds a <sect6> element, but it seems too verbose to be an efficient means of subclassing, and I suspect that technically that example isn’t subclassing at all. Also, that example doesn’t seem to make any special use of the role attribute.

What is your idea of subclassing then?

Perhaps the term “subclassing” can be bit misleading. DocBook is a markup system, not a programming language. The analogy between subclassing (customizing) a DocBook element and creating a subclass in Java or C++ should not be taken too far.

There is nothing magical about role. It is just an attribute with no predefined semantics. You don’t have to do anything special with it in order to create a DocBook customization.

Is subclassing a DocBook element so trivial that it goes unnoted?

Why do you say that? The whole “Customizing DocBook” chapter is about customization of DocBook elements. It’s not something that goes unnoticed.

Is subclassing a DocBook element using role a nice idea that just doesn’t work?

It does work, but perhaps not in the way you expect it to.

As described above, simply by deciding on a particular value for the role attribute on an element and using it in your document, you are in effect creating a subclass (customization, variant) of that element. That’s it.

How to use the custom element — how to transform it, filter it, visualize it, and so on — is a different story.