Annotation Markup in DocBook V5.0

Volume 8, Issue 134; 17 Oct 2005; last modified 08 Oct 2010

Closing the loop on DocBook annotation markup.

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.

Comments

Why not use Ruby for inline annotations? It is part of the XHTML 1.x namespace...

—Posted by Anne van Kesteren on 17 Oct 2005 @ 05:09 UTC #

I suppose (some) alt elements could be implemented with Ruby for HTML. Do modern browsers support Ruby?

—Posted by Norman Walsh on 17 Oct 2005 @ 10:35 UTC #

According to http://en.wikipedia.org/wiki/Ruby_characters: "Ruby markup is partially supported by Microsoft Internet Explorer (5.0+) for Windows and Macintosh, but is not supported by Mozilla, Firefox, Safari/Konqueror or Opera."

Although Ruby is supposed to be part of XHTML 1.1, I don't know if it's support is mainstream enough for this yet.

It also looks like Ruby would work for inlines, but I don't know about block level...

--Scott
—Posted by Scott Hudson on 18 Oct 2005 @ 02:38 UTC #

Why is alt done as an element as opposed to an attribute?

Where is an Annotation element expected to be placed in the tree? I realize it is not a child of the parent, but surely one is not expected to go through the whole tree for annotations, it would make sense if they were confined to one part of the tree.

—Posted by Bryan Rasmussen on 19 Oct 2005 @ 07:13 UTC #