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] Key scopes and topicsetref

One problem is the description of topicsetref explicitly says "in another map", that is, a topicsetref is a reference to a topic set in another map.

This again raises the question of what the processing relationship of that other map is when the map containing the topicset is not otherwise referenced from the referencing map (which using keys would require, avoiding the issue).

If we're saying that despite the language of the topicsetref element definition about "independent unit" and "dynamic navigation platform" that topicsetref is processed no differently than any topicref that refers to another topicref using @format="ditamap" then I agree that normal processing rules, whatever they are, apply.

It means that if the only reference to the map is a direct-URI reference to the topicref then the processing implications are undefined because there's not enough information in the content as authored to know what the processing context of the target topicref is. Clearly there must be some expectations of what that processing context is for this feature as used within IBM but that doesn't help us here.

So using key references is the only way to have a topicref-to-topicref reference provide sufficient information to enable reliable processing of the result because using keys forces you to establish the root map context of any keys you reference, local or peer.

The only language I can find in the 1.3 spec that indicates the implications of a format="ditamap" reference to topicref is in the description of the @format attribute:

"The linked-to resource is a DITA map. It represents the referenced hierarchy at the current point in the referencing map."

Reading this now I'm not sure what "represents the referenced hierarchy" means but I take it to mean "the hierarchy defined by the referenced topicref is used at the point of reference"

I think there are a bunch of unstated assumptions about what this type of link means that underly both this language and Erik's language for topicsetref that are not obvious.

I think it is still the case that the key scope implications in this case are not obvious from the general rules for keys.



Eliot Kimber, Owner
Contrext, LLC

From: Robert Anderson <robander@us.ibm.com>
Date: Thursday, April 14, 2016 at 10:57 AM
To: Chris Nitchie <chris.nitchie@oberontech.com>
Cc: Eliot Kimber <ekimber@contrext.com>, dita <dita@lists.oasis-open.org>
Subject: Re: [dita] Key scopes and topicsetref

The <topicsetref> element is really nothing more than a specialized topicref that defaults format="ditamap". The expectation is that it will refer to a <topicset> element, though any processing I've encountered would work exactly the same if it referred to any other <topicref>. [This was a commonly used element in IBM when Erik Hennum proposed it for DITA 1.2; it's still used today but most of the tools that explicitly looked for it have disappeared.]

Because it's just a slightly special topicref with a defaulted format="ditamap", <topicsetref> should work the same as it would here:
<topicref href="" format="ditamap" keyscope="topicrefScope"/>

Which could be broadened further to the more familiar case of:
<topicref href="" format="ditamap" keyscope="someScope"/>

I think this means I'm of the same opinion as Chris - how the topicsetref is "resolved" might vary based on what you're doing with it, but all the key scopes and references are determined before that happens.


Robert D. Anderson
DITA-OT lead and Co-editor DITA 1.3 specification,
Digital Services Group

E-mail: robander@us.ibm.com
Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA

Inactive hide details for Chris Nitchie ---04/13/2016 08:09:29 PM---My assumption is that any topicsetref resolution should occChris Nitchie ---04/13/2016 08:09:29 PM---My assumption is that any topicsetref resolution should occur *after* keyref resolution, and the top

From: Chris Nitchie <chris.nitchie@oberontech.com>
To: Eliot Kimber <ekimber@contrext.com>, dita <dita@lists.oasis-open.org>
Date: 04/13/2016 08:09 PM
Subject: Re: [dita] Key scopes and topicsetref
Sent by: <dita@lists.oasis-open.org>

My assumption is that any topicsetref resolution should occur *after* keyref resolution, and the topicsetref functions as a reference to the topicset as contextualized at its location. If that's the case, then whether either or both elements specify @keyscope doesn't matter, because the topicsetref's resolution occurs after all keyrefs have been resolved at both locations.


On 4/13/16, 9:08 PM, "dita@lists.oasis-open.org on behalf of Eliot Kimber" <dita@lists.oasis-open.org on behalf of ekimber@contrext.com> wrote:

>In the case of topicsetref and topicset, the 1.3 did not add any language
>to define what the behavior should be when either or both of the
>topicsetref and topicset specify a value for @keyscope.
>There are four possible cases:
>1. No key scopes. This is the 1.2 case and nothing is changed
>2. Key scope on topicsetref but not on topicset
>3. Key scope on topicset but not on topicsetref
>4. Key scope on both topicsetref and topicset
>In cases (2) and (3) I think the correct behavior can only be that there
>is one effective scope reflecting the scope name specified. While
>topicsetref is defined as a use-by-reference of the topicset I don't think
>just throwing away a keyscope specified on it would ever be
>appropriate--it's not a literal replacement but an application-managed
>relationship between the navigation point in the referencing map and the
>navigation structure defined by the topicset and that definitely argues
>for maintaining the keyscope.
>In case (4) there are four possible behaviors:
>1. The two scope names are merged as for map-to-map references, resulting
>in one key scope with two names.
>2. The topicsetref's scope becomes the parent scope of the topicset's key
>3. The topicsetref's key scope is ignored
>4. The topicset's key scope is ignored
>Option (1) is consistent with the explicit rules for map-to-map references
>and is my preference since it has the least surprise.
>Option (2) is logical but surprising and seems inconsistent with the
>semantic of topicsetref as a use-by-reference.
>Options (3) and (4) are conref-type behaviors and in a real conref would
>be controllable via the -use-conref-target keyword in the attribute value.
>That option is not available here so I think we can discard these options,
>especially since the writeup of topicsetref explicitly says it's not a
>content reference.
>I don't recall ever discussing the implications of key scopes for
>topicsetref. Did we?
>Based on my informal survey on DITA Users it doesn't appear that anyone
>much uses topicsetref.
>But probably good for us to decide what the right answer is or explicitly
>defer a decision to DITA 2.0.
>Eliot Kimber, Owner
>Contrext, LLC
>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:

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