[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]