Re: [docbook] Re: DocBook Annotations

["John L. Clark" <jlc6@po.cwru.edu>]

I want to speak to the current annotations in DocBook proposal in
general.  The practice of using a child element to annotate its parent
bothers me at an reflexive, instinctual level, and I wanted to at least
take this opportunity to express that discomfort and encourage an
alternative.

I am uncomfortable primarily because insofar as a subtree is defined by
its root name, attributes, and content, when a child of that root is
given semantics which describe the whole subtree, in effect that
description also applies to the child node (which is doing the
describing in the first place).  I don't think that's what
we want in this case.

While this may not be XML canon, I generally think of child nodes as
"composing" the subtree rooted at their collective parent.  But as I
imagine the semantics of the alt and annotation elements, they do not
seem to help "compose" this subtree so much as "describe" it.  Thus, I
would really like to see such annotations "outside" the subtree.

It seems to me that annotations participate in a relationship with the
subtree that they annotate.  Relationships are usually modeled as
tuples, and I'd like to do the same here.  I went through a number of
designs where I attempted to model the tuples explicitly, using a common
parent, but it always ended up too verbose and too far removed from the
flow of information.

What I would like to suggest, therefore, is a different
application-level semantic than I have typically seen before.  I would
like to specify that annotations modify not their parent, but their
previous sibling.  Instead of:

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

which simply strikes me as odd (the annotation of the phrase is "part
of" the phrase?), one would have:

  <para>Modern browsers display acronym expansions and link titles as
  "<phrase>tool tips</phrase><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>".</para>

with the processing expectation that the annotation be "associated" with
the phrase (as opposed to the para).

Further, I think that there should be an option to allow annotations to
pick their targets using the IDREF mechanism that you would expect,
should the author want to place them elsewhere.  For example:

  <para>Modern browsers display acronym expansions and link titles as
  "<phrase xml:id="tt">tool tips</phrase>"</para>

  <!-- Other content... -->
  
  <annotation linkend="tt">
    <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>

I think I would prefer to author annotations using such a system.

On Tue, Feb 15, 2005 at 03:53:12PM -0500, Norman Walsh wrote:
> I suppose we could call it "anot" or something instead of "alt", but
> one of the most common use cases is (I imagine) going to be for
> accessibility and lots of folks are used to calling that stuff "alt
> text".

I know this ground has been covered before, but I still think an
attribute is more appropriate for this type of annotation.  I think the
80/20 split for "simple, inline annotations" falls firmly on the side of
text-only annotations, for which an attribute is a clear winner.  I
think it wins because it is more clearly attached to the element in
question and doesn't "get in the way" of that element's content.  The
only thing it *doesn't* do is allow for a structural annotation, but I
think this falls well into the 20 side of the house (and is clearly
covered by the annotation element).

For example:

  <para xmlns:ext="tag:jclark@nps.edu,2005-02-15:alt_types">The <acronym
  alt="Organization for the Standardization of Structured Information
  Standards" ext:alt_type="acronym-expansion">OASIS</acronym> DocBook
  <acronym alt="Technical Committee"
  ext:alt_type="acronym-expansion">TC</acronym> is responsible for
  maintaining the <span alt="Language for Expressing Technical
  Documentation" ext:alt_type="elaboration">DocBook</span>
  schemas.</para>

As Jirka also mentioned, there are other examples of this in DocBook
(and likely many, if not most, other languages).  When thinking about
accessibility, we may want to particularly step lightly with respect to
this issue.

Thanks for listening to my thoughts.  I look forward to any feedback
that you might have.

Take care,

    John L. Clark

PGP signature