RE: [dita] TractorX Example

["Chris Nitchie" <chris.nitchie@oberontech.com>]

Eliot,

I think I see your point.
 
There are two (at least, but let's work with two) approaches when applying
key scopes to a map structure:

1. Logical key scope names, reused across multiple maps (e.g. "maintenance",
"support", "specifications", etc.), in a consistent key scope structure.
2. Specific key scope names for specific collections of content (e.g.
"TractorX", "TractorY", "Calculus101", "TheWorksOfShakespeare"), nested
more-or-less arbitrarily, where cross-scope linking is relatively common.

The only thing I'm sure of is that there *will* be both, sometimes within
the same map. With a global key scope namespace, it would be impossible to
combine publications authored with approach 1 into an omnibus map, because
the first instance of a scope name would trump all others (thus kind of
undermining the whole point of confining keys to a scope). But without a
global key scope namespace, it becomes a major challenge to reuse topics
authored with approach 2, because the scope paths will vary from publication
to publication.

Eliot, it sounds like you think case 2 will be more common. I honestly have
no idea, though I have my doubts, and I'm troubled by the implications for
case 1. The whole point of this proposal is to eliminate the global
namespace for key names; it rankles - considerably - to introduce a new
global namespace for key scopes.
 
But I don't have any first-hand experience of situations where cross-scope
linking would be necessary, much less the types of cases you're concerned
about. Either way, explicitly-defined keys can still be cordoned off into
their own scopes without polluting other parts of the map, which is the
primary purpose of the proposal. So I'll take your word for it, but I'd be
curious what other folks think.

Chris

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@rsicms.com] 
Sent: Tuesday, April 09, 2013 4:48 PM
To: Chris Nitchie; dita
Subject: Re: [dita] TractorX Example

For the me issue with having hierarchical scope names is that you could not
have a topic that makes a hierarchical key reference used in two maps that
happen to produce different key scope hierarchies for the same target scope.
That pretty much defeats the purpose of scopes because your only recourse is
to define an invariant key at the root map level, and you don't need scoped
keys for that.

Having a flat space of scope names avoids that problem, allowing you to have
re-usable key references that will work correctly regardless of the scope
hierarchy.

The downside is that you have to manage your scope names so that they are
distinct across all the scopes you expect to use together in a map.

I would expect that if key scopes are used that they would tend to be
defined on a per-map level, since that is the common use case: make each
submap a distinct key space so that I can safely create references *within*
the space and only have to worry about qualifying key references when I want
to reference keys across scopes.

I think of this as the "multiple-product document" use case: you want to
slam maps that are otherwise for independent products into a single root map
for publication purposes. Within each product-specific map you very well
might have subscopes, such as on a per-subsystem basis or on a per-chapter
basis, or similar.

Another common use case would be training content, where you have maps at
the course, module, lesson, and learning object level. Each of those levels
is intended to be reusable and each probably wants to have its own key scope
to enable ease of reuse. In that case I would much rather manage my scope
names to ensure there's no clash rather than have to maintain references to
hierarchies of scopes in order to reference a key in a particular lesson or
learning object.

That is, once you start using submaps for organizing your content, you tend
to use them more and more, meaning a deeper tree of maps, and if you're
using keys you're going to usually want to use key scopes for each map just
to keep things nicely modular (in the same way that topic element IDs are
each in their own ID space).

So I don't see nested key scopes as an edge case but as the *primary* use
case for many users.

Having scope paths worries me a lot because it adds a lot of complexity and
it means that you have to know the key scope context of any target key when
referencing it outside the scope and that context will change as the same
scope-defining map is used in different contexts.

At that point it's hard to see how key scopes offers any value over just
making all your key names globally unique using some naming convention and
do what you have to in master maps to set up the keys appropriately.

I suppose the counter argument would be that if having nested scopes is too
hard then just don't nest your scopes, but that admonition breaks down in
the training case, for example (I have exactly this case in training I'm
developing for the DITA NL conference).

By having only one space of scopes it requires that your scope names are
managed but it also keeps things simpler and makes it possible to reliably
address a key in a given scope regardless of its use context relative to
other scopes.

It also means that you could have re-usable topics with cross-scope
references reliably used in multiple maps because the details of the key
reference would not be dependent on the scope hierarchy of the scope that
defines the key, only the name of the scope.

Cheers,

E.

On 4/9/13 3:06 PM, "Chris Nitchie" <chris.nitchie@oberontech.com> wrote:

