Public Comment

[comment-form@oasis-open.org]

Comment from: ehennum@us.ibm.com

On behalf of IBM, I'd like to make the following proposal to the TC
for a minor change prior to the initial OASIS DITA release that would
have major benefits for DITA adopters.

-------------------------------------------------
Data Element Proposal

This note proposes adding a new element to DITA to support
extensible record structures.

Problem
--------

DITA provides only limited extensibility for topic metadata.  A
designer can specialize from the othermeta element for simple
metadata values, but the designer can't define complex metadata
structures similar to the existing metadata properties.

The same extensibility limitation applies to other machine-processable
properties of the topic in the prolog.  The specializer can't create
complex property structures.

As a result, specializers are forced to specialize body content to
create complex data structures.  (For examples, see the eNote
record-oriented demo and the bookmap book collection demo.)  These
data structures are not part of the topic content and thus don't
belong in the body.


Proposal
--------

Add a new element with unspecified semantics as a basis for
specializing data structures.  Expressed with DTD syntax:

<!ELEMENT data      (#PCDATA|%state;|%keyword;|%image;|%object;|%ph;|%data;)*>
<!ATTLIST data        %univ-atts;
                      name   CDATA   #REQUIRED
                      keyref NMTOKEN #IMPLIED
                      href   CDATA   #IMPLIED
>

The data element would have a loose content model to provide a basis
for specialization.  Content could include any of the following:

*  Textual content.

*  Data oriented subelements such as state and object.

*  A phrase for isolated fragments of content out of the main flow of
   discourse such as biographical blurbs and so on.

*  An href and keyref attributes because data often has links and keys
   expressed as URIs.

*  Recursion for creation of deeper substructure.

Zero or more instances of the data element could appear in the
following contexts:

*  At the end of the content list for the metdata element so new
   kinds of metadata can be added to the topic.

*  At the end of the content list for the prolog element so new
   properties can be added to the topic.

*  In the content list for the body element so new kinds of data
   structures can be added to the topic content structure.

*  In content lists where the ph element can appear so new kinds
   of data structures can be embedded in content.

Providing the data element to the body and ph contexts would offer
additional benefits in that a DITA topic specialization could provide
a mix of machine processable and human readable content.

The default processing for the data element would be to ignore it
silently because the data element has no semantics.  Thus, processing
has to be provided for the specialization.  Because the specialized
element can generalize to the data element, however, interoperability
is still preserved when topic is exchanged with other DITA adopters.
Other DITA adopters simply ignore the data, which is meaningless in
their applications anyway.

As a design note, specializers should never use the data element to
specialize an element for human readable content because the content
will be ignored and the topic will thus be incomplete if the topic is
generalized.


Examples
--------

In the DITA 1.3 distribution on IBM DeveloperWorks, the eNote demo
supports the following record in the topic body.  The subelements of
the noteheader element could all be modelled as specializations of the
proposed data element, so the noteheader could become the topic
prolog:

<noteheader>
    <From>
        <recipient href="dond@us.ibm.com">Don Day</recipient>
    </From>
    <To>
        <recipient href="ehennum@us.ibm.com">Erik Hennum</recipient>
        <recipient href="john_hunt@us.ibm.com">John Hunt</recipient>
    </To>
    <Date>2004-03-24</Date>
    <delivery>
        <Importance value="high"/>
        <ReturnReceipt state="yes"/>
    </delivery>
    <references>
        <InReplyTo href="OF910137D5.CFA24150-ON87256E60.0062F17A-88256E60.00639864@LocalDomain"/>
    </references>
</noteheader>

Similarly, the bookinfo file for the bookmap demo supports the
following record in the topic body.  The subelements of the bkinfobody
could all be modelled as specializations of the data element, which
would allow us to move the bookinfo elements into the metadata of the
bookmap where they really belong (and rename the container from
bkinfobody to a bkinfo specialization of topicmeta).  The benefits
include using existing metadata elements with the additional
properties and being able to declare any data of the book inline
within the bookmap itself or externally via conref.

<bkinfobody>
    <bkrights>
        <bkcopyrfirst><year>2003</year></bkcopyrfirst>
        <bkcopyrlast><year>2004</year></bkcopyrlast>
        <bkowner>
	         <organization>
		       <orgname>International Business Machines</orgname>
                <address>New Orchard Road
Armonk, New York 10504</address>
                <phone>914-499-1900</phone>
                <resource href="http://www.ibm.com/"/>
            </organization>
        </bkowner>
    </bkrights>
</bkinfobody>


Issues
------

The data element should also be added to the end of the topicmeta
element in the DITA map.  That way, prolog and metadata is consistent
across topic and map, and map benefits from the ability to specialize
complex metadata and topic properties.  To allow this, DITA needs a design
pattern so the ph element and its specializations can be shared
between maps and topics.

While it's clear that data should be added to the topic body element,
it's not clear whether it should be added to the conbody, refbody, and
taskbody specializations.