Annotations Revisited

Volume 7, Issue 204; 02 Dec 2004; last modified 08 Oct 2010

A few annotation changes reflecting mainly decisions of the DocBook Technical Committee at the October telcon.

No one means all he says, and yet very few say all they mean, for words are slippery and thought is viscous.

—Henry Adams

The last time the DocBook TC discussed annotations, there seemed to be consensus on two points. First, that one of the principle motivations for simple, inline annotations is accessibility. Second, that authors will find it easier to use annotations if the distinction between simple, inline annotationsInline annotations contain only text and other phrase-level markup. They are typically displayed as “tooltips” in a browser. and “block” annotationsBlock annotations, like this one, are more akin to footnotes. The browser presentation is a typically a pop-up window. is made on the basis of the element name.

To that end, I've updated the customization layer used here so that the “alt” element is allowed in all inline context. The alt element identifies a simple, inline annotation. The name “alt” has the advantage of being both short and suggestive of the accessibility aspect of this kind of annotation.

The annotation element no longer has a class attribute, it is now used only for block annotations.

Comments? Suggestions?

Comments


<para> I like it<alt>In that it seems v.sensible</alt>
</para>
<annotation>
<para> I guess the next question is does its place in
the schema suite all users?</para>
</annotation>

This is nice. I have two comments. The first example behaves like the second, not like a tooltip. Wouldn't it be better if the first one recited the annotation text instead of [Annotation #1] when I pass the cursor over it? Also, the block annotation says it is like footnotes, but the behavior differs. Usually footnotes are rendered as jump links rather than popups. You might mention that either behavior could be implemented by the stylesheet.