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