[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: annotation proposal
Hi all,
I'm am following up on my action item to submit a
updated proposal for annotations. Here I provide some
background, a summary, and the proposal.
I've made some innovations here, so I'm hoping we can have
some email discussion before our meeting next Wednesday.
Background
---------------------------
Here is a listing of the key discussions of annotations
over the last 3(!) years.
June 2002: Started discussion of annotations in TC:
http://lists.oasis-open.org/archives/docbook/200206/msg00152.html
June 2002: Paul described many issues regarding annotations:
http://lists.oasis-open.org/archives/docbook/200206/msg00153.html
June 2002: Mike mentions using a second element for simple annotations:
http://lists.oasis-open.org/archives/docbook/200206/msg00182.html
August 2002: Norm starts playing with annotations in response to
Paul's list of issues:
http://lists.oasis-open.org/archives/docbook/200208/msg00156.html
[and follow-up messages]
March 2003: Mike submits TC proposal for single annotation element:
http://lists.oasis-open.org/archives/docbook-tc/200303/msg00001.html
August 2003: Short TC discussion where out-of-line annotations suggested:
http://lists.oasis-open.org/archives/docbook/200308/msg00037.html
June 2004: Mike again proposes single annotation element that is a child
of the annotated element:
http://lists.oasis-open.org/archives/docbook-tc/200406/msg00003.html
June 2004: Norm responds to Mike's proposal with many questions
and issues:
http://lists.oasis-open.org/archives/docbook-tc/200406/msg00005.html
September 2004: Norm posts his "Annotations" essay on his website;
includes inline and block examples, and several follow-up comments:
http://norman.walsh.name/2004/09/10/annotations
September 2004: TC discusses Mike's proposal, differentiates between
simple and complex annotations:
http://lists.oasis-open.org/archives/docbook-tc/200409/msg00016.html
September 2004: Norm posts his "Annotation Markup" essay, showing
inline and block annotation markup:
http://norman.walsh.name/2004/09/16/annotationMarkup
October 2004: TC merges discussion with Accessibility, proposes
two elements <alt> and <annotation>:
http://lists.oasis-open.org/archives/docbook-tc/200410/msg00018.html
December 2004: Norm posts his "Annotations Revisited" essay,
showing <alt> and <annotation> elements:
http://norman.walsh.name/2004/12/02/annotations
December 2004: TC approves two elements <alt> and <annotation>,
and Norm to submit proposal:
http://lists.oasis-open.org/archives/docbook-tc/200412/msg00008.html
February 2005: Norm makes annotation proposal to docbook list; much
discussion follows:
http://lists.oasis-open.org/archives/docbook/200502/msg00059.html
February 2005: TC discusses Norm's proposal, and how to associate
an annotation with its annotated element:
http://lists.oasis-open.org/archives/docbook-tc/200502/msg00008.html
March 2005: TC discusses how to associate an annotation with
its annotated target. Bob to write up a proposal:
http://lists.oasis-open.org/archives/docbook-tc/200503/msg00009.html
Summary so far
---------------------------
The TC agreed that two elements would be created:
<alt> for text-only annotation, typically used for accessibility.
<annotation> for complex annotations containing block elements.
The question this proposal addresses is how to associate
these annotation elements with the annotated content.
Based on my reading of the discussions, here are some
points that guided the development of this proposal:
1. While we have identified several use cases,
we expect users to invent ways to use annotations beyond
the use cases that we have discussed.
2. We can define syntax for annotations, but we
cannot define all possible semantics for them.
3. We expect users to use the 'role' attribute to create
different types of annotations with different semantics,
to be handled by stylesheets in different ways.
4. We expect the authors of the DocBook stylesheets to
implement certain specific and common types of annotations
for certain elements. This will provide examples for how
annotations can be used, and will make them immediately
useful in the DocBook community. But these will not be
"official" annotation semantics.
5. An annotation is associated with an element, not a
point in text. By contrast, a <footnote> is associated
with a point in text.
[Terminology: What can we call the element that is referred
to by an annotation? It is annotated, so call it an
annotatee? (made up word). I use "annotated element" here.]
6. An annotation and its annotated element can be a
two-way connection. Sometimes you want to go from the
annotation to the element, and sometimes from the element
to the annotation. Think of a <callout> and a <co> element.
Sometimes you want to go from the <co> number in a figure
to the <callout> paragraph. And sometimes you want to go
from the <callout> paragraph to the <co> location in the
figure. The <callout> and <co> elements support both connections.
7. One element can have many annotations. An element could
have several annotations of the same type, or of different types
for different purposes.
8. An <annotation> element could be associated with
many annotated elements. It is not likely that a simple
<alt> element needs this feature.
9. Several people wanted the ability to put an annotation
away from the annotated element.
Proposal
---------------------------------
This proposal suggests that the two annotation elements
have two different mechanisms for association with
the annotated element.
For alt annotations, make the <alt> element a child of
its annotated element.
Examples of <alt>:
<!-- Alt text for a mediaobject -->
<mediaobject>
<imageobject>
<imagedata/>
</imageobject>
<alt>Text description</alt>
</mediaobject>
<!-- Alts for multiple imageobjects -->
<mediaobject>
<imageobject role="html">
<imagedata/>
<alt>Text for html graphic</alt>
</imageobject>
<imageobject role="fo">
<imagedata/>
<alt>Text for a talking PDF file!</alt>
</imageobject>
</mediaobject>
<!-- An equation -->
<equation>
<alt>Description of equation</alt>
<mediaobject>
<imageobject>
<imagedata/>
</imageobject>
</mediaobject>
</equation>
<!-- A graphical title -->
<title>
<inlinemediaobject>
<imageobject>
<imagedata/>
</imageobject>
</inlinemediaobject>
<alt>The title as text</alt>
</title>
The advantages for handling <alt> this way are:
- This is an intuitive placement for this simple element.
- The association by proximity keeps the alt text visible
in the source.
- It is as close to being an attribute as you can get without
actually being an attribute.
- It matches the current usage of the alt element in <equation>.
The disadvantages for <alt> are:
- You can't do remote <alt> attributes.
- You can't reuse an <alt> attribute for multiple elements.
- Empty elements such as imagedata would have to become nonempty
if we want to add alt to them.
For the <annotation> element, a more flexible method for
forming the association is needed. I propose
that the association always be made by
using an attribute to point to an id attribute.
Using attributes, the association can be made in either
direction or both directions. This example forms
the association in both directions:
<annotation id="myannot" refersto="mychap">
...
</annotation>
<chapter id="mychap" annotations="myannot">
...
</chapter>
The 'refersto' (refers to) attribute in the <annotation>
indicates which elements this annotation refers to.
The 'annotations' attribute in the annotated element
indicates which annotations are attached to it.
The 'annotations' attribute is to be added to the list of
common attributes.
I'm also proposing that the 'refersto' and 'annotations'
attributes be declared as CDATA rather than IDREFS
attribute type. You lose the ability to validate them with
the parser, but you make them more flexible. In a system
that uses XInclude to assemble documents from validatible
file modules, using IDREFS would prevent annotation links
from crossing module boundaries. Annotation integrity of
the assembled document can be checked by the stylesheet at
processing time, in the same way that olinks are resolved.
The advantages for handling <annotation> this way are:
- The difficult question of where to put the <annotation> element
relative to the annotated element is resolved. The annotation
element can be anywhere. It can be a child, a sibling, a
descendant, or a distant cousin.
- There are no implied associations based on position
or proximity.
- It doesn't require checking the presence or absence of
an id attribute to determine whether the association is
by id or proximity.
- It is unambiguous and easy to compute.
- It supports both local and remote locations for annotations.
- Enabling annotations on all elements is as easy as adding
one attribute to the list of common attributes.
- It supports forming the association in either
direction, or both directions. The author decides
which direction(s) to use for each instance.
- The annotation element's 'refersto' (refers to) attribute
accepts multiple space separated values, so one <annotation>
can be associated with more than one annotated element.
- An element's 'annotations' attribute takes multiple
space separated values, so one element can be associated
with more than one <annotation>.
- You can even annotate your <annotation> elements.
The disadvantages of this proposal for <annotation> are:
- It requires adding id attributes to form the association.
- It requires two attributes to form a two-way connection.
- Using multiple values requires editing an attribute
value rather than inserting another element or attribute.
So each annotation element would have its own
method of forming its attachment, and each method
would be simple, clear, easy to learn, and easy
to remember.
By using two different attachment mechanisms for the
two annotation elements, the distinction between them
is made even stronger. I think that is a good thing.
I don't think <alt> needs any mechanism for
doing remote annotations or reuse of annotations.
But <annotation> does.
Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]