RE: [dita] Groups - DITA 1.1 Issue # 9 (IssueNumber9.html) uploaded

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Paul and Busy Committee:

Apologies for the slowness responding. (Headcold and lack of headroom.)

To refresh, here's the core proposal again for the <data> element:

http://www.oasis-open.org/apps/org/workgroup/dita/download.php/13539/IssueNumber9.html

I've embedded some comments.


Hoping that's interesting,


Erik Hennum
ehennum@us.ibm.com


"Paul Grosso" <pgrosso@arbortext.com> wrote on 07/12/2005 02:11:02 PM:

> Erik Hennum had written:
> > "Paul Grosso" <pgrosso@arbortext.com> wrote on 07/12/2005 09:26:30 AM:
> >
> > > > From: ehennum@us.ibm.com [mailto:ehennum@us.ibm.com]
> > >
> > > 1.  If the data element provides information about its parent,
> > >     what is the point/meaning/use case for nesting data elements?
> >
> > Here's an example of a potential book information structure
> > for the book map:
> >
> >     <bkrights>
> >         <bkcopyrfirst><year>2003</year></bkcopyrfirst>
> >         <bkcopyrlast><year>2005</year></bkcopyrlast>
> >         <bkowner>
> >             <organization>
> >                 <orgname>XYZ, Inc</orgname>
> >                 <phone>123-456-7890</phone>
> >                 <resource href=""http://www.xyz.com/"/> > >             </organization>
> >         </bkowner>
> >     </bkrights>
>
> It may not be obvious to all which of the above you meant
> to be specializations of <data>.  I'm guessing it's all
> the bk* elements and none others, is that correct?

The entire structure would be specialized from the <data> element.
As usual, the reader was expected to have ESP.


> I gather that bkrights is a child of bookmap, is that correct?
>
> If so, then I assume bkrights is metadata about the bookmap element.

Yes, bkrights would be contained within bookmap and metadata about the
book.  Something like the following:

    <bookmap>
        <bookmeta>
            <bkrights>
                ...
            </bkrights>
            ... other book properties ...
        </bookmeta>


> I could imagine the bkcopyr* elements are metadata about
> the bkrights element, but is bkowner metadata about the
> bookmap element or about the bkrights element?
>
> What if I gave the bkowner element a <data> child that
> included metadata about the incorporation status (stock
> symbol, state of incorporation, etc.) of the bkowner?
> Or maybe this data element would more appropriately be
> a child of <orgname>.  In any case, I can see times I
> want the data element to be referring to its parent and
> other times when it should be referring to the parent of
> its outermost ancestral element that is a specialization
> of data: (ancestor::*[@class=" ...data..."])[1]::parent
> in xpath-ese.

An excellent issue.  To rephrase:

