[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]