RE: [dita] @keys in <topicsetref>

[Tarun Garg <tarung@adobe.com>]

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

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 <keywords> above):
>    "submap-01.ditamap#tr-01_keywords"

With the 1.0 and 1.1 specification, these are valid targets for a topicref.
With the latest 1.2 specification, a key may be associated with these
because a key can be associated with any topicref target.

> Now, suppose if we allow the key to be bound to a map only and never
> to an element (topicref/non-topicref) inside the map; the key-
> referencing shall happen as follows:
>
> <topicref key="submap-01" href="submap-01.ditamap" format="ditamap"/>
>
> Now,
> KEY Reference to topicref:
>    "submap-01/tr-01"
> KEY Reference to elements other than topicrefs (say <keywords> above):
>    "submap-01/tr-01_keywords"

If I understand your suggestion, this means that we should add a limitation
that keys cannot be associated with elements inside a map - that keys can
only be associated with a map (such as file.ditamap or
file.ditamap#MapElementId).

I think this change would cause a several problems:
   It would mean that keys are valid on some topicref elements and not on
   others, depending only on the target. It means adding @keys to a valid
   topicref (such as some.ditamap#branch) would be invalid; I think this
   would be pretty confusing.
   It removes the simple equation of one key value being equivalent to any
   valid topicref target.
   Applications have already begun to use the map#elementid syntax with
   keys, so we should avoid changing it without a strong reason.

> But, that brings us to another thing. A key can be bound to any
> resource that a topicref can refer to:
> 1) Topic File.
> 2) Topic element inside a Topic File.
> 3) Map File
> 4) Topicref element inside a Map File.
> 5) non-DITA resource.
> So, does that mean (4) becomes an exception for this ?

For (2), I think you're saying you can refer to any <topic> level element,
rather than sub-topic elements like <ph>, which is correct. Currently (4)
is not an exception - these are all valid targets of a topicref, and they
are all valid for a key association. If we limit keys as I think you
suggested above, then #4 would be an exception. I think this would be
confusing.

> Also, since there is a difference in the way referencing to topic
> elements & map elements is done.
>
> For Topic, it is - File#UniqueId/Id (Or File#Topic-id/Element-id)
> For Map, it is - File#Id  (Or File#Element-id)
>
> For key-referencing,
> - In case of Topics "File#UniqueId", part gets replaced with "key-
> name" and "/Id" part is intact.
> - In case of maps, "File#", part gets replaced with the "key-name/"
> and the "Id" part is intact.

I am not certain I understand all of this.

Today, a topicref may be associated with a topic, but not with a sub-topic
level element. In that case, the key represents the topic. The /element
syntax in a keyref attribute is an optional way to refer to an element
within that topic - the key itself *always* refers to the topic itself.

A topicref may also be associated with any element within a map. In that
case, the key represents that element. There is no slash.

In both cases, a valid target in the topicref is exactly equivalent to the
key.

> This could be one of the ways for visualizing keys for someone used
> to using URI referencing. That brings another question to my mind -
> Why can't we have similar format for referencing elements in map
> (same as for topics) ? (I am not sure if this has been discussed
> earlier; as this is not specific to v1.2)
> Although map-id is not needed for referencing elements inside a map,
> I see no harm in adding it to the referencing format, for ensuring
> consistency. Considering this:
> For Topic, it would be - File#UniqueId/Id (Or File#Topic-id/Element-id)
> For Map, it would be - File#UniqueId/Id (Or File#Map-id/Element-id)

I think this is not something we can consider for 1.2, for a two major
reasons:
* It is a very significant change in addressing over previous releases, and
it is too late at this point to consider such a modification
* To preserve backwards compatibility, we have to maintain the old format,
so applications would be required to support two ways to address every DITA
map element.

In addition, the topic/element syntax can always be understood because
topics require an ID, while maps do not require the ID (and cannot without
breaking backwards compatibility). Existing maps would have to be
retrofitted with an ID in order to allow for this type of reference.

> It will help in bringing consistency at two places:
> a) The URI format for referencing MAP elements & TOPIC elements
> b) The KEYREF format for referencing MAP elements. Considering this,
> for both maps & topics the "key-name" shall replace the
> "File#UniqueId" part of the URI and both will have "/Id" part intact.

While it allows for consistency in addressing elements within a map and a
topic, it also allows for inconsistency because any map element can be
referenced in two ways.

I do think this is a valid thing to look at for DITA 2.0, when we have the
ability to make backwards incompatible changes, but until then I think
maintaining the current design is consistent with other map addressing and
with the previous releases.

