Re: [docbook-tc] annotation proposal

["Bob Stayton" <bobs@sagehill.net>]

----- Original Message ----- 
From: "Norman Walsh" <ndw@nwalsh.com>
To: <docbook-tc@lists.oasis-open.org>
Sent: Thursday, April 14, 2005 4:48 PM
Subject: Re: [docbook-tc] annotation proposal


> / "Bob Stayton" <bobs@sagehill.net> was heard to say:
> | By using two different attachment mechanisms for the
> | two annotation elements, the distinction between them
> | is made even stronger.  I think that is a good thing.
> | I don't think <alt> needs any mechanism for
> | doing remote annotations or reuse of annotations.
> | But <annotation> does.  
> 
> On the whole, I think that's a fine proposal. Some questions and
> comments, in no particular order.
> 
> 1. I agree we should make the attributes CDATA. That allows, in principle
> at least, refersto="somefile.xml#someid"

Yeah, I was wondering about extending the connections to
other documents, but I didn't want to go there yet.  
I don't want to end up with RDF.  8^)
 
> 2. I'm not real wild about the name 'refersto'. What about 'annotates'?

Yeah, I kept reading it as "refer sto".  I think "annotates" is 
much better.

> 
> 3. Having both directions explicit means you can get mismatches. What
> does this mean:
> 
>   <para xml:id='p1' annotations='a1 a2'>...
> 
>   <annotation xml:id='a1' refersto='p1'>...
>   <annotation xml:id='a2' refersto='p2'>...
> 
> Is it an error? Does it mean the relationship is 1-way for a2 and
> two-way for a1? Does it make sense? Is that what users will want? We
> could also propose that they were always two-way and the processor was
> required to build the union.

No, it is not an error.  I should have made it clear that
I meant that either direction establishes the association.
Using both directions is just a convenience.  

So it means "the p1 para and the a1 annotation have an
association, and the p1 para and the a2 annotation have
an association.  The a2 annotation has an association
with a p2 element, which we can't see yet."
The only potential error here is if there is no element
with xml:id="p2".

> 
> 4. Is there any relationship between extended XLink and annotations?

I'm not proposing any.  I think that adds to the complexity,
and we would have to examine what would be gained by it.
 
> 5. Are annotations required to have an xml:id or a refersto?

No.  I think it should be possible to create annotation elements
and link them later.  Also, since a link can be established in
either direction, neither attribute would be required, although
an <annotation> won't be connected unless it has one or the other.
 
> 6. Is this allowed? How is this processed?
> 
>   <para>Hello<annotation>...</annotation> world.</para>

It is allowed, if we say that an annotation element can
appear just about anywhere.  Because it has no attributes,
the <annotation> in this example is not associated with
any element, not even the para it is inside.  In the
proposed scheme, all annotation elements are out-of-line,
they can appear anywhere, and their location means nothing.
They are connected only through the attributes.  The para
is simply a holding tank for the annotation element, and is
not otherwise associated with it.  To associate it with the
para, add the appropriate attributes.  Perhaps that is the part
of this proposal that people will have a hard time with.

How is it processed?  I have no idea.  The schema assigns
no semantics to <annotation>.  I guess the default processing
should be that an <annotation> element is ignored.

> 7. More generally, where are annotations allowed?

I'll go out on a limb here and say anywhere that an
indexterm is allowed.  I think we will have to look more carefully
at the implications, if people agree that this is a useful
design.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net