OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-tc message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: [docbook-tc] Annotation element: Concrete proposal

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

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

     annotation ::=


     annotation ::=

     Name                   Type                Default
     label                  CDATA               none

     class                  Enumeration:        none
    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.

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,

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC