OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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


I'm just getting more lost.
 
I didn't think my point was so difficult to state,
understand, and discuss.  Perhaps it's just me that
isn't able to pick up on these long messages, so
unless others speak up, I'm about to give up on
this topic.
 
Just a couple points:
 
1.  Regarding camel case, we're talking about attribute
names, not module names, Java, etc.  Let's stick to one
convention for one thing.
 
2.  Regarding RDF, I'm not talking about RDF.
 
3.  Regarding what I call the value of the property (the
metadata or other information you wish to associate with
some element in the document) that a given data element
is associating with some other element in your document
and for which you'd like to be able to use an href at
times to reference--I'm not talking about that. 
 
4.  Regarding how to determine what element in the document
is having some metadata or other information associated
with it by a data element, I'm happy to have the default
be the parent of the given data element (possibly with
some well-defined exceptions for topicrefs and such as
you've outlined elsewhere).  I just want to have a way
to indicate that the information is to be associated
with a different element in some cases.
 
paul


From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: Wednesday, 2005 July 27 14:39
To: Paul Grosso
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Groups - DITA 1.1 Issue # 9 (IssueNumber9.html) uploaded

Hi, Michael and Paul:

There are cases where we might need different hrefs for subject and value. For example, the following content indicates that the book owner has the resource "http://www.xyz.com/":

        <bkowner id="xguideOwner">
           <organization>
               <orgname>XYZ, Inc</orgname>
               <phone>123-456-7890</phone>
               <resource about="#xguideOwner" href="http://www.xyz.com/"/>
           </organization>
       </bkowner>


For clarity, let's use aboutHref and aboutType. The rationale for not providing a "value" prefix on the value href and type would be consistency with DITA linking elements and because the value is more common than the subject because the subject can be identified through containment by default.
I'd suggest camel case because:

1) The TC adopted that practice for module names
2) Other extensible type systems (such as Java) have had good success with a naming convention based on camel case.

The existing DITA linking elements supply a type attribute so an instance can declare that links should go to the specified type element or its specializations. For instance, if a <conceptref> element specializes <topicref> and sets the type attribute to "concept," a validating build should report a warning if the referenced topic is a task topic.

It would probably be appropriate for an editor to filter targets based on the type when building a list for selecting the target of a reference.

In passing, I'd note that there's a problem with the type. For precision, the type should be set to the qualified type name (as in concept/concept). The author, however, doesn't know about the qualification and thus can't be required to provide it when setting the attribute in the instance.

I'd propose that the type can specify a target type constraint for href or specify the datatype (date, integer, etc) for a value, which could be useful to specialized processing.

Default DITA processes wouldn't access the referenced target, but if specialized processes might, we should probably also provide an aboutFormat and format attributes.

The typeid (maybe not the best name) would be a well-known external identifier for the semantic of the property type. Typically, the typeid would be defaulted in the schema. For instance, the following source

    <bookmap id="xguide">
        <bkpublisher>
           <organization>
               <orgname aboutHref="#xguide"

                    typeid="http://purl.org/dc/terms/publisher"
                    >XYZ, Inc</orgname>
               <phone>123-456-7890</phone>
               <resource href="http://www.xyz.com/"/>
           </organization>
       </bkpublisher>

    </bookmap>

would let a generic RDF output transform produce the following representation of the data:

    <rdf:Description rdf:about="xguide.rdf#xguide">
        <publisher xmlns="http://purl.org/dc/terms/">XYZ, Inc</publisher>
    </rdf:Description>

Suggestions for a better attribute name than typeid?

For a description of the keyref attribute, see:


Pending separate discussion of keyref, we might need to add keyref here for both subject and value.

So, the current damage:

