Annotation Markup

A few days ago, I demonstrated some experimental annotation formatting. What I didn’t really do was talk about the source markup for annotations. From our discussions at the DocBook TC meeting yesterday, it’s pretty clear there are a few ways to slice the problem.

Annotations divide, functionally, into two classes: “inline” and “block”. Inline annotations are one possible solution for a set of accessibility issues: providing alternate text for graphical elements and other places where short, basically text-only, “tool tip style” rendering is appropriate. Expansions for abbreviations and acronyms and perhaps translations for foreignphrasesThe foreignphrase element can be used to markup the text of a foreign word or phrase. “Foreign” in this context means that it is a language other than the primary language of the document and is not intended to be pejorative in any way. fall into this category.

Block annotations are more like footnotes. They can contain a range of block elements (paragraphs, lists, even tables) and have to be rendered in some other way, they aren’t “tool tips”.

For my experiments, I chose a single annotation element and used an attribute to distinguish between the two classes:

…DocBook <acronym>TC<annotation class="inline">Technical
Committee</annotation></acronym>…

The class values “inline” and “block” aren’t really suitable for production use, they were just convenient for my experiments. In real life, I think we’ll want to use things like “title” or even “expansion”. I don’t know exactly what the list should be though.

One question is whether the functional distinction in annotations should be exposed to the author by using two elements, analogous to inlinemediaobject and mediaobject. The problem is, that’s not a very good analogy. It’s true that the two forms of media object have different processing expectations, but inlinemediaobject exists as a distinct element in order to prevent “block” media objects from appearing in inline contexts (like titles and phrases)The inlinemediaobject element is allowed basically everywhere text is because it’s the hook that authors can use to deal with glyphs that aren’t in the fonts they use, or even in Unicode.. Either style of annotation, on the other hand, can occur in almost all contexts. Certainly block annotations can, in general, occur in inline contexts.

A better analogy, in some sense, is between para and simpara, where para can contain block-level markup (like programlisting and table) where simpara cannot. But my experience is that authors don’t use simpara very much unless customizers force them to do so.

So, one of the tensions we face is over the annotation element’s name(s). Is there significant value in terms of explaining to authors and getting them to use it correctly if there are two elements for this purpose? Or does the fact that these two elements would almost always appear together in every content model mean that it makes more sense to have a single element and distinguish between the inline and block cases simply by the element’s content?

It turns out that there’s a precedent for that too. When we needed to provide alternate text for media objects, we observed that we already had a textobject element in the content model for media objects, so we extended it to allow either phrase or block level markup and decreed that the processing expectation for a text object containing only a phrase was that it was the “inline” alternate text for the image. (A text object containing block level markup might be used as the long description of an image.)

In retrospect, I’m not sure this was a really good idea. The markup is a bit awkward and the distinction is pretty subtle to explain. Part of the awkwardness of the content model:

<!ELEMENT textobject (phrase|(para|orderedlist|...))>

is related to shortcomings in XML DTD constraints. When I built my experimental annotation markup, I left out the clumsy “phrase or blocks” dichotomy choosing instead a simple:

element db:annotation {
   ((text|inlines) | blocks)+
}

model. This won’t translate well to a DTD, but I haven’t decided if I care or not. Certainly forcing an extra phrase in there just to avoid pernicious mixed contentA content model that allows a mixture of #PCDATA and block elements exhibits a nasty peculiarity that we call “pernicious mixed content”. In SGML, it manifested as markup errors. In XML the rules for content models were changed and the errors can’t occur any more, but a content model that exhibits this problem can’t prevent unadorned text content from occurring in places where it shouldn’t be allowed, such as between paragraphs. seems like a burden.

Then there’s the unanswered question of where annotations should be allowed. I’m inclined to think the correct answer is “everywhere text is allowed”. Dick Hamilton pointed out one place were we might not allow block annotations: inside link elements. The point being that a hypertext link inside a hypertext link is going to be difficult to render and potentially confusing to authors and readers. Maybe more experience will suggest other limits.

I suppose the next thing to do is think more explicitly about the processing expectations for annotations. In my experiments, I’ve only allowed them in a few places. Allowing them everywhere, and processing them in a reasonable way wherever they occur, may be a significant processing challenge.

<annotation>
  <abbrev>XML</abbrev>
  <description>eXtensible Markup Language</description>
</annotation>