summary: Annotation element

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

One of my action items from last month was to submit a summary of the
state of discussion about the proposed Annotation element.

The summary is: After going back through responses to the proposal on
the mailing list, the only feedback was related to the processing
expectations for the element, not to its content model.

As far as the processing expectations go, it seems like the only way we
can address those is in the Processing Expectations section of the docs.
I can't see that they have any effect at all on the content modeling.

That said, I've added an update proposal to the RFE at Sourceforge:

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

And I've also pasted it in below.

To see an example of one way in which an Annotation might be rendered
online, please see:

  http://www.logopoeia.com/docbook/dontlearn.html#les2

-----------------------------------------------------------------

Annotation -- An annotation associated with a portion
              of the main narrative flow of a document

1. Description
--------------
  An Annotation is similar to a footnote in that it
  references or annotates a portion of the main
  narrative flow of a document, while it is intended to
  be rendered outside of the main narrative flow.

  An annotation might be used to provide short
  annotative text, such as the "expansion" or
  spelling-out of an acronymn, or long annotative text,
  such as an excerpt (possibly containing graphics,
  lists, simple tables, and so on) from a work cited in
  the main narrative flow.

  Unlike a Footnote, which is associated with the
  element that precedes it, an Annotation is intended
  to be associated with the element that *contains* it
  (for example, as a Title is associated with the
  Section that contains it).

  1.1 Processing Expectations
  ---------------------------
    The body of an Annotation may be rendered:

      * similar to a footnote (that is, at the bottom
        of the page on which the portion of the main
        narrative flow that it references occurs, or as
        end notes at the end of the component that
        contains the annotation)

      * (for "interactive" electronic versions such as
        PDF and HTML documents) as pop-up text, with
        character formatting and possibly containing
        graphics and so on (not just text) in some
        other form completely separate from the
        rendered version of the document

      * (if the source content is limited to CDATA) as
        the value for the HTML "title" attribute, which
        will automatically be rendered by some HTML
        browsers as pop-up "tool tip" text

    For electronic versions (for example, PDF and HTML
    versions) of a document, the Annotation element may
    or may not generate a mark at the place in the main
    narrative flow of a document in which it occurs.
    (If no mark is rendered in the main flow, the
    presence of the footnote may be indicated or
    handled by the rendering application automatically;
    for example, available through a "mouse-over".)

2. Synopsis:

   2.1 Content Model
   -----------------
     annotation ::=
       (%list.class;|%linespecific.class;|%synop.class;
        |%para.class;|%informal.class;%local.annotation.mix)

     Note: This is basically the same content model the
           Footnote element has.

   2.2 Attributes
   --------------------------------------------------------------
     Name                   Type                Default

     label                  CDATA               none

     class                  Enumeration:        none
                            expansion
                            definition
                            title

   3.3 Parameter Entities
   -----------------------------------------------------------------
    %admon.mix;           %bookcomponent.content;  %component.mix; 
    %cptr.char.mix;       %divcomponent.mix;       %docinfo.char.mix; 
    %genobj.class;        %glossdef.mix;           %indexdivcomponent.mix; 
    %ndxterm.char.mix;    %other.char.class;       %para.char.mix; 
    %qandaset.mix;        %refcomponent.mix;       %refinline.char.mix; 
    %revdescription.mix;  %sidebar.mix;            %tbl.entry.mdl; 
    %title.char.mix;      %word.char.mix; 

    Note: This is basically the same set of parameter
          entities in which the Remark element is
          included.

3. Attribute discussion
-----------------------
  label
    Identifies the desired annotation mark

  class
    Identifies the type of annotation

4. Examples
-----------
   <para>Well, polish up an apple for the teacher,
     <phrase>because I just happen to have such a
     table<annotation 
       ><para
         ><inlinemediaobject>
             <imageobject>
               <imagedata
                 fileref="http://www.logopoeia.com/docbook/dontlearn_files/learnxml_xs_l.gif"/>
             </imageobject>
             <textobject>
               <phrase>Learning XML book cover</phrase>
             </textobject>
           </inlinemediaobject>
       The initial basis for the
       taxonomy in <xref linkend="table.SpecsByGroup"/>
       was the <citetitle pubwork="chapter" >Taxonomy of
       Standards</citetitle> appendix in
       Erik T. Ray's <citetitle ><ulink
        url="http://www.oreilly.com/catalog/learnxml/"
        >Learning &xml;</ulink></citetitle>, though the
       grouping/labeling in <xref
       linkend="table.SpecsByGroup"/> differs quite a bit
       from Ray's, and it adds some non-W3C technologies.
       So, if you disagree with the table, you've only got
       me to blame. And if you <emphasis
       >really</emphasis> disagree with it, hey, come
       up with your own table, and we'll see if we can get
       a senate subcommittee to evaluate which one's
       better.</para></annotation>
     handy.</para>

   -----------------

   For an example of how the markup above might be
   rendered online, see:

     http://www.logopoeia.com/docbook/dontlearn.html#les2