[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] @keys in <topicsetref>
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 > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]