<!ELEMENT data      (#PCDATA|%keyword;|%term;|%image;|%object;|%ph;|%data;)*>
<!ATTLIST data      %univ-atts;
                   name        CDATA #IMPLIED
                   label       CDATA #IMPLIED
                   typeid      CDATA #IMPLIED
                   aboutHref   CDATA #IMPLIED
                   aboutType   CDATA #IMPLIED
                   aboutFormat CDATA #IMPLIED
                   value       CDATA #IMPLIED
                   href        CDATA #IMPLIED
                   type        CDATA #IMPLIED
                   format      CDATA #IMPLIED
                   outputclass CDATA #IMPLIED
>

Contexts for the <data> element:

* any block context (that is, peer of <paragraph> and <ol>) within the body of topics
* any <topicref> context within maps (so data can be incorporated into collections)
* any context where the <keyword> element can appear
* any metadata container such as <prolog>, <metadata>, and <topicmeta> (at the end of the existing content model)


Comments?


Erik Hennum
ehennum@us.ibm.com


"Paul Grosso" <pgrosso@arbortext.com> wrote on 07/27/2005 10:23:58 AM:

> I'm not finding the keyref attribute anywhere in

> http://docs.oasis-open.org/dita/v1.0/langspec/ditaref-type.toc.html
>  
> If it's being added in 1.1, where can I find the
> writeup on it?
>  
> I can't answer your first question yet.  I know href
> doesn't do what I want, but I don't know how keyref
> does what Erik's about attribute was going to do.
>  
> paul
>
> From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
> Sent: Wednesday, 2005 July 27 8:59
> To: Paul Grosso
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] Groups - DITA 1.1 Issue # 9 (IssueNumber9.html) uploaded

>
> 1) Could we get rid of "about" and "aboutType" if we just say that
> the href/keyref attributes already provide equivalent functionality?
> IE, if the data element references other content, then the data
> element is about that content; otherwise the data element is about
> the parent element.
>
> 2) With regards to providing href: there are a set of attributes
> that typically come along with href, including scope, format, and
> type. It looks like you've got valueType below acting as equivalent
> to the existing type attribute - for consistency's sake I think we
> should either keep it the same, or split off type so that valueType
> applies to value and type applies to href.
>
> 3) how is typeID different from "id"? (which is already there
> courtesy of univ-atts)
>
> Michael Priestley
> mpriestl@ca.ibm.com
>

>
> "Paul Grosso" <pgrosso@arbortext.com>

> 07/27/2005 09:42 AM
>
> To

>
> <dita@lists.oasis-open.org>

>
> cc

>
> Subject

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

>
>
>
>
> I'm mostly okay with this.
>  
> Regarding aboutType and valueType, I note we
> don't use camel-caps in any other DITA attribute.
>  
> I'm unclear what an editing tool or publishing
> process should do about aboutType and valueType.
> We'd need to specify this more clearly before we
> can add this to the DITA language.  Can you elaborate
> on the processing expectations for these attributes
> including comparing/constrasting with the existing
> type attribute?
>  
> paul
>
> From: Erik Hennum [mailto:ehennum@us.ibm.com]
> Sent: Tuesday, 2005 July 26 19:38
> To: Paul Grosso
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] Groups - DITA 1.1 Issue # 9 (IssueNumber9.html) uploaded

> Hi, Paul and Committee:
>
> Let's follow the RDF/A proposal and add an optional about attribute:
> http://www.w3.org/MarkUp/2004/rdf-a

