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.

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.

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.

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. :-)

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

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 ...

Test of abbrs.

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.

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

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.

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?

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.

FYI: Annotea (http://www.w3.org/2001/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: http://www.w3.org/2001/Annotea/User/Papers.html