DOCBOOK: Playing with annotations...

[Norman Walsh <ndw at nwalsh dot com>]

At the last TC meeting, I took an action to experiment with stylesheet
support for annotations. Hours before the next TC meeting :-), I've
finally pushed that action to the top of my list. At

  http://nwalsh.com/annot.zip

you'll find my attempts. I've shown four of five styles that seem like
obvious possibilities to me. Two independent axes produce four of the
possibilities: simple or discrete and popup or no-popup.

Consider:

<phrase>Hello World<annotation class="note">A common test phrase</annotation></phrase>

Simple display of annotations puts them inline:

  Hello World[<a>Annotation</a>]

Discrete keeps them off the screen by percolating the link up to the
containing element:

  <a>Hello World</a>

popup uses JavaScript to make hovering over the link popup a window
containing the annotation. Non-popup doesn't, but uses JavaScript to
popup a new browser window if the user clicks on it.

The fifth possibility is "simple, no-popup" with the actual
annotations rendered like footnotes at the bottom of the page, instead
of using a new browser window to display them

One of the reasons for the experiment was to see if it shed light on
the seven issues that Paul raised[1] when we first started considering
annotations:

> 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 

Yes.

> do they interact with footnotes an dother floats? 

I'm tempted to make them footnotes labelled differently and presented
in the same footnote list as other footnotes, either before all the
other footnotes or after them.

> 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?

Apply the same rules as footnotes.

> 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?  

Where footnotes get labelled "1", "2", "3", etc. I'm tempted to label
annotations with either their label, if they have one, or "Ann-1",
"Ann-2", etc.

I would format them in all other respects like footnotes.

> What do you do in the flowing text to indicate some text is annotated?

Output the label that's used at the bottom of the page.

> How do you associate a given annotation with a given annotated element?

For the paginated case, if you're using PDF "popup" features as Mike
showed[2], I think you can go with either the simple or discrete
style. If you're using footnotes, I think the simple style is the way
to go.

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

I think the answer is probably yes, and the same answers apply to the
formatting questions.

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

I don't think there should be a requirement that it be possible to
render them that way. But I don't see any reason to forbid it.

> 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)?

The simple style I've described above "fixes" this problem by allowing
the start of each anchor to be a point location, just as the start of
each footnote marks a point location.

If you want to use the discrete style, I think you could choose either
the start or end of the parent element as the relevant point location.

I guess my mental model is that annotations are even less important
than footnotes in the sense that the reader shouldn't "need" them to
understand or interpret the text. So I'm willing to be relaxed about
their exact placement (I think I could even be convinced that it's ok
to throw them away entirely).

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

Mike's solution, also implemented by the stylesheets actually (hover
over 'e.g' in the HTML), is to allow the author to indicate that an
annotation is specifically intended to be a "title" for the
surrounding element.

I'm unhappy with the moniker "title" but I didn't try to fix that now.
If you put arbitrary structure in a title annotation, you will
probably get just the text content.

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

Yep.

> 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? 

No. (IMHO).

> 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?

I'd say it should be left behind.

                                        Be seeing you,
                                          norm

[1] http://lists.oasis-open.org/archives/docbook/200206/msg00153.html
[2] http://lists.oasis-open.org/archives/docbook-tc/200205/msg00005.html
-- 
Norman Walsh <ndw@nwalsh.com>      | As charms are nonsense, nonsense
http://www.oasis-open.org/docbook/ | is a charm.--Benjamin Franklin
Chair, DocBook Technical Committee |