Re: [dita] TractorX Example

[Eliot Kimber <ekimber@rsicms.com>]

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

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