Annotation Markup in DocBook V5.0

As the design has evolved, I've written several essays on annotations. The design finally selected by the DocBook TC uses two elements: alt and annotation.

The alt element is for inline annotations, often rendered as “tooltip” text in the browser (title attributes on HTML elements). An alt element applies to its parent. The annotation for the abbreviation “HTML” is accomplished like this:

<abbrev>HTML<alt>Hypertext Markup Language</alt></abbrev>

The annotation element is for longer, “block” annotations. After much discussion about how an annotation relates to its parent, we decided it doesn't: that is, the context in which an annotation appears has nothing to do with its placement or the element(s) to which it applies.

Instead, elements can either point to relevant annotations with a new common attributeCommon attributes are those that appear on every DocBook element; see The Definitive Guide for a list of common attributes in DocBook V5.0.: annotations, or annotations can point to the element(s) to which they apply with an annotates attribute. Here's the annotations attribute in action:

<para>Instead, elements can either point to relevant annotations with
a new <phrase annotations="common.attr">common attribute</phrase>:
<tag class="attribute">annotations</tag>, or <tag>annotation</tag>s
can point to the element(s) to which they apply with an <tag
class="attribute">annotates</tag> attribute. Here's the
<tag class="attribute">annotations</tag> attribute in action:</para>

<annotation xml:id="common.attr">
<title>Common Attributes</title>
<para>Common attributes are those that appear on every DocBook
element; see
<link xlink:href="http://docbook.org/tdg5/en/html/ref-elements.html#common.attributes">The Definitive Guide</link> for a list of common attributes
in DocBook V5.0.</para>
</annotation>

This makes the processing expectations of annotation a little hairy and I think it's fair to say that they're still a little bit experimental. But that looks like the final design and it's not too hard to support in XSLT 2.0.

I've updated the markup in all the essays on this site that use annotations and preserved the “popup” nature of their display. For the stock (XSLT 2.0) stylesheets, I've selected something slightly simpler for the time being. Rather than incorporate all the popup machinery, I simply put the annotations into the text as divs where they are referenced and use a small amount of Javascript to toggle the display property of the division.