Re: [docbook-tc] Annotation proposal

[Norman Walsh <ndw@nwalsh.com>]

/ Michael Smith <smith@xml-doc.org> was heard to say:
| I've had the following open action item for quite a while now -

Thanks for following up, Mike.

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

My concerns about the annotation element are three-fold, 

1. usability
2. semantics
3. processing expectations

Usability:

It's verbose. And (practically) it's got to have at least one other
element inside it if we want to allow annotations to contain both
blocks and phrases.

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

That's a lot of markup for what HTML does with

   <acronym title="For Your Information">FYI</acronym>

I am not advocating the latter design, in fact I man strongly opposed
to it, I just worry about the usability of the former.

In reality, annotations are associated with not contained by the things
they annotate. But then there's the question of maintaining the integrity
of associations and dealing with the associated content.

Semantics:

How do we define, and then describe in terms an author will understand,
the semantics of annotation. There are a bunch of questions that have
to be answered:

Are these the same or different? Will users understand the answer?

   <acronym>FYI<annotation>For Your Information</annotation></acronym>

   <acronym><annotation>For Your Information</annotation>FYI</acronym>

Are these?

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

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

What does this mean?

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

Does it mean the same thing as this?

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

How does xml:lang get resolved?

How do multiple classes get resolved?

What are the appropriate class values?

How do we deal with the fact that some class values may be appropriate
for annotations on one element but not on another?

Are people allowed to have audio annotations? Does annotation have to
allow audioobject? Videoobject?

Is the following reasonable?

  <set>
    <!-- 2.5 gigabytes of nested <book> elements inlined -->
    <annotation>Did you remember to process me?</annotation>
  </set>

Processing Expectations:

What on earth are processors expected to do with each of these? How do
we deal with the fact that the capabilities of interactive rendering
and static presentation are so dramatically different.

I can easily imagine enumerating a set of fixed processing
expectations for certain kinds of annotations on certain elements for
a certain kind of transformation. And I can imagine some general rules
for a class of "reasonable" annotations. But I don't know what to do
about the thousand different ways people will actually attempt to use
them.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | The fundamental delusion of
http://www.oasis-open.org/docbook/ | humanity is to suppose that I am
Chair, DocBook Technical Committee | here and you are out
                                   | there.--Yasutani Roshi

PGP signature