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