|
We have been following the discussion and have a real-life example to offer. This organization is a long time DITA user that we need to move to keys away from conditional processing. The complexity is stunning.
JoAnn
Sent from my iPhone
JoAnn Hackos
Comtech
Begin forwarded message:
So perhaps a Real life example might help?
Within one document, we have discussions on how to connect power cables to three cabinet types -- the -40V, 24V, and 220V cabinets. We want to write one topic that uses keys to change the power supply and a few isolated steps within the procedure. But
all three topics will appear in the document, so each doc when included in the map needs a unique key scope.
Now we want to put that document into a library of many documents for different product lines. In addition to the unique elements of the three cabinets, these topics also appear in the entire library multiple times based on the product line -- the 3900,
3900A, 3900L -- and each of these products has multiple versions. So in this library the topics need the power supply keys at the individual topic level, but the product and version keys at the book level. Within the library we might have 3 voltage topics
that appear in each of three versions of three different product books. If I understand correctly, to specify keys without hierarchy would mean specifying 27 keys each time the topic was used, instead of being able to specify one key def at the topic level
and two key defs at the book level for each of the nine books.
Now I know we question why this organization structures their library this way, but it is a real-life application of why we need this to work.
Dawn
-----Original Message-----
From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Chris Nitchie
Sent: Tuesday, April 09, 2013 5:34 PM
To: 'Eliot Kimber'; 'dita'
Subject: RE: [dita] TractorX Example
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="">
/>
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="">
<topicref keys="TractorX.RegularMaintenance"
id="x2"
href="">
</map>
TractorY.ditamap
----------------
<map>
<title>Tractor Y</title>
<topicref id="y1"
keys="TractorY.OilChart"
href="">
<topicref id="y2"
keys="TractorY.RegularMaintenance"
href="">
</map>
AllTractors.ditamap
-----------------------
<map>
<title>All Tractors</title>
<mapref href="">
<mapref href="">
</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="">
keyscope="tractor-x"/>
<mapref href="">
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
---------------------------------------------------------------------
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
|