|From:||Bob Stayton (bo...@sagehill.net)|
|Date:||Apr 14, 2005 2:11:04 pm|
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.
--------------------------- 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.
--------------------------------- 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 bo...@sagehill.net