OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita] DITA 1.3 Proposal 13004: Scoped Keys


These are all good comments. Some thoughts.

1. There's no requirement that I'm aware of for addressing a key scope.
However, note that the amount of information required to correctly
address a key scope is not just the map URI and the scope name, because
that doesn't specify the ancestor scopes. It's also not sufficient to
provide the root map URI and the scope URI and name, since a sub-map may
appear at multiple locations in a map structure, and in such cases you
can't know the interceding scopes between the root and the scope in
question. In order to properly address a scope, you'd need the full
ancestry of the scope as identified by map URI and scope name (or
topicref ID). So even if scope addressing is desirable, I'm not sure
there's a feasible path starting from the provisions of this proposal.

2. In the example, the order of definitions is incidental. The point is
that the last definition occurs outside of the child scope, and since a
parent scope can't 'see' the definitions in its child scopes, the
relative position of key definitions and child scopes has no bearing on
which is the defining element.

3. If a topic is referenced from multiple scopes, then yes, in a static
'chunked' output there must be multiple renditions of the topic. For a
monolithic output like PDF or simple HTML, each rendering of the topic
should be uniquely parameterized by its context.

4. This one's tricky. By this proposal, there is no mechanism by which
keys defined in lower scopes can prevent being superseded by higher
scopes. I don't think it's a showstopper, as it forces map authors to be
thoughtful in their placement of key definitions, and I don't think
that's a bad thing. But it is a limitation. I believe the second
suggestion, namely, "...define submaps for exactly the use scope and
define the "variable" keydefs
there," is the appropriate one (though with this proposal, you wouldn't
have to use submaps, you could use topicgroups or any other topicref).

One thing I'm considering formally proposing is something I outlined
back when we were talking about variables, namely, the ability to
specify fallback behavior for keys within topic prologue markup. That
would help alleviate some of these concerns, but not all.

5. That's correct, a sub-map is not inherently a key scope per this
proposal, and I don't think it could possibly be and remain
backwards-compatible. In fact, doing so would prevent the best practice
that we recommend to people, namely, managing key definitions in their
own map and referencing it from the top-level publication map. However,
since @keyscope would be part of topicref-atts, you *could* specify it
on a <map> element. Doing so effectively says, "this map does not
contribute key definitions to any parent map that references it."

6. I considered using 'key space scope' or 'key sub-space' instead of
'key scope' in the proposal, but the former is too verbose and the
latter sounds like something from a science fiction story. I do think it
makes sense to come up with good terminology here so we can be
consistent. I think it makes sense to talk about "segmented key spaces,"
for example.

Chris 

-----Original Message-----
From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
Behalf Of Eliot Kimber
Sent: Monday, January 23, 2012 1:38 PM
To: dita
Subject: [dita] DITA 1.3 Proposal 13004: Scoped Keys

Based on my initial reading I'm happy with the proposal as written as
far as
it goes. However, there are a number of cases it doesn't address that I
think need to be worked out.

1. Is there a requirement to enable direct reference to keys within
specific
scopes?

The proposal does not provide such a mechanism. Without it authors would
have to define global keys for any topic or map that needs to be
addressed
across scopes and these keys would need to be different from any scoped
keys
for the same topic or map (in order to avoid overriding the scoped
definition). I don't think that's necessarily a show stopper and may in
fact
be best practice, but I do want to highlight the implication.

The alternative would be to provide a way to include some form of key
scope
identifier or location as part of a key reference, which would require
knowledge of the specific map within which the key scope is defined,
which
largely undoes the value of keys unless the key scope reference itself
can
be done via keys (which I would definitely want). That starts to seem
like a
lot of extra addressing complexity.

The proposal says that key scopes need to have names, which is good, but
they don't have to be globally unique or unique within a map tree, only
within a map document (think that's the only possible rule). That means
that
they cannot be used alone for map scope reference but would have to
qualified with the address of the map document that contains them.

At that point there's no difference between a reference to a map scope
name
and a reference to the scope-defining topicref by ID using existing
addressing methods, that is, either a keyref/id pair or a URI reference
to a
map with a fragment identifier identifying the topicref within the map.

But given that, it could make sense to provide the attributes
@keyscoperef,
@conkeyscoperef, @keyscopekeyref, and @conkeyscopekeyref to allow
explicit
reference to key scopes, directly or by key.

2. The examples show that a global key definition that occurs *after*
scoped
key definitions within the same map takes precedence over the key
definitions in the scope. This means that scopes within a map are
treated as
though they were submaps for the purposes of constructing key spaces.
That's
fine but I point it out because we'll have to highlight this change in
behavior over 1.2. 

3. If a topic is used in two key scopes and is not referenced using
either
@copy-to or @chunk then what happens?

I think the only right answer is that, because of the key scopes, the
processor is obligated to make two copies of the topic in the result,
otherwise it cannot reflect scope-distinct addresses.

Is this interpretation correct?

4. I observe that one effect of this proposal will be to force key
definitions to the lowest maps in map trees in order to avoid
inadvertent
overriding of scoped definitions by higher maps. That is, if I am using
keys
to define "variables" and I want to ensure that I get the correct
definition, meaning the one that applies only in my use scope, I have to
either have full control over the entire map tree in order to ensure
that
the correct definition is applicable for each use context or I have to
define submaps for exactly the use scope and define the "variable"
keydefs
there. 

I think the analysis in the proposal is correct: we can't change the
precedence rules for keys without either seriously disrupting or
seriously
complicating the key mechanism.

This is why I feel that a *separate* mechanism is required for
variables,
one that reverses the precedence rules and that allows topic authors to
define default values for variables within topics (where those defaults
can
be overridden in higher-level topics or in using maps).

5. The proposal doesn't discuss it in detail, but as written, sub map
documents explicitly do not establish new key scopes--you either add a
topicref in the map that establishes a key scope or you have the
topicref to
the map establish the key scope. I think this is correct but I think
this
might surprise some users who already expect submaps to establish new
key
scopes. We would need to explain this detail clearly.

6. Note that with this proposal the distinction between "key space" and
"key
scope" is pretty thin. A key scope as defined in the proposal is a key
space
as meant in DITA 1.2, that is, a distinct namespace of keys that is
disjoint
from any other key space.

The only real difference is that in the case of nested
key-scope-defining
topicrefs, nested key scopes inherit key definitions from their ancestor
scopes, but that really only affects key space construction. It doesn't
affect key resolution against the constructed key space as the proposal
is
clear that a key not defined in a key scope is not addressable from
within
the scope of that key space, which implies that inherited key
definitions
are effectively duplicated in each key scope they apply to. Of course a
processor could implement things less literally, but for the purposes of
understanding the abstraction defined by the proposal, each key scope is
a
completely distinct key space.

The only other difference then is the association of a given key
reference
with its applicable key space at resolution time. Per the proposal,
that's
implicit in the using map structure (just as in DITA 1.2). But since
we've
now established the existence of multiple key spaces within a single map
tree, it makes it easier to think about the utility and details of
explicit
key space addressing, as discussed above.

Cheers,

E.


-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com


---------------------------------------------------------------------
To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]