Volume 7, Issue 162; 10 Sep 2004; last modified 08 Oct 2010

The DocBook TC has been talking about annotations for a while now. Herewith a few random thoughts and a little bit of experimental implementation.

When found, make a note of.

Charles Dickens

The DocBook TC has been talking about annotations for a while now. The genesis of this discussion is two separate but similar requests:

  • Support for acronym expansion (such as ASCII and EBCDIC) and

  • Support for titles on links (such as Sun)

First, although HTML uses attributes for the simple inline annotations demonstrated above, we want to use elements. Putting human readable content in attributes is wrong (it doesn’t support the full range of text that you might want to use and it doesn’t internationalize well).

Present a bunch of engineers with a problem and what’s one of the first things we do? We generalize. There are a lot of issues around annotations, technical and otherwise, that have to do with just how far we want to take this generalization. Once you’ve got the stuff in elements, it’s a short step from inline annotations to more interesting flavors.

Modern browsers display acronym expansions and link titles as “tool tipsA tool tip is a word or short phrase displayed automatically by an application when the user hovers the mouse over some component in the user interface.”. That little graphic after the phrase “tool tips” is a “block” annotation. In a modern, graphical browser clicking on that link will present a “popup window”. That works in Firefox and Internet Explorer and sortof in Opera and sortof in Safari. In Opera, you have to click twice on the graphic sometimes, but maybe that’s because I have an antique version of Opera. In Safari, the popups don’t seem to go away when you click somewhere else in the window; you have to reload the page to get rid of them. That’s unfortunate.

I’m using Matt Kruse’s PopupWindow code. For the moment, I’m going to assume that technical glitches with specific browsers are just that, technical glitches, and I’m not going to worry about it too much.

With a little CSS cleverness, text-only browsers like links and lynx work OK too. I hope that means screen readers work too. What happens is, the block annotations appear at the bottom of the page and the graphic’s alternate text becomes a hypertext link to those annotations. Maybe it’s a little cluttered, what with the “X” alternate text for the close button and all, but it seems like a fair compromise.

At the moment, I’m only supporting two classes of annotations:

  • Inline annotations are recognized in abbrev and link elements and produce an appropriate HTML tool tip. Only the first inline annotation is recognized, the rest are ignored.

  • Block annotations are recognized in most places and produce the little clickable graphic that makes the popup window.

One of the open questions with annotation support is what, if any, rendering should be used for print (or non-interactive) presentation. I’m using footnotes at the moment, with a distinct footnote mark, for block annotations. Inline annotations are ignored.

Comments? Suggestions?


I'm not sure about the coding details, but I do think the notion of annotations has fairly broad applicabilty that may suggest rethinking some basic structures in standards like DocBook. Consider footnote, which is a presentation-specific point element of what perhaps ought to be an annotation on a range of text. Likewise with citations arguably. And how about allowing foreignphrase to include the translation?

As for how to handle all this in output formatting in, say, print, I guess this is the real difficulty. Some content might need to get inlined in parenthesis (like a foreignphrase translation), some might need to get "footnoted", while still others might become marginal notes.

—Posted by Bruce D'Arcus on 10 Sep 2004 @ 03:58 UTC #

Good points, Bruce. You're not the first to suggest that a footnote is a kind of annotation but I'd be very reluctant to remove or deprecate the footnote element in favor of something like <annotation class="footnote">.

There's just too much historical precedent for <footnote>. It has well defined and well understood semantics and I think replacing it with a general element would cause more confusion without actually helping anyone very much.

That said, it might make sense to process footnotes and annotations in some uniform way.

—Posted by Norman Walsh on 10 Sep 2004 @ 04:12 UTC #

Norm -- yeah, I wouldn't say you ought to deprecate in favor of annotation necessarily. However, one practical problem with footnote is what if you decide you want them represented as endnotes (for which there is no structure in DocBook; nor should there be)? I commonly have to switch between them in my documents; outputting one way for one journal, and another way for another journal. I guess I'd prefer just <note>, with an optional role attribute where one could specify "footnote" if absolutely necessary.

Note: your comment stuff truncates my last name because of the apostrophe.

—Posted by Bruce D'Arcus on 10 Sep 2004 @ 05:15 UTC #

I plan to add an stylesheet option for "footnotes as endnotes" real soon now.

I'll investigate what happens to your last name. Sorry about that. :-)

—Posted by Norman Walsh on 10 Sep 2004 @ 06:36 UTC #

The apostrophe bug is fixed. And I patched the existing comments to fix them. Sorry, again, about that.

—Posted by Norman Walsh on 10 Sep 2004 @ 07:00 UTC #

I just write <acronym>TLA</acronym> in my source documents and have my XSLT look up the expansion in a separate file when converting to html (or other target format). I find this usefull since I often use the same acronyms all over.

Of course, most other annotations would be impractical to handle like this ...

—Posted by Rasmus Kaj on 10 Sep 2004 @ 08:43 UTC #

Test of abbrs.

—Posted by John Cowan on 11 Sep 2004 @ 01:06 UTC #

Hmm, the abbr element doesn't seem to do anything presentational. Maybe we too could insert simple annotations into our comments? (We'd need an attribute, of course.)

Anti-endnote rant:

Endnotes may be tolerable in papers, but in books they deeply, deeply suck. Not only do you have to flip to the back of the book and try to find the right endnote, you have to find the right chapter within the endnotes. And it invariably turns out that the endnote header says simply "Chapter XVIII", whereas the running head in your chapter says simply "Aquentravalkeration Among The Nitenmangrey", or what have you.

So you have to keep your place in the book, page back to the beginning of the chapter to learn its number, page to the back of the book, by which time you have forgotten the footnote number and have to reread the original page, etc. etc. etc. etc.

Hmm. In an HTML comment, blank lines are ignored. I think your stylesheet should infer a paragraph break anyway.

—Posted by John Cowan on 11 Sep 2004 @ 01:12 UTC #

Also, there isn't enough interparagraph leading in comments, which makes the grafs tend to run together. (I feel like complaining tonight.)

—Posted by John Cowan on 11 Sep 2004 @ 01:14 UTC #

Yes, endnotes suck. But publishers use them all the time, and if I want to publish, I need to respect that.

My point still stands that footnote is presentational markup. To talk about the foot of a webpage doesn't make much sense, and I tend to think the content for online use ought to be presented in a pop-up, or a sidebar perhaps.

—Posted by Bruce D'Arcus on 11 Sep 2004 @ 01:27 UTC #

WAI, Protocols and Formats group, have been discussing this for some time Norm. One audience is people with learning difficulties. Simple wordnet word meanings would be a start. RDF was suggested, I kind of like the simplicity of what you are discussing. If its available via a little styling that makes it a today solution instead of tomorrow, which I like. Hadn't seen much discussion on docbook list. Has there been any?

—Posted by Dave Pawson on 11 Sep 2004 @ 05:12 UTC #

Hi Norm, what syntax for annotations do you propose? I think that this is the hardest part of problem. Syntax that will be general enough but not too complex. I was thinking about it and I was unsuccessful.

—Posted by Jirka Kosek on 12 Sep 2004 @ 08:43 UTC #

FYI: Annotea ( provides an RDF schema for annotations that may be useful here. Annotea also defines a protocol for storing annotations in annotation servers some of which can be subscribed by the user. We also have a schema for shared bookmarks and topics that we are working on now and we have experimented using bookmark files for storing them. Some documentation:

—Posted by marja on 16 Sep 2004 @ 07:05 UTC #