Annotation proposal

[Michael Smith <smith@xml-doc.org>]

I've had the following open action item for quite a while now -

  Mike to reconsider the annotation problem and post his thoughts.

Today I went back and looked at what I originally proposed[1] (RFE
574880[2] -- it's been around two years ago now) and have reconsidered it.

[1] http://lists.oasis-open.org/archives/docbook-tc/200204/msg00006.html

[2] http://sourceforge.net/tracker/index.php?func=detail&aid=574880&group_id=21935&atid=384107

My thoughts after reconsidering it are that there's nothing I would
change from what I originally proposed. If we were to add an Annotation
element to DocBook, I can't see it being significantly different from
what is described in that proposal.

Part of what I proposed was that the Annotation element should be a
child of the element it annotates; for example:

  <acronym>FYI<annotation
    class="expansion">For Your Information</annotation></acronym>

  <foreignphrase>caveat emptor<annotation
    >Latin phrase usually translated as "Let the buyer
    beware".</annotation></foreignphrase>

That would make it different from the Footnote element, which is simply
a marker at some point in a document that doesn't clearly indicate what
part of the document it's intended to annotate. (That is, it's not clear
whether it's annotating the word that precedes it or the phase/sentence/
paragraph or whatever.)

To my recollection, it was concerns about that part of the proposal that
stalled our original discussion about adding the element. But as far as
I remember, those concerns had to do with processing expectations, not
with the content model itself.

Anyway, if those concerns are going to prevent us from ever considering
adding the element, then I would like to reluctantly suggest that we
talk about having it instead be something like the Footnote element --
just a marker, without any means to unambiguously indicate exactly what
it's annotating. Like this:

  <acronym>FYI</acronym><annotation
    class="expansion">For Your Information</annotation>

  <foreignphrase>caveat emptor</foreignphrase><annotation
    >Latin phrase usually translated as "Let the buyer
    beware".</annotation>

That's it.

  --Mike