dita — archive

[Eliot Kimber <chris.nitchie@oberontech.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 > >