[docbook-tc] Annotation element: Concrete proposal

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

Here is my take on a (rough) proposal for adding an Annotation element
to DocBook. I hope we'll be able to discuss the rationale more during
the TC call today.


Proposal:     Add an Annotation element to DocBook, with the following
              documentation and content model.


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

     Content Model [basically same as the content model for Footnote]
     ----------------------------------------------------------------
     [unexpanded]

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

     [expanded]

     annotation ::=
       ((calloutlist|glosslist|itemizedlist|orderedlist|segmentedlist|
         simplelist|variablelist|literallayout|programlisting|
         programlistingco|screen|screenco|screenshot|synopsis|
         cmdsynopsis|funcsynopsis|classsynopsis|fieldsynopsis|
         constructorsynopsis|destructorsynopsis|methodsynopsis|
         formalpara|para|simpara|address|blockquote|graphic|graphicco|
         mediaobject|mediaobjectco|informalequation|informalexample|
         informalfigure|informaltable)+)

     Attributes
     --------------------------------------------------------------
     Name                   Type                Default
   
     label                  CDATA               none

     class                  Enumeration:        none
                            expansion
                            definition
                            title
                            
    Parameter Entities [same as Remark]
    ----------------------------------------------------------------
    %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; 

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.

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".)

Parents:       These elements contain Annotation (same as Remark):

               abbrev, ackno, acronym, answer, appendix, application,
               article, artpagenums, attribution, authorinitials,
               bibliodiv, bibliography, bibliomisc, blockquote,
               bridgehead, callout, caution, chapter, citation,
               citetitle, city, classsynopsisinfo, collabname, command,
               computeroutput, confdates, confnum, confsponsor,
               conftitle, constraintdef, contractnum, contractsponsor,
               contrib, corpauthor, corpname, country, date, edition,
               email, emphasis, entry, fax, firstname, firstterm,
               foreignphrase, funcparams, funcsynopsisinfo, function,
               glossary, glossdef, glossdiv, glosssee, glossseealso,
               glossterm, holder, honorific, important, index,
               indexdiv, invpartnumber, isbn, issn, issuenum, jobtitle,
               label, lineage, lineannotation, link, listitem, literal,
               literallayout, lotentry, manvolnum, member, modespec,
               msgaud, msgexplan, msgtext, note, olink, optional,
               orgdiv, orgname, otheraddr, othername, pagenums, para,
               partintro, phone, phrase, pob, postcode, preface,
               primary, primaryie, procedure, productname,
               productnumber, programlisting, pubdate, publishername,
               pubsnumber, qandadiv, qandaset, question, quote,
               refentry, refentrytitle, refmiscinfo, refnamediv,
               refpurpose, refsect1, refsect2, refsect3,
               refsynopsisdiv, releaseinfo, remark, replaceable,
               revdescription, revnumber, revremark, screen,
               screeninfo, secondary, secondaryie, sect1, sect2, sect3,
               sect4, sect5, section, see, seealso, seealsoie, seeie,
               seg, segtitle, seriesvolnums, setindex, shortaffil,
               sidebar, simpara, simplesect, state, step, street,
               subscript, subtitle, superscript, surname, synopsis,
               term, tertiary, tertiaryie, tip, title, titleabbrev,
               tocback, tocentry, tocfront, trademark, ulink,
               userinput, volumenum, warning, wordasword, year.

Children:      The following elements occur in Annotation (same as Footnote):

               address, blockquote, calloutlist, classsynopsis,
               cmdsynopsis, constructorsynopsis, destructorsynopsis,
               fieldsynopsis, formalpara, funcsynopsis, glosslist,
               graphic, graphicco, informalequation, informalexample,
               informalfigure, informaltable, itemizedlist,
               literallayout, mediaobject, mediaobjectco,
               methodsynopsis, orderedlist, para, programlisting,
               programlistingco, screen, screenco, screenshot,
               segmentedlist, simpara, simplelist, synopsis,
               variablelist.


Attributes:    Label -- identifies the desired annotation mark
               Class -- identifies the type of annotation