DOCBOOK: Issues with processing expectations of the proposedannotation element

[Paul Grosso <pgrosso at arbortext dot com>]

At 14:38 2002 06 25 -0400, Norman Walsh wrote:
>| The DocBook Technical Committee met on Tuesday, 25 June 2002

 . . .

>| 8. Discuss Annotations {15 min}
>
>     Annotations would be associated with the element that contains them.
>     Mike points out that this would allow the content of an element that contained
>     an annotation to be presented with a special color or other distinctive
>     presentation.
>
>     Mike: if we want to add an element for associating expanded/spelled-out versions
>     of acronyms and abbreviations, we might want to provide a broader solution so
>     that we could support anything someone wanted to annotate.
>
>     Footnote has legacy connotations.
>
>     ACTION: Paul to send email describing some unresolved processing expectation
>     issues.

By way of background, Mike sent the following email:

* Annotation element: Concrete proposal, Tue, 16 Apr 2002 06:08:24 -0500 [1]

* Annotation element: Background/Use cases, Tue, 21 May 2002 02:18:48 -0500 [2]

* Annotation element: Some rendered examples, Tue, 21 May 2002 02:29:23 -0500 [3]

The proposal in brief is to have an annotation element (with possible substructure) 
that (1) contains some material forming the annotation and (2) is contained within 
the element to be annotated (that is, the parent of the annotation element is the 
annotated element).  An annotation element is an out-of-line (aka "floating")
element in that its contents is not rendered within the usual flow of text.

Per [1], the processing expectations for an annotation is that the
annotation contents 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".)

Issues
------

1.  In paginated output, should annotations be able to be rendered 
as footnotes (e.g., at the bottom of the current page)?  If so, how 
do they interact with footnotes an dother floats?  What if it is 
impossible to get the annotated element and the annotation on the 
same page?  Do you allow a long annotation to be broken up over a 
page?  What is the formatting style (font, paragraph shape, vertical 
spacing before the first one and between subsequent ones, generated 
text [e.g., rule] vertically preceding the first one, generated 
text/marker horizontally preceding each annotation) of the annotations?  
What do you do in the flowing text to indicate some text is annotated?
How do you associate a given annotation with a given annotated element?

2.  In paginated output, should annotations be able to be rendered 
as end notes, that is, collected and emitted at the end of some 
current scoping division?  If so, we have most of the formatting
questions raised above.

3.  In paginated output, should annotations be able to be rendered as 
general floats, e.g., "top of next page" or whatever?  If so, then
we have most of the float-related and formatting questions raised 
in point 1 above.

4.  Most out-of-line elements have an "anchor" or "reference point" 
in the flowing text, and the final location of the floating material
is (at least partially) determined by the location in the flowing text
of this anchor.  The current proposal appears to suggest that the "anchor"
for an annotation element is the entire parent element.  How do we reconcile
this with the point-wise anchor concept?  For example, if the annotation 
is supposed to be printed (in paginated output) on the bottom of the same 
page as its reference, how do we interpret this when the annotated
element breaks over a page (or two)?

5.  If the contents of the annotation element can include complex
substructure (e.g., tables and lists), how can it be of use for the 
HTML title attribute?  I think we should give up on hoping we can use
this annotation element for HTML title attributes.

6.  Can HTML browsers and PDF viewers handle complex substructure 
(e.g., tables and lists) as part of pop up windows?

7.  If an annotation element is contained within a title, does the
copy of the title in the Table of Contents (or List of XXX) also
have the annotation?  Or if the annotation element is contained
within an element, say "year", that is picked up by some XSLT code
to be stored and used elsewhere, what happens to the annotation
in the copy that was picked up?


paul

[1] http://lists.oasis-open.org/archives/docbook-tc/200204/msg00009.html
[2] http://lists.oasis-open.org/archives/docbook-tc/200205/msg00004.html
[3] http://lists.oasis-open.org/archives/docbook-tc/200205/msg00005.html