atom feed4 messages in org.oasis-open.lists.dita-chair[dita-comment] RE: [dita] @keys in <t...
FromSent OnAttachments
Robert D AndersonAug 25, 2010 6:48 am 
Eliot KimberAug 25, 2010 8:44 am 
Eliot KimberAug 25, 2010 8:49 am 
Robert D AndersonAug 27, 2010 1:26 pm 
Subject:[dita-comment] RE: [dita] @keys in <topicsetref>
From:Robert D Anderson (roba@us.ibm.com)
Date:Aug 25, 2010 6:48:45 am
List:org.oasis-open.lists.dita-chair

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.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 <tar@adobe.com> wrote on 08/25/2010 06:11:35 AM:

From: Tarun Garg <tar@adobe.com> To: Robert D Anderson/Rochester/IBM@IBMUS Cc: "di@lists.oasis-open.org" <di@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 | tar@adobe.com

-----Original Message----- From: Robert D Anderson [mailto:roba@us.ibm.com] Sent: Tuesday, August 17, 2010 12:29 AM To: Tarun Garg Cc: di@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 <tar@adobe.com> To: "di@lists.oasis-open.org" <di@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 | tar@adobe.com