*  Some containers (for instance, <organization>) have
   identity and are the subject of subelement properties
   ("a book can have an owning organization, which in
   turn can have a phone number").

*  Some containers (for instance, <bkrights>) seem to
   provide organizing categories for the properties of
   an ancestor ("some of the book's properties have to
   do with rights, but a book doesn't have rights
   that in turn have copyright years").

Is this distinction one of interpretation, however,
rather than a hard and fast differences that we could
encode in the markup?

For instance, if we added a property specifying the
locales in which a specified set of book rights are
valid, would that make us tend to think of <bkrights>
more as a subject of properties ("a book has rights
in the US and other rights in the EU") and less as
an organizing category?

For some properties, can the same property be considered
to apply to any of several levels of ancestry (treating
the intervening levels of containment as categories that
combine to label the full semantic of the property)?

For instance, does <phone> have a subject of <organization>
or of <bkowner>?  That is, does the organization have a
phone number or does the book owner have an organization
phone number?  For that matter, can we treat a book as
having an owner contact phone number?

For another example, if an application regarded the stock
symbol as the only significant property of rights ownership,
could the application legitimately treat the stock symbol
as a property of the book (albeit with a long semantic label)?
For instance, outputting a rights table in which the rows
are books and the columns consist of the copyright years
and the owner identifiers (stock symbols)?

I'm coming around to the thought that default processing
should treat every data property as having its container
as its subject (with the exception of data contained by the
<prolog> or <metadata> elements, which of course have the
topic as a whole as its subject).

Applications that know the semantics of the data or that
have  access to a more formal definition of property
relationships outside of DITA (such as an RDF definition
of transitivity up the containment hierarchy) are free to
interpret the subjects of properties accordingly.


> > > 2.  Since the data element provides information about another
> > >     element, I wondered if it made sense to provide some kind
> > >     of "idref-ish" attribute on the data element to allow one
> > >     to point to the target element.  But upon reflection, I'm
> > >     not sure it does.
> >
> > The proposed data element has an href attribute for cases where
> > the value is a referenced object (either managed within DITA or
> > external to DITA).
>
> I'm getting lost.  The value of what here?  The value of
> the metadata within the data element?  If so, then that
> sounds more like a kind of conref where you are referencing
> the metadata.
>
> My point #2 here was about the possibility of allowing the
> data element to have an explicit pointer to the element for
> which the data element's content was metadata--to address
> the point discussed in #1 that you might not always want the
> data element's metadata to be just about its parent.
>
> (Given the example below, maybe that is what you mean here,
> I'm not sure.)

I misunderstood.  The thought for the href attribute is the
opposite -- not the subject of the property but the object.

I agree that we need conref, but I'd suggest that we also need
the ability to output values that are references.  For instance,

*  The identifier of the DITA topic that provides the full
   explanation of the license for a product described in a book.

*  The book owner's website.

*  The ISBN for the companion volume expressed as a URI.


> > If a data element with an href contains other data elements, the
> > values would pertain to the referenced object. For instance:
> >
> >     <demonstrator>
> >         <creator value="XYZ, Inc."/>
> >         <access href=""http://www.xyz.com/demo/"> > >             <login>guest</login>
> >             <password>guest</password>
> >         </access>
> >     </demonstrator>
>
> Lost again.  Which elements are specializations of the data
> element here?
>
> Given "a data element with an href contains other data elements",
> I assume all of access, login, and password are data elements,
> is that correct?

All of the elements would specialize data including <demonstrator>.
(The class attributes were set in a virtual document type.)  The
full context might be something like

    <topic ...>
        ...
        <prolog>
            <metadata>
                <product ...>
                    <demonstrator>
                        ...
                    </demonstrator>


> So by "values would pertain to the referenced object" do you
> mean that the login and password values are metadata about
> "http://www.xyz.com/demo/" and not metadata about <access>
> or <demonstrator> or the parent of <demonstrator> (if
> demonstrator is a data element)?

That paragraph should have had its own example.  Consider
the following example where the maintainer element is a
specialized data element:

    <topicref href=""sometopic.dita">
        <topicmeta>
            <maintainer>Sachiko</maintainer>
        </topicmeta>
        ...
    </topicref>

Is Sachiko responsible for maintaining the references in this
branch of the map?  Or for maintaining the referenced content
of sometopic.dita?  A default process would have a hard
time harvesting the data without resolving that ambiguity.

So, the data element might need an attribute to disambiguate
these cases.  Something like

    <!ATTLIST data reference (source|target) "source">

That way, a specialized element could assign a fixed or defaulted
value to the reference attribute in the document type so the
ambiguity wouldn't arise in the instance.  

In the following example, mapMaintainer would have a reference
of source while topicMaintainer would have a reference of target:

    <topicref href=""sometopic.dita">
        <topicmeta>
            <mapMaintainer>Sachiko</mapMaintainer>
            <topicMaintainer>Fred</topicMaintainer>
        </topicmeta>
        ...
    </topicref>

Returning to the earlier suggestion about defining the property
relationships outside of DITA, the ordinary RDF convention to
identify a property is to combine the namespace and element name.

If the element doesn't have a namespace, however, it might be
useful to have an attribute to set the external type identifier:

    <!ATTLIST data typeid CDATA>

That way, a specialized data element can set a defaulted or
fixed attribute in the document type.

    <!-- Dublin Core rights -->
    <!ATTLIST bkrights typeid CDATA "http://purl.org/dc/elements/1.1/rights">

The default process could then use the identifier in the generated
harvested data.