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] @keys in <topicsetref>


Hi Eliot, 

I agree with you & Robert, that binding a key to a topicref doesn't make much sense. I would suggest we shall streamline the behavior for URI & Key-referencing in this case.

Taking your example again(in map submap-01.ditamap):

<topicref id="tr-01" keys="topicref-01">
    <topicmeta>
      <keywords id="tr-01_keywords"/>
    </topicmeta>
</topicref>


URI Reference to topicref:
	"submap-01.ditamap#tr-01"
URI Reference to elements other than topicrefs (say <keywords> above):
	"submap-01.ditamap#tr-01_keywords"

Now, suppose if we allow the key to be bound to a map only and never to an element (topicref/non-topicref) inside the map; the key-referencing shall happen as follows:

<topicref key="submap-01" href="submap-01.ditamap" format="ditamap"/>

Now,
KEY Reference to topicref:
	"submap-01/tr-01"
KEY Reference to elements other than topicrefs (say <keywords> above):
	"submap-01/tr-01_keywords"

Hence, there is no difference in how you refer to a topicref element and a non-topicref element inside a map. The only difference is the mechanism you choose - URI or KEY. Once, the mechanism is decided, there is no discrimination.

But, that brings us to another thing. A key can be bound to any resource that a topicref can refer to:
1) Topic File.
2) Topic element inside a Topic File.
3) Map File
4) Topicref element inside a Map File.
5) non-DITA resource.
So, does that mean (4) becomes an exception for this ?

Also, since there is a difference in the way referencing to topic elements & map elements is done.

For Topic, it is - File#UniqueId/Id (Or File#Topic-id/Element-id)
For Map, it is - File#Id  (Or File#Element-id)

For key-referencing,
- In case of Topics "File#UniqueId", part gets replaced with "key-name" and "/Id" part is intact.
- In case of maps, "File#", part gets replaced with the "key-name/" and the "Id" part is intact.

This could be one of the ways for visualizing keys for someone used to using URI referencing. That brings another question to my mind - Why can't we have similar format for referencing elements in map (same as for topics) ? (I am not sure if this has been discussed earlier; as this is not specific to v1.2)
Although map-id is not needed for referencing elements inside a map, I see no harm in adding it to the referencing format, for ensuring consistency. Considering this:
For Topic, it would be - File#UniqueId/Id (Or File#Topic-id/Element-id)
For Map, it would be - File#UniqueId/Id (Or File#Map-id/Element-id)

It will help in bringing consistency at two places:
a) The URI format for referencing MAP elements & TOPIC elements
b) The KEYREF format for referencing MAP elements. Considering this, for both maps & topics the "key-name" shall replace the "File#UniqueId" part of the URI and both will have "/Id" part intact.

Regards,
Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com


-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Wednesday, August 25, 2010 9:15 PM
To: Robert D Anderson; Tarun Garg
Cc: dita; dita-comment@lists.oasis-open.org
Subject: Re: [dita] @keys in <topicsetref>

For references to elements within maps there are the following
possibilities:

1. A topicref with an associated keyname may be addressed by that key, e.g.:

Key definition (in map submap-01.ditamap):

<topicref id="tr-01" keys="topicref-01">
 <topicmeta>
  <keywords id="tr-01_keywords"/>
 </topicmeta>
</topicref>

Key references: 
  
- From a map that is in the same map tree as submap-01.ditamap):

   <topicref keyref="topicref-01"/>

- From a topic:

   <xref keyref="topicref-01"/>

2. A topicref with an ID attribute addressed by URI:

- From a map:

    <topicref href="submap-01.ditamap#tr-01"/>

- From a topic:

   <xref href="submap-01.ditamap#tr-01"/>

[Need to check what, if anything, the implication is for the second
reference when scope="local"]

3. A non-topicref element addressed by URI:

- From a map:

<topicref>
 <topicmeta>
  <keywords conref="submap-01.ditamap#tr-01_keywords"/>
 </topicmeta>