Does that make sense?

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

Tarun Garg <tarung@adobe.com> wrote on 08/27/2010 02:05:14 AM:

> From: Tarun Garg <tarung@adobe.com>
> To: Eliot Kimber <ekimber@reallysi.com>
> Cc: dita <dita@lists.oasis-open.org>, "dita-comment@lists.oasis-
> open.org" <dita-comment@lists.oasis-open.org>, Robert D Anderson/
> Rochester/IBM@IBMUS
> Date: 08/27/2010 02:06 AM
> Subject: RE: [dita] @keys in <topicsetref>
>
> 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):
>
> <topicref id="tr-01" keys="topicref-01">
>     <topicmeta>
>       <keywords id="tr-01_keywords"/>
>     </topicmeta>
> </topicref>
>
>
> URI Reference to topicref:
>    "submap-01.ditamap#tr-01"
> URI Reference to elements other than topicrefs (say <keywords> above):
>    "submap-01.ditamap#tr-01_keywords"
>
> Now, suppose if we allow the key to be bound to a map only and never
> to an element (topicref/non-topicref) inside the map; the key-
> referencing shall happen as follows:
>
> <topicref key="submap-01" href="submap-01.ditamap" format="ditamap"/>
>
> Now,
> KEY Reference to topicref:
>    "submap-01/tr-01"
> KEY Reference to elements other than topicrefs (say <keywords> above):
>    "submap-01/tr-01_keywords"
>
> Hence, there is no difference in how you refer to a topicref element
> and a non-topicref element inside a map. The only difference is the
> mechanism you choose - URI or KEY. Once, the mechanism is decided,
> there is no discrimination.
>
> But, that brings us to another thing. A key can be bound to any
> resource that a topicref can refer to:
> 1) Topic File.
> 2) Topic element inside a Topic File.
> 3) Map File
> 4) Topicref element inside a Map File.
> 5) non-DITA resource.
> So, does that mean (4) becomes an exception for this ?
>
> Also, since there is a difference in the way referencing to topic
> elements & map elements is done.
>
> For Topic, it is - File#UniqueId/Id (Or File#Topic-id/Element-id)
> For Map, it is - File#Id  (Or File#Element-id)
>
> For key-referencing,
> - In case of Topics "File#UniqueId", part gets replaced with "key-
> name" and "/Id" part is intact.
> - In case of maps, "File#", part gets replaced with the "key-name/"
> and the "Id" part is intact.
>
> This could be one of the ways for visualizing keys for someone used
> to using URI referencing. That brings another question to my mind -
> Why can't we have similar format for referencing elements in map
> (same as for topics) ? (I am not sure if this has been discussed
> earlier; as this is not specific to v1.2)
> Although map-id is not needed for referencing elements inside a map,
> I see no harm in adding it to the referencing format, for ensuring
> consistency. Considering this:
> For Topic, it would be - File#UniqueId/Id (Or File#Topic-id/Element-id)
> For Map, it would be - File#UniqueId/Id (Or File#Map-id/Element-id)
>
> It will help in bringing consistency at two places:
> a) The URI format for referencing MAP elements & TOPIC elements
> b) The KEYREF format for referencing MAP elements. Considering this,
> for both maps & topics the "key-name" shall replace the
> "File#UniqueId" part of the URI and both will have "/Id" part intact.
>
> Regards,
> Tarun Garg | Adobe Systems | +91-120-2444711 | tarung@adobe.com
>
>
> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Wednesday, August 25, 2010 9:15 PM
> To: Robert D Anderson; Tarun Garg
> Cc: dita; dita-comment@lists.oasis-open.org
> Subject: Re: [dita] @keys in <topicsetref>
>
> 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):
>
> <topicref id="tr-01" keys="topicref-01">
>  <topicmeta>
>   <keywords id="tr-01_keywords"/>
>  </topicmeta>
> </topicref>
>
> 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:
>
> <topicref>
>  <topicmeta>
>   <keywords conref="submap-01.ditamap#tr-01_keywords"/>
>  </topicmeta>
> </topicref>
>
> - 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.
>
> Cheers,
>
> Eliot
>
>
> 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:
> >
>
http://www.oasis-open.org/committees/download.php/26493/IssueNumber1207v8b.htm

> >
> l
> >
> > 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
> >>
>
> --
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 512.554.9368
> www.reallysi.com
> www.rsuitecms.com
>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>