OASIS Darwin Information Typing Architecture (DITA) TC

<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

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:

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 

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:

Sounds like a good catch! 

> 

                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                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 

For references to elements within maps there are the following
possibilities:

1. A topicref with an associated keyname may be addressed by that key, e.g.:

Key definition (in map submap-01.ditamap):



Key references: 
  
- From a map that is in the same map tree as submap-01.ditamap):

   

On 8/25/10 10:45 AM, "Eliot Kimber" 

Hi Eliot, 

I agree with you & Robert, that binding a key to a topicref doesn't make much sense. I would suggest we shall streamline the behavior for URI & Key-referencing in this case.

Taking your example again(in map submap-01.ditamap):




URI Reference to topicref:
	"submap-01.ditamap#tr-01"
URI Reference to elements other than topicrefs (say 

Hi Tarun,

There are several points here, so I will try to get them all.

> URI Reference to topicref:
>    "submap-01.ditamap#tr-01"
> URI Reference to elements other than topicrefs (say 

Hi Robert,

As you suggested, let's keep that for DITA 2.0. I think, there is some link, where the proposals for DITA 2.0 are being kept for future discussion.

As of now, a key can point to an element inside the Map. There was a comment from Eliot below that this shall not be allowed for non-topicref elements. I agree with that and we shall put it in the spec.
And with this change, it shall be as follows:
(Please forgive me, if I am getting repetitive; but this will help me understand better)

For a map, a key can refer to:
a) Map File
    key="map" href="submap-01.ditamap"
b) Topicref element inside a map
    key="tr" href="submap-01.ditamap#tr-01"
And nothing else.

For key-based referencing to:
1) Map File : keyref="keyname"
   VALID   - keyref="map"
2) Topicref element : keyref="keyname"
   VALID   - keyref="tr"
   INVALID - keyref="map/tr-01"
3) non-Topicref element : keyref="keyname/element-id"
   VALID   - keyref="tr/elem-01"
   INVALID - keyref="map/elem-01"

Please correct me, if I got it wrong.

Also, please refer to the spec section - " 2.1.3.4.3.2 Using keys to address DITA elements". Under "Syntax", it states:
                (PARA-1)For references to topics, maps, and non-DITA resources, the value of the @keyref attribute is simply a key name: keyref="topic-key".
                (PARA-2)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".

Here, my understanding kind of matches with what is stated in para-2. In para-1, I think "topicref elements inside map" shall also be added. So, it shall look like:
                (PARA-1)For references to topics, maps, topicref elements in maps and non-DITA resources, the value of the @keyref attribute is simply a key name: keyref="topic-key".
                (PARA-2)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 addition, we can mention that - "For references to non-topicref elements within maps, the key used in @keyref shall be pointing to a topicref element within the map."


Regards,
Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com



                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com]
Sent: Saturday, August 28, 2010 1:57 AM
To: Tarun Garg
Cc: dita; dita-comment@lists.oasis-open.org; Eliot Kimber
Subject: RE: [dita] @keys in 

A reference to a key is *never* a reference to the topicref that defines the
key but a reference to the resource *bound to* the topicref that defines the
key.

That is, a reference to a key name is *always* an indirection through the
key-defining topicref. DITA 1.2 provides no way to say "this key reference
is addressing the topicref with this key instead of the resource bound to
the topicref with this key".

A key may be directly bound to the following types of resources:

1. To a topic (the topic directly or indirectly addressed by the
key-defining topicref).

2. To a map (the map directly or indirectly addressed by the key-defining
topicref)

3. To a non-DITA resource (e.g, a graphic directly or indirectly addressed
by the key-defining topicref)

4. To a topicref in the same or a different map, using an URL with a
fragment ID that is the ID value the topicref within the target map, e.g.:

Thanks a lot Eliot & Robert.
From this it is clear that the point-3(in my reply earlier) needs to be corrected as follows:

> For a map, a key can refer to:
> a) Map File
>     key="map" href="submap-01.ditamap"
> b) Topicref element inside a map
>     key="tr" href="submap-01.ditamap#tr-01"
> And nothing else.
>
> For key-based referencing to:
> 1) Map : keyref="keyname"
>    VALID   - keyref="map"
> 2) Topicref element : keyref="keyname"
>    VALID   - keyref="tr"
>    INVALID - keyref="map/tr-01"
> 3) non-Topicref element : keyref="keyname/element-id"
>    INVALID - keyref="tr/elem-01"
>    VALID   - keyref="map/elem-01"

Also, I apologize if my post was confusing in the sense that a key can be bound to the topicref that defines it. Such a reference in the post was actually related to the cases as illustrated in point (b) above.

In my mind, the questions which remain now are that should the spec explicitly say:
(i) A key cannot be bound to a non-topicref element within a map.
(ii) For key based referencing to a non-topicref element, the key used shall be bound to a map. Using a key bound to a topicref element shall not be correct in this case (as explained in point-3 above).

I think this shall be put in the spec to avoid any confusions of this sort.

Regards,
Tarun Garg




                                                

					
                                                    

        
                                                
				
                                                

                                                    
                                                        
                                                        Original Message
                                                
                                                Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com]
Sent: Wednesday, September 01, 2010 10:29 AM
To: Tarun Garg; Robert D Anderson
Cc: dita; dita-comment@lists.oasis-open.org
Subject: Re: [dita] @keys in