OASIS DocBook TC2

 View Only

summary: Annotation element

  • 1.  summary: Annotation element

    Posted 03-18-2003 10:53
    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