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


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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

Subject: Re: [dita] @keys in <topicsetref>

For references to elements within maps there are the following

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">
  <keywords id="tr-01_keywords"/>

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:

  <keywords conref="submap-01.ditamap#tr-01_keywords"/>

- 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.



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:
> 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 " 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

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