RE: [dita] @keys in <topicsetref>

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

Sounds like a good catch! 

> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com] 
> Sent: Wednesday, August 25, 2010 9:49 AM
> To: Tarun Garg
> Cc: dita@lists.oasis-open.org; dita-comment@lists.oasis-open.org
> Subject: RE: [dita] @keys in <topicsetref>
> 
> 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/IssueN
> umber1207v8b.html
> 
> 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
> >
>