Re: [dita] TractorX Example

[Eliot Kimber <ekimber@rsicms.com>]

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/