Re: [dita] @keys in <topicsetref>

[Eliot Kimber <ekimber@reallysi.com>]

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