[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Proposal 13088: Variable Facility
I wasn't around for the initial design around keys, so forgive my ignorance. If text specified via key definition was never meant to be used as a variable text mechanism, then why does @keyref appear on non-linking elements? I know you can use it to turn non-linking elements into linking elements, but I don't understand the real-world use case behind that capability. My main concern is that in DITA 1.2, you can use keyrefs to do something that looks an awful lot like what Eliot describes, albeit with some critical limitations, namely (paraphrasing Eliot): 1. Key definitions have root-map scope, so you cannot have the same topic behave differently at different locations in the map structure. 2. You cannot specify fallback text for key references directly in the topic (though I'll note that you *can* specify fallback href, scope, and format attributes for linking elements). 3. You cannot specify key definitions within a topic, which is problematic for content included via conref within that topic. Rather than come up with a completely new feature for inserting variable text into topics (a third, by my count, after text-by-keyref and conkeyref), I propose we plug these holes in keyref instead. My proposal 13004 will address #1. We'd have to do something else for #2 and #3. But I'd prefer that we enhance an existing almost-there feature rather than invent something new out of whole cloth. Chris -----Original Message----- From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Eliot Kimber Sent: Thursday, October 20, 2011 6:20 PM To: dita Subject: [dita] Proposal 13088: Variable Facility The write up linked from the issue table ( http://lists.oasis-open.org/archives/dita/201107/msg00002.html) includes my formal proposal, but I wanted to discuss it a bit less formally. My motivation for the proposal is the observation that there is a strongly-expressed and well-established requirement for being able to "parameterize" topics such that the rendered topic reflects values that are specific to a given use of the topic within a map, such that two uses of the same topic may reflect different values. A key use case is being able to conref in content and variables in the referenced content reflect values specific to the context of the using topic. For example, I may want a generic task to reflect different product details within a multi-product publication. There is no way to do this with keys: 1. As currently defined, key bindings are root-map-global, so you cannot have different resolved values for the same key within a single publication (meaning a single root map processed as a single processing instance). 2. There is no way to have a "fallback" value for a key defined within a topic so that a reference will always have a value but the value can be overridden by a definition within the using map. You can define default key bindings within a map, but not within a topic. 3. The variable scope needs to be to any of: - Root map - Submap - Topicref - Parent topic - Substructure within a topic body (this last is less compelling, but having it doesn't really change the implementation complexity). Even if we define a way to have scoped key bindings within a map, it will not address point 2 at all or point 3 complete (non-map-related contexts). The text replacement feature of keys was always intended primarily as a way to get link text for elements that are or become links because of a key reference. It was never intended or capable of being a more general "variable" or parameterization facility. I feel strongly that we need a separate parameterization facility that provides the specific features authors need and is a better match to the way people both expect such a feature to work and need it to work. When authoring a topic, it makes sense to define a "variable" in the topic prolog, set an appropriate default value there, reference that variable from within the topic content, and then know that you can set values higher up in the map or topic tree if you need to. With keys, even where a variable would have a natural default, a topic author must still create a key definition and integrate it with all relevant maps simply to provide *any* value for the variable. That seems like a deal breaker to me. The variable mechanism puts the primarily definition of variables *and their meaning* in the topic. Coordination between variables in topics and their definitions in maps is only required when the topic is re-used in multiple contexts. If the purpose of the topic-defined variable is simply to supply values to conreffed content, then the topic author never has to worry about maps at all. Even with map-scoped key definitions, this could not be the case for key-based text replacement. This model is consistent with the way variables work in most programming languages, where you have nested binding contexts, with the *nearest* binding being the effective one for a particular reference to the variable. This is how people expect keys to work and are very surprised when they don't work that way, as is evident from many discussions on the DITA User list. The failure is not in user's expectations but in the misapplication of keys and the lack of a separate variable feature that works as users expect and need. From an implementation standpoint, variable resolution can be, in fact must be, fairly late bound, meaning done after all conref resolution and filtering has been applied. Markup for a variable mechanism can be built as specializations of existing elements, e.g., <data> for variable definitions and <ph> or <text> for variable references. That means the facility does not require any new architectural features in order to be defined and implemented. I have implemented a simple, experimental example of the variable mechanism in the DITA for Publishers vocabulary and Toolkit plugins. The D4P design works but doesn't reflect the full depth of thought that a complete solution would require. But it proves that such a feature is relatively easy to define and implement using normal XML processing tools (e.g., XSLT). In almost every techdoc vocabulary I've designed and implemented over the years I've always had some sort of "variable" mechanism because you simply have to have one. The fact that DITA never has had one is a bit surprising actually, because it's really a hard requirement for production technical documentation when re-use is involved. Cheers, Eliot -- 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]