OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-comment message

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


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/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 <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]