ZedAI AnnotationNoteObjectIssues

From zedwiki

Jump to: navigation, search

Contents

Background

There is currently overlap and ambiguity regarding the use of the note and annotation elements, which in turns spills over into the annotating of elements (in particular, the object element).

The May 21 2010 release of the specification provides a rudimentary set of tools for noting and annotating documents, but this proposal seeks to redress certain shortcomings and to simplify and standardize their use.

Issues

annotation and note

The scope of the annotation element is currently intentionally wide in range, covering annotations as they appear in the source, republisher-provided annotations, as well as alternate representations (e.g. text equivalents of images). This overlap leads to the overload of the annotation element and the pedagogical challenge of conveying the additional and now required semantics necessary to fully annotate the annotation (which we've otherwise tried to keep as an optional layer).

In addition, depending on the type of annotation, the pointing relationship can vary: print-provided annotations do not always identify the specific segment of text that is being annotated (e.g., they may generally apply to multiple lines/sentences or whole paragraphs), while republisher-provided annotations typically do.

The distinction between when to use the note element or annotation element is also somewhat unclear because of the large scope of annotation and because of print legacy. When to use one or the other is currently tied to the inclusion of marked identifiers in the text, instead of semantics. This approach leaves the door open to misuse of annotation in the absence of markers and note in the presence of them.

object

The nesting of object elements (as per XHTML object) allows processing agents to select preferred content types for images. As the image types that processing agents must support is clear upfront (even in the presence of the SVG-CDR feature), there is really no direct use for this feature in the core namespace anymore -- the nesting was adopted while we had a non-restriction on allowed mimetypes on object.

This conflates with the intent of the content selection feature, and results in a deviation from our design guideline to provide one, not many, ways to do something.

Annotating elements

The ability to describe the contributor of an annotation or note (author, editor, translator, republisher, etc) is currently placed in the role element alongside the annotation nature, creating complexities with regards to using multiple curies in the same value, and mapping to implicit values.

Proposed Solution 1

Overview

To resolve the issues with annotation and note:

  1. Reduce the scope of annotation to not include republisher-provided alternates and structural descriptions. Instead introduce a new alt namespace which will include elements to cover these use cases.
  2. Keep the current semantics of note for representing only footnotes and endnotes.
  3. Add a annoref element to cover cases where annotations include a referent.
  4. Drop the requirement to always have a correlating noteref or annoref. In the absence of a referent in the text, the note or annotation must instead point to the element it annotates through a ref attribute (e.g., either a noteref must point to a note or the note must point to some element in the document).

To fix the issues annotating object:

  1. Create a new namespace for elements that exclusively contain content added by a republisher (example prefix: alt)
  2. Add one new element alt:description (see below)
  3. Remove the ability to nest object, but still allow text inside object
  4. Let text nested inside object be an implicit alt:description

Details

annotation element

The annoref element will be introduced as a specialization of the existing noteref element for inserting a text referent in the document, but makes no changes to noteref's traits.

The annotation element must either refer to an element in the document or must have a annoref element pointing to it.

The type attribute will be used to indicate the nature of the annotation and the by attribute will be used to identify the person or agency who added the annotation.

annotation will no longer be used for republisher-provided structural descriptions or alternate representations.

note element

The note element will be restricted to representing only footnotes and endnote. The type attribute will allow a value of either footnote or endnote, with footnote as the implicit value.

The note element must either refer to an element in the document or must have a noteref element pointing to it.

object element

object will not allow the nesting of object elements but allow direct inclusion of text elements corresponding to the content model of alt:description at the current level as an alternate representation. Note: text inside object is considered an implicit alt:description and the alt:description IDREF attribute is also implicit.

Alternatively to nesting text, object can also reference an alt:description placed elsewhere, including the document head, allowing multiple objects to reference the same alternate representation and/or description.

Nested text and/or alt:description is not required on object. (A validator could have a mode to generate warnings when alt text is missing).

alt namespace and elements

Introduce a new namespace (e.g., http://www.daisy.org/ns/authoring/alt), initially with one element description and one attribute (alt:description) (for now). Elements in this namespace are related in that they exclusively contain content that is typically added by a republisher in order to assure accessibility of the output.


The alt:description element can be used to provide a variety of republisher descriptions that may accompany figures, tables, complex lists and so on, such as:

  • to explain in general terms the structure and/or layout of the construct;
  • to provide a text-only alternate representation of a non-textual contruct;
  • to correct a problem from the original source;
  • to clarify some aspect of the construct;
  • etc.

alt:description will be allowed both in the head and body. The element will include a type attribute for specifying the nature of the descriptive text. The implicit value of the attribute is 'content-description'.

The alt:description IDREFS attribute is part of the core attributes and provides a link from the element being described to the alt:description elements associated with it.

If multiple alt:descriptions are provided for the same element, then they must have unique types/roles.


Proposed Solution 2

This solution, discussed during the August 24, 2010 telecon, does away with the republisher namespace and uses elements in the core together with the by attribute to identify republisher additions.

Annotations/Descriptions

The description element in Solution 1 will be included in the core namespace, but its semantics will continue to limit it to be used to add accessible descriptions for images, videos, etc. By bringing it out of a specialized namespace, the idea is to encourage source producers to include accessible descriptions in their documents (move away from it being a republisher's requirement).

The by attribute will become a global attribute allowed on any element. This attribute will allow all additions by republishers (or others) to be easily identified and filtered during processing. The implied by value would be the producer.

Notes

This new solution proposes no new changes from Solution 1. The note element will continue to be used exclusively for footnotes and endnotes

Object

The contents inside an object will be treated as having an implied description element. TBD what the implied by value will be.

No other changes to object were proposed.

Examples

annotation and note

Footnote with noteref pointer 

  <p>...<noteref ref="n1">1</noteref>...</p>
   ... 
   <note type="footnote" xml:id="n1">...</note>

Endnote with no noteref pointer 

<block type="endnotes">
  <note ref="page_25" rend:prefix="25">...</note>
  <note ref="page_26" rend:prefix="26">...</note>
</block>


Republisher annotation

Solution 1 

   <p>...<annoref ref="a1">1</annoref>
   <alt:annotation xml:id="a1" type="production">...</alt:annotation>


Solution 2 

   <p>...<annoref ref="a1">1</annoref>
   <annotation xml:id="a1" by="republisher" type="production">...</annotation>

Annotation without annoref pointer 

  <p xml:id="p1">...</p>
   ... 
   <annotation ref="p1">...</annotation>


object examples

Object with nested implicit alt:description 

  <object src="..." srctype="image/png">
    <p>...</p>
  </object>

Object with external alt:description

Note that <alt:description> is text-only, core ZedAI namespace, no features, no object, in this proposal the only way to provide an image-based alternate representation is by the content selection feature.

Solution 1 

<head>
  <alt:description xml:id="alt_img1">...</alt:description>
</head>
<body>
  <object src="..." srctype="image/png" alt:description="alt_img1" />
</body>

Solution 2 

<head>
  <description xml:id="alt_img1">...</description>
</head>
<body>
  <object src="..." srctype="image/png" ref="alt_img1" />
</body>

Content selection feature and image types

Instead of object nesting, use the content selection feature, which would get a new function "preferred-mime-type" which takes a mime type as parameter: 

<body>
 ....
   <sel:select>
       <sel:when expr="type('image/svg')"
           <object src="image.svg" alt:description="img1"/>
       </sel:when>
       <sel:otherwise>
            <object src="image.png" alt:description="img1"/>
       </sel:otherwise>
   </sel:select>
...
</body>

This also makes it more streamlined when considering future use cases of multiple SVG's with different content and/or targets. The selection principle is now all collected in the content selection feature instead of being spread out between native object behavior and select: 

<sel:when expr="type('image/svg') and target('TACTILE')">
   <object .../>
</sel:when>

alternatively using nested clauses: 

<sel:when expr="type('image/svg')">
  <sel:when expr="target('TACTILE')">
    <object .../>
  </sel:when>
  <sel:otherwise><object .../></sel:otherwise>
</sel:when>


description examples

table structure description

description can also be placed in head

Solution 1 

<table xml:id="t1">...</table>
<caption ref="t1">...</caption>
<alt:description ref="t1" type="structure-description">...</alt:description>

Solution 2 

<table xml:id="t1">...</table>
<caption ref="t1">...</caption>
<description by="republisher" ref="t1" type="structure-description">...</description>


by examples 

<p by="republisher" role="warning">He who shares or copies this book will be cursed ... </p>
Retrieved from "http://www.daisy.org/zw/ZedAI_AnnotationNoteObjectIssues"
Personal tools