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 attribute![[A+]](/graphics/annot-open.png)
:
annotations, or <annotation>s
can point to the element(s) to which they apply with an annotates attribute. Here's the
annotations attribute in action:
![[A-]](/graphics/annot-close.png)
<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 <div>s 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...
I suppose (some)
altelements could be implemented with Ruby for HTML. Do modern browsers support Ruby?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...
--ScottWhy 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.