Re: DocBook Annotations

[Norman Walsh <ndw@nwalsh.com>]

/ Norman Walsh <ndw@nwalsh.com> was heard to say:
[...]
| annotation
| ----------
|
| annotation - a comment about, or explanation of, an element
|
| Processing expectations
| -----------------------
|
| An annotation contains a comment, explanation, or other description of
| an element. Annotations are not intended to be rendered in the normal
| flow of the text. In an interactive environment, they may be rendered
| as links or popups. In a non-interactive environment such as
| traditional printed media, they may be rendered as marginalia, end
| notes, footnotes, or even be suppressed entirely.
|
| Examples
| --------
|
| <para>Modern browsers display acronym expansions and link titles as
| “<phrase>tool tips<annotation>
| <title>Tool Tips</title>
| <para>A tool tip is a word or short phrase displayed automatically by
| an application when the user hovers the mouse over some component in the
| user interface.</para></annotation></phrase>”.</para>

Paul and I were talking about this earlier today and we kicked around
another possibility. This may be along the same lines as what John
Clark proposed.

We could instead do this:

...
<info>
<annotation xml:id="anot.tooltip">
<title>Tool Tips</title>
<para>A tool tip is a word or short phrase displayed automatically by
an application when the user hovers the mouse over some component in the
user interface.</para></annotation>
</info>
...
<para>Modern browsers display acronym expansions and link titles as
“<phrase annotations="anot.tooltip">tool tips</phrase>”.</para>

This moves the annotation out of line and allows more than one element
to point to it. (annotations is an IDREFS, though then folks will
wonder if xlink:href works there...)

If we don't use ID/IDREFS, we're going to need to add annotationref,
I'm afraid.

Pros: Looks less like footnote.
      Removes the semantic that it applies to its container.
      Allows the same element to apply to multiple elements

Cons: Authors can't put annotations near where they're used.
      Less control over where/how the formatting occurs,
         (though I suppose <anchor annotations=""/> could work around that)
      Requires annotationref to apply the same annotation to multiple elements

*shrug*

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Everything should be made as
http://www.oasis-open.org/docbook/ | simple as possible, but no simpler.
Chair, DocBook Technical Committee |

PGP signature