>
> The rule for determining the subject of the <data> property:
>
> * If you supply a URI (or key reference) in the about attribute, the
> subject of the property is the identified target.
>
> * If you omit the about attribute, the default subject is the parent
> element with the following exceptions for consistency with existing
> attribution of metadata elements:
>
> o If the parent element is <prolog> or <metadata>, the default
> subject of the property is the topic.
>
> o If the parent element is <topicmeta>, the default subject of the
> property is the grandparent if the grandparent doesn't have an href
> element. If the grandparent does have an href element (ie, a
> reference), the subject of the property is the target of the
> reference. (That's the long way of saying that the metadata applies
> to the target of a <topicref> or <navref> element.)
>
> I see clear value for the about attribute where content is generated
> by an automated process or where the subject can vary from instance
> to instance.
>
> I have a harder time seeing the value where the content is authored
> and the subject should always be an element with the same
> containment relationship. The author has to identify the subject
> correctly in every document instance, which seems burdensome and
> error prone. To minimize the errors, we should probably have an
> aboutType attribute that can specify the type for the target of the
> about attribute. That way, the designer of a specialized <data>
> element can constrain the valid subject for the about attribute.
>
> In the following example (where <bkrights> and everything it
> contains are specialized from the <data> element), we have the phone
> of the owner of the book:
>
>    <bookmap id="xguide">
>        <bkrights>
>           <bkcopyrfirst><year>2003</year></bkcopyrfirst>
>           <bkcopyrlast><year>2005</year></bkcopyrlast>
>           <bkowner id="xguideOwner" about="#xguide">
>               <organization>
>                   <orgname>XYZ, Inc</orgname>
>                   <phone about="#xguideOwner">123-456-7890</phone>
>                   <resource href="http://www.xyz.com/"/>
>               </organization>
>           </bkowner>
>       </bkrights>
>        ...
>    </bookmap>
>
> In the following alternative, we have the phone of the organization
> of the owner of the rights of the book:
>
>    <bookmap>
>        <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>
>        ...
>    </bookmap>
>
> In the following example (where <maintainer> is specialized from
> <data>), we have the maintainer of the topic:
>
>    <topicref href="sometopic.dita">
>       <topicmeta>
>           <maintainer>Sachiko</maintainer>
>       </topicmeta>
>       ...
>   </topicref>
>
> In the following example, we have the maintainer of the position in the map:
>
>    <topicref id="thisbranch" href="sometopic.dita">
>       <topicmeta>
>           <maintainer about="#thisbranch">Sachiko</maintainer>
>       </topicmeta>
>       ...
>   </topicref>
>
> In passing, the downside here is that we have no way to simplify the
> author's life by creating a specialized element that always applies
> data to the map position instead of the referenced topic. We can set
> the aboutType to constrain the subject to topicref elements.
>
> Here are some examples of potential uses for a specialized <data>
> element within the topic content.
>
> In the following example (where the <sourceFile>, <startDelimiter>,
> and <endDelimiter> elements are specialized from <data> but the
> <codeFragment> is specialized from <pre>), we have a start delimiter
> for a code fragment. (Perhaps it is refreshed automatically.)
>
>    <example>
>        <title>An important coding technique</title>
>        <codeFragment>
>         <sourceFile     value="helloWorld.java"/>
>         <startDelimiter value="FRAGMENT_START_1"/>
>         <endDelimiter   value="FRAGMENT_END_1"/>
>         ...
>       </codeFragment>
>   </example>
>
> In the following example (where the <realEstateProperty> and
> everything it contains are specialized from <data> but
> <houseDescription> is specialized from <section>), we have a real
> estate block for a real estate property for a house description:
>
>    <houseDescription>
>        <title>A great home for sale</title>
>        <p>This elegant....</p>
>        <realEstateProperty>
>         <realEstateBlock value="B7"/>
>         <realEstateLot   value="4003"/>
>         ...
>       </realEstateProperty>
>       <object data="javascript:void(0);"/>
>   </houseDescription>
>
> Other possible specializations include the core components of UBL.
>
> Will that fly? I've appended the tally of attributes (by my count).
>
>
>
> Thanks for working through the issues,
>
>
>
> Erik Hennum
> ehennum@us.ibm.com
>
>
>
> <!ELEMENT data      (#PCDATA|%keyword;|%term;|%image;|%object;|%ph;|%data;)*>
> <!ATTLIST data        %univ-atts;
>                     name        CDATA #IMPLIED
>                     label       CDATA #IMPLIED
>                     typeid      CDATA #IMPLIED
>                      about       CDATA #IMPLIED
>                     aboutType   CDATA #IMPLIED
>                     value       CDATA #IMPLIED
>                     href        CDATA #IMPLIED
>                     keyref      CDATA #IMPLIED
>                     valueType   CDATA #IMPLIED
>                     outputclass CDATA #IMPLIED
> >
>
> name = authored name of the type (typically, the same as the
> specialized element name)
> label = display label for the type
> typeid = full machine-processable identifier for the type
> about = reference to a DITA element or non-DITA resource that's the
> subject of the data
> aboutType = element constraint on the subject
> value = literal data value
> href = "referenced" data value that's either a DITA element or non-DITA resource
> keyref = key referenced data value
> valueType = constraint on the value, href, or keyref
> ouputclass = weak semantic assertion about the instance
>
> A <data> element can have only one of the value, href, or keyref
> attributes (or none of the three).
>
> The rest of the proposal:
> http://www.oasis-open.org/apps/org/workgroup/dita/download.
> php/13539/IssueNumber9.html


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]