> Eliot,
>
> Yes, I think you basically get it. The implications for 
> cross-publication keyrefs you talk about is *exactly* what I had in mind.
>
> I think the key sentence here is, "This behavior makes the key scoping 
> mechanism really just syntactic shorthand for creating 
> otherwise-normal key references." Assuming you meant 'definitions' 
> instead of 'references,' then yes, that, exactly. I've tried to make 
> this proposal as free of "magic" as possible. We're just implicitly 
> defining regular old key names in the parent scope. Once you've 
> figured out the appropriate key space for a given key reference, it's 
> a simple matter of name-matching to find the appropriate definition, just
as it is in DITA 1.2.
>
> In my example, I used "tractor-x" and "tractor-y" to make it obvious 
> where the different tokens were coming from. If you replaced them with
"TractorX"
> and "TractorY", the results would be the same, e.g.
> "TractorX.TractorX.OilChart" instead of "tractor-x.TractorX.OilChart". 
> Note that at no point is there ever a key named "OilChart". That is 
> never a valid key reference, in either the scoped or un-scoped case. I 
> think that's clear, but I wanted to make it explicit. If our 
> hypothetical map author wanted to start using unqualified key 
> references like "OilChart" and "RegularMaintenance", she'd have to 
> change (or add) those key definitions in TractorX.ditamap and
TractorY.ditamap.
>
> Some comments about your A, B, C and D.
>
> A. You say, "Defining *any* scope in a map does not make all key 
> references with dots in them necessarily scope references, only those 
> where the first dot-delimited token within the key reference matches the
name of a scope."
> There's no such thing as a "scope reference." It would be more precise 
> to simply say that all key references are resolved against the keys - 
> explicit and implicit - defined within the key scope encompassing the 
> reference. This proposal suggests changing the process of building 
> and, now, partitioning the key spaces in a map structure. Resolution 
> against those key spaces is exactly the same as it was in 1.2.
>
> B. "The set of key scope names is global and normal key precedence 
> rules determine which instance of a scope name is effective when the 
> same scope name is used more than once." This is the only sentence in 
> your message that's flat-out wrong as the proposal is currently 
> written, but I'm open to further discussion on this point.
>
> Key scope names are scoped to their containing key scope, not globally 
> within the root map. Take this map:
>
> <map>
>
>   <topicgroup keyscope="scope1">
>     <topicgroup keyscope="scope2">
>       <keydef id="A" keys="key"/>
>     </topicgroup>
>   </topicgroup>
>
>   <topicgroup keyscope="scope2">
>     <keydef id="B" keys="key"/>
>   </topicgroup>
>
>   <!-- NOTE: Duplicate Scope Name
>        within parent scope. -->
>   <topicgroup keyscope="scope2">
>     <keydef id="C" keys="key"/>
>     <keydef id="D" keys="key2"/>
>   </topicgroup>
>
> </map>
>
> "root" keyspace
> ---------------
> scope1.scope2.key=A
> scope2.key=B
> scope2.key2=D
> (Note: 'C' is overridden due to normal key precedence rules in the 'root'
> scope, and so is never accessible outside its defining scope.)
>
> "scope1" keyspace
> -----------------
> scope1.scope2.key=A (inherited)
> scope2.key=B (inherited; local implicit definition overruled) 
> scope2.key2=D (inherited)
>
> "scope1.scope2" keyspace
> ------------------------
> scope1.scope2.key=A (inherited)
> scope2.key=B (inherited)
> scope2.key2=D (inherited)
> key=A
>
> "scope2" keyspace (the first one)
> ---------------------------------
> scope1.scope2.key=A (inherited)
> scope2.key=B (inherited)
> scope2.key2=D (inherited)
> key=B
>
> "scope2" keyspace (the second one)
> ----------------------------------
> scope1.scope2.key=A (inherited)
> scope2.key=B (inherited)
> scope2.key2=D (inherited)
> key=C
> key2=D
>
> This is a contrived example, and I would expect situations like this 
> to be rare, but as currently written, that's how it would work. It has 
> the benefit of allowing a map with scopes to be reused in a parent map 
> which cordons it off within its own scope, without fear of name clashes.
>
> C. Item C assumes Item B, so that's wrong too by implication. It 
> suggests, though, that scope paths make working with scopes too 
> difficult. You might be right, but I'm not sure. Like I said, I'm open 
> to discussion. I think one could easily come up with a contrived case 
> that would be baffling to the average user - see above - but I also 
> don't expect such cases to come up often in real-world usage. Key 
> scoping is something of an edge case, and I think multiple levels of 
> scoping will wind up being an edge case within that edge case.
>
> And finally, D: I hadn't thought about that, but yes, I think that 
> logically follows.
>
> Otherwise, this is spot-on.
>
> Chris
>
> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@rsicms.com]
> Sent: Tuesday, April 09, 2013 2:21 PM
> To: Chris Nitchie; dita
> Subject: Re: [dita] TractorX Example
>
> Thanks--I was in the process of working up essentially the same 
> example but you beat me to it. Your analysis is consistent with mine.
>
> The main difference between your example and mine is that I make the 
> original qualification bit the new scope name, that is, the scope 
> would be "TractorX" in your example, not "tractor-x". In that case, 
> what is the binding of the original "TractorX.OilChart" references 
> from within the scope of the Tractor X map? Are they unbound or do 
> they resolve as they did before? Likewise the TractorX.OilChart 
> references from the scope of the Tractor Y scope.
>
> This scenario is based on this line of potential reasoning by a System
> Architect:
>
> "Hey, this scoped keys thing is neat, and look, I've already used dots 
> to qualify my key names, so if I just add the @keyscope declarations, 
> I'll have scoped keys and now I can create multi-product maps with less
effort."
>
> So she adds @keyscope="TractorX" and @keyscope="TractorY" to the 
> maprefs. In that case, her expectation would at a minimum be that the 
> key references within each scope would now be reliably scoped without 
> the root map having to do anything. She also knows that her authors 
> can start eliminating the scope qualifier for in-scope references. 
> Will she be surprised if references to TractorY.OilChart from the 
> TractorX scope will no longer resolve without additional work?
>
> But what other things does she have to realize? I think the list is, 
> per your analysis (and mine):
>
> 1. Cross-scope references have to either be reauthored to add the 
> now-missing scope qualifier or the root map has to declare the 
> original TractorY keys in the global scope in order for the existing 
> references to resolve.
>
> 2. Subtrees that don't explicitly define a scope don't imply a scope.
>
> A few things to be sure we're clear on:
>
> A. Defining *any* scope in a map does not make all key references with 
> dots in them necessarily scope references, only those where the first 
> dot-delimited token within the key reference matches the name of a scope.
> That is, if we view scopes as simply adding dynamically-constructed 
> key names to the set of global key definitions, then the use of scopes 
> doesn't fundamentally change how key resolution works--you're just 
> matching key names to key bindings for those names--there's no magic.
>
> B. The set of key scope names is global and normal key precedence 
> rules determine which instance of a scope name is effective when the 
> same scope name is used more than once. (This allows using maps to 
> completely override scopes if it wants, which I think is the right 
> answer.) This behavior makes the key scoping mechanism really just 
> syntactic shorthand for creating otherwise-normal key references.
>
> C. Because of (B) there is no notion of having a "path" of scopes to 
> get to a given qualified key. All key references are either qualified 
> by a single scope name or not qualified at all. This makes both 
> prediction of the appropriate qualified key reference to use easy (or, 
> arguably, possible in the general case) and also makes it easy for 
> higher-level maps to override keys within scopes.
>
> D. A key definition outside a scope may redirect to a key within a 
> scope, e.g., a global-scope key definition like:
>
> <keydef keys="TractorX.OilChart"
>         keyref="tractorx.TractorX.OilChart"
> />
>
> This means that root maps could restore the original 1.2 behavior for 
> keys that would otherwise need to be scope qualified, as in this case.
>
> I think that satisfies my concerns that existing maps might be 
> irreparably broken by introducing scopes. The fact is that if you want 
> to take advantage of scopes you'll have to rethink your key definition 
> and management practices but it means you'll be able to do something you
can't do today.
>
> We have not yet defined how this mechanism could be extended or 
> defined to also handle cross-deliverable key references (that is, 
> references to peer key spaces).
>
> I think one solution would be to use @keyscope on peer maprefs, e.g.:
>
> <mapref scope="peer"
>         keyscope="publication-02"
>         href="../pub-02/pub-02.ditamap"
> />
>
> That makes the meaning of a reference to "publication-02.foo" clear 
> and consistent with Chris' proposal and avoids the need for any new 
> addressing syntax.
>
> Hmmm.
>
> I will consider this as I try to finish my cross-deliverable demo for 
> next week.
>
> Cheers,
>
> E.,
>
>
> On 4/9/13 11:28 AM, "Chris Nitchie" <chris.nitchie@oberontech.com> wrote:
>
>> I want to try and tease out the hypothetical Eliot brought up during 
>> the TC call today. Imagine, today, you had two DITA maps for 
>> different tractor models, TractorX.ditamap and TractorY.ditamap. 
>> There also exists a third map,  AllTractors.ditamap, that included 
>> both TractorX and TractorY. Because we live in a DITA 1.2 world, 
>> where a given root map has exactly one key space, we¹ve prefixed all 
>> of our keys with their context. This allows one of the TractorY 
>> topics to reference a key
> in the TractorX map.
>>
>> TractorX.ditamap
>> ----------------
>> <map>
>>   <title>Tractor X</title>
>>   <topicref id="x1"
>>             keys="TractorX.OilChart"
>>             href="TractorX/oilChart.dita"/>
>>   <topicref keys="TractorX.RegularMaintenance"
>>             id="x2"
>>             href="TractorX/regularMaintenance.dita"/>
>> </map>
>>
>> TractorY.ditamap
>> ----------------
>> <map>
>>   <title>Tractor Y</title>
>>   <topicref id="y1"
>>             keys="TractorY.OilChart"
>>             href="TractorY/oilChart.dita"/>
>>   <topicref id="y2"
>>             keys="TractorY.RegularMaintenance"
>>             href="TractorY/RegularMaintenance.dita"/>
>> </map>
>>
>> AllTractors.ditamap
>> -----------------------
>> <map>
>>   <title>All Tractors</title>
>>   <mapref href="TractorX.ditamap"/>
>>   <mapref href="TractorY.ditamap"/>
>> </map>
>>
>> TractorY/RegularMaintenance.dita
>> --------------------------------
>> <topic id="topic">
>>   <title>Regular Maintenance</title>
>>   <body>
>>     <p>Refer to <xref keyref="TractorX.RegularMaintenance"/>,
>>        using <xref keyref="TractorY.OilChart"/> for the oil
>>        chart.</p>
>>   </body>
>> </topic>
>>
>> EFFECTIVE KEY SPACE FOR AllTractors.ditamap
>> -------------------------------------------
>> TractorX.OilChart=x1
>> TractorX.RegularMaintenance=x2
>> TractorY.OilChart=y1
>> TractorY.RegularMaintenance=y2
>>
>>
>> So DITA 1.3 comes out with the scoped keys feature as currently 
>> described in 13004. The author of AllTractors.ditamap introduces them 
>> (for reasons I don't quite understand).
>>
>> AllTractors.ditamap with Scopes
>> -------------------------------
>> <map>
>>   <title>All Tractors</title>
>>   <mapref href="TractorX.ditamap"
>>           keyscope="tractor-x"/>
>>   <mapref href="TractorY.ditamap"
>>           keyscope="tractor-y"/>
>> </map>
>>
>> This turns the single key space into three key spaces.
>>
>> ROOT KEY SPACE
>> --------------
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>>
>> TRACTOR X KEY SPACE
>> -------------------
>> (inherited from root)
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>> (scoped key names)
>> TractorX.OilChart=x1
>> TractorX.RegularMaintenance=x2
>>
>> TRACTOR Y KEY SPACE
>> -------------------
>> (inherited from root)
>> tractor-x.TractorX.OilChart=x1
>> tractor-x.TractorX.RegularMaintenance=x2
>> tractor-y.TractorY.OilChart=y1
>> tractor-y.TractorY.RegularMaintenance=y2
>> (scoped key names)
>> TractorY.OilChart=y1
>> TractorY.RegularMaintenance=y2
>>
>>
>> The problem here, as Eliot points out, is that the reference to 
>> TractorX.OilChart from TractorY/RegularMainenance.dita will no longer 
>> resolve, because that key is no longer defined in Tractor Y's key space.
>> However, the reference to TractorY.OilChart will continue to work 
>> just fine, as will any other reference to a TractorY key from within 
>> a TractorY key scope.
>>
>> The author now has a number of ways to fix the problem.
>>
>> * Change the key reference to "tractor-x.TractorX.RegularMaintenance".
>> * Add a new <keydef> to TractorY.ditamap for
> "TractorX.RegularMaintenance".
>> * Add a new <keydef> to AllTractors.ditamap for 
>> "TractorX.RegularMaintenance" (which would override the definition in 
>> the tractor-x scope, but would make the key visible to all child scopes).
>>
>> Chris
>>
>>
>> Chris Nitchie
>> Oberon Technologies, Inc.
>> 2640 Wildwood Trail
>> Saline, MI  48176
>> Main: 734.666.0400 Ext. 503
>> Direct: 734.330.2978
>> Email: chris.nitchie@oberontech.com
>> www.oberontech.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.ph
>> p
>>
>
> --
> Eliot Kimber
> Senior Solutions Architect, RSI Content Solutions "Bringing Strategy, 
> Content, and Technology Together"
> Main: 512.554.9368
> www.rsicms.com
> www.rsuitecms.com
> Book: DITA For Practitioners, from XML Press, 
> http://xmlpress.net/publications/dita/practitioners-1/
>
>
> ---------------------------------------------------------------------
> 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
>
>

--
Eliot Kimber
Senior Solutions Architect, RSI Content Solutions "Bringing Strategy,
Content, and Technology Together"
Main: 512.554.9368
www.rsicms.com
www.rsuitecms.com
Book: DITA For Practitioners, from XML Press,
http://xmlpress.net/publications/dita/practitioners-1/


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