</topicref>

- From a topic
   
  I don't think there's a sensible or valid use case here as you cannot
conref from a topic to a map because of conref constraints (the doctypes of
maps and topics cannot ever be compatible because the base structural types
are different).


4. A map addressed by URI:

Key definition:

<topicref key="submap-01" href="submap-01.ditamap" format="ditamap"/>

Key reference (in a map, references to maps from topics has no defined
meaning in DITA 1.2 [it will in DITA 1.3, but that's for another time]):

<topicref keyref="submap-01" format="ditamap"/>

5. A non-topicref element addressed by key:

   Here the only sensible case would, I think, be to use a key definition
that already binds the target map. In that case, a keyref of
"{keyname}/{elementId}" is perfectly sensible since the key reference
establishes the map context within which the ID occurs.
However I definitely agree with Robert that it would not make sense when the
key is bound to a topicref (which it can be, per the examples above).

It seems to me that the use case for addressing non-topicref elements in
maps via key is pretty tenuous--the only use I can think of would be conref
and the only non-topicref elements that can occur within maps are reltables
and metadata, neither of which would normally be useful conref targets.

So I would be happy to amend the spec to disallow key-based addressing of
non-topicref elements in maps because while I think its sensible in the
specific case of keys bound to maps, it's such an edge case that the lack of
it would not significantly inconvenience any users.

Cheers,

Eliot


On 8/25/10 8:49 AM, "Robert D Anderson" <robander@us.ibm.com> wrote:

> Hi Tarun,
> 
> Thanks for the comments. There is clearly some confusion here. I think that
> the spec is incorrect when it says:
>       For references to non-topic elements within topics and non-topicref
>       elements within maps, the value of the @keyref attribute is a key
>       name, a solidus ("/"), and the ID of the target element:
>       keyref="topic-key/some-element-id".
> 
> In all of the proposal information leading up to the spec, it was clear
> that the /some-element-id value was *only* for use addressing sub-topic
> elements. I do not know why this changed in the write up for the spec. For
> example:
> * In the "Longer description", the approved proposal says "A key reference
> consists of a key name, optionally followed by a ³/² character and an id of
> a sub-topic element. ".
> * In item 6) of the technical description, it states that the keyref syntax
> is "a key name, optionally followed by the character ³/² and a topic
> element id"
> * In item 24), it implies that topics, maps, and sub-map elements are all
> valid key targets
> * The approved proposal is:
> 
http://www.oasis-open.org/committees/download.php/26493/IssueNumber1207v8b.htm>
l
> 
> In all other addressing attributes in DITA, it is invalid to address a map
> branch with #mapid/branchid - that is only used for topics. It is always
> valid to address map branches with some.ditamap#branch.  This is a valid
> target for a topicref, which means that it can be associated with a key.
> So, the following should be a valid way to associate a key with a
> branch:<topicref format="ditamap" href="other.ditamap#mybranch"
> keys="mykey"/>
> 
> The current spec language indicates that this is also valid:
> <topicref format="ditamap" href="other.ditamap" keys="mykey"/>
> <topicref keyref="mykey/mybranch"/>
> 
> So - I believe that the spec language is wrong, because:
> * It is counter to the original proposal
> * It makes this the only location in all DITA references that map/id is
> used to reference an ID within a map
> * It establishes two ways to reference the same thing
> 
> Thoughts?
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> Tarun Garg <tarung@adobe.com> wrote on 08/25/2010 06:11:35 AM:
> 
>> From: Tarun Garg <tarung@adobe.com>
>> To: Robert D Anderson/Rochester/IBM@IBMUS
>> Cc: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
>> Date: 08/25/2010 06:12 AM
>> Subject: RE: [dita] @keys in <topicsetref>
>> 
>> Hi Robert,
>> 
>> As I understand from this, a key can point to any of the following:
>>    1) Topic File. (Here the key is assumed to be pointing to the
>> first topic in the file)
>>    2) A particular Topic in a Topic File (in case of multiple
>> topics, though it is not a recommended to keep multiple topics in a
>> single file).
>>    3) Map File. (Here keye is assumed to be pointing to the <map>
> element)
>>    4) A particular Topicref inside the Map file.
>>    5) Non-DITA resource
>> 
>> Now, while using this key in the @keyref, following are the
> possibilities:
>> 
>> For 1 & 2,
>>    - @keyref = "key" | Refers to Topic element
>>    - @keyref = "key/element-id" | Refers to an element inside the
>> Topic element
>> 
>> For 3,
>>    - @keyref = "key" | Refers to Map element
>>    - @keyref = "key/element-id" | Refers to a topicref (or any
>> other) element inside the Map element.
>> 
>> For 5,
>>    - @keyref = "key" | Refers to resource
>>    - @keyref = "key/element-id" | This is Invalid
>> 
>> I am not sure for case 4. Please suggest.
>> 
>> Also, please refer to the "syntax" section of "2.1.3.4.3.2 Using
>> keys to address DITA elements". It states:
>>           For references to topics, maps, and non-DITA resources,
>> the value of the @keyref attribute is simply a key name:
> keyref="topic-key".
>>        For references to non-topic elements within topics and non-
>> topicref elements within maps, the value of the @keyref attribute is
>> a key name, a solidus ("/"), and the ID of the target element.
>> 
>> This section also presents some confusion in case of maps. From the
>> first line, a key can point to a map. It says nothing about key
>> pointing to a topicref inside a map. And the next line explains how
>> to refer to non-topicref elements in maps.
>> 
>> Regards,
>> Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com
>> 
>> 
>> -----Original Message-----
>> From: Robert D Anderson [mailto:robander@us.ibm.com]
>> Sent: Tuesday, August 17, 2010 12:29 AM
>> To: Tarun Garg
>> Cc: dita@lists.oasis-open.org
>> Subject: Re: [dita] @keys in <topicsetref>
>> 
>> Hi Tarun,
>> 
>> A key value may be set on any topicref element, so it may be associated
>> with any valid target that can be referenced with a topicref.
>> 
>> A topicref element may not reference elements nested inside a topic, but
> it
>> may be used to reference elements inside of a map. For example, this is a
>> valid reference on a topicref:
>> <topicref href="othermap.ditamap#branch" format="ditamap"/>
>> 
>> If a key is added on that topicref, it is associated with that branch of
>> the map. The topicsetref element is a specialized topicref that
> references
>> a branch of a map, just like in that example. Specifically, it references
> a
>> topicset element inside of a map:
>> <topicsetref href="othermap.ditamap#topicset-branch"/>
>> 
>> So, it's not an error to have a keys attribute on topicsetref. In short -
>> any specialized topicref still needs to point to something that is valid
>> for topicref. In this case, it's a branch of a map, which is valid for
> both
>> elements. Anything referenced by a topicref can be associated with a
>> key ... so the keys attribute is valid in this case as well.
>> 
>> Robert D Anderson
>> IBM Authoring Tools Development
>> Chief Architect, DITA Open Toolkit
>> 
>> 
>> 
>> From:   Tarun Garg <tarung@adobe.com>
>> To:   "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
>> Date:   07/28/2010 07:28 AM
>> Subject:   [dita] @keys in <topicsetref>
>> 
>> 
>> 
>> <topicsetref> points to a <topicset> element in a DITA Map. As per my
>> understanding, a key identifies/points to a Map/Topic. So, if a key is
>> defined on <topicsetref> (using @keys) what shall it refer to?
>> 
>> I think, @keys does not make sense on <topicsetref>, as it points to an
>> element inside a Map (and not to the Map itself). Hence, @keys shall be
>> dropped from <topicsetref>.
>> 
>> Regards,
>> Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com
>> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com



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