As I mentioned a couple of weeks ago, part of proposal 13004, scoping mechanism for keyrefs, is really about enabling scope-specific variables, which people are trying to do with keyref text replacement, which simply can't work, certainly not as keyref is defined 1.2 and not at all in the general case because key scoping would always be limited to map-defined scopes, which is not sufficient. To address the requirement for "scoped variables" that should satisfy all requirements, including non-map-defined scopes, I have worked up the initial pre-proposal writeup given here. I will add a proposal for this to the 1.3 proposal list. Note that this proposal does not require any architectural changes to DITA--it is entirely defined as specializations of existing types (<data>, <ph>, <text>). I implemented an early version of this idea in DITA for Publishers as a proof of concept, so I could always provide this functionality unilaterally but I think it would be better to have it as part of the base DITA design. Cheers, Eliot Initial proposal text: --------------- DITA Variables Requirements and Possible Implementation Approaches There is a general requirement for "variables" that allow for the parameterization of values used in topics and in topicref metadata where the resolved value needs to reflect the use context of the topic or topicref involved. Common examples include product names, product identifiers, locale- and region-specific values, use-context-specific properties of otherwise generic product components, and so on. The DITA 1.2 key and keyref facility satisfies some of these requirements but not all of them. In addition, the key facility could never satisfy all the requirements. [Additional details to be provided here.] The general requirement is that authors be able to define variables that are scoped such that the "nearest" definition is effective for a given reference to a variable. The general intent is for these variables to behave in the way that variables scopes behave in most programming language, such that the definition within the containing scope nearest to the reference defines the effective value of the variable for that reference. The possible variable scopes must be: * Global to a root map * Scoped to a submap within a map tree * Scoped to a topicref within a topicref tree (scoped to a subtree within a tree of topicrefs) * Scoped to a topic and its directly-contained subtopics * Scoped to a section, bodydiv, or sectiondiv. It must also be possible to define default values for variables that are used when the variable is not defined in a higher scope. For example, allowing variable references to specify a default value that is overridden by any explicit definition of the variable. It should be possible to refer to variable definitions in higher scopes. ----------------------- General Design Proposal The general design proposed here uses metadata elements within <topicmeta> to define variables and elements in content or metadata refer to variables by name. Variable definitions specialize from <data>. Variable references specialize from <text> or <ph> as required (but note that the 1.3 proposal to allow <text> in all contexts allows variable references to specialize from <text> if that otherwise satisfies requirements. The effect of resolving a variable is analogous to conref in that the content of the variable-defining element is processed as though it occurred at the point of reference. Variable definitions occur within <topicmeta>, <prolog>, <section>, <bodydiv>, or <sectiondiv>. The parent map, topicref, topic, section, bodydiv, or sectiondiv establishes the scope for the variable binding. Each scope establishes a new variable name space. Within a given scope, the first definition in document order of a given variable name takes precedence over any later definitions of the same name in the same scope. Descendant scopes do not affect the definition of variables defined directly within a given scope. For a given variable reference, the nearest ancestor scope defines the effective value of the variable. Note: For example, if a topicref to a topic defines a variable and the referenced topic also defines the same variable, a reference to the variable within the topic gets the value defined in the topic, not the value defined in the topicref (unless the variable defined in the topic is defined as a fallback variable). ------------------- Variable definition Variable definitions bind variable names to variable values within their containing scope. Example: ------------ <variableDefinition id="var-def-01"> <variableName>productName</variableName> <variableValue><tm>My Product Name</tm></variableValue> </variableDefinition> ------------ <variableDefinition> Contains the binding of a variable name to a variable value. The @id attribute has no special meaning for variable definitions. It simply allows normal content reference of variable definitions. Content model: (variableName, variableValue+, variableIsFallback?) Specialization ancestry: topic/data Multiple <variableValue> elements are intended to allow different values with different conditions. If two or more values are filtered in then the first in document order is used as the effective value of the variable. <variableName> Defines the variable name. Variable names are case-sensitive. Variable name matching is done with all whitespace normalized as for the XPath normalize-space() function. Content model: (#PCDATA)* Specialization ancestry: topic/data <variableValue> Defines the value of the variable. Content model: (%ph.cnt;)* NOTE: The intent is that variables should allow essentially any inline elements. However, it may not be possible to allow this level of flexibility in DITA 1.3 due to limitations in where <ph> can occur. Specialization ancestry: topic/data <variableIsFallback> When this element is present, the variable definition acts as a fallback or default definition such that the value is used only if the variable is not defined in a higher scope. This allows lower scopes to provide appropriate default values for variables while allowing using contexts to override the default. Content model: EMPTY Specialization ancestry: topic/data Variable reference Variable references establish a use of the named variable at the point of reference such that the reflected value is the value defined in the nearest scope relative to the variable reference. Example: ---------- <p>The <variableRef>productName</variableRef> product does everything. ---------- <variableRef> Specifies a reference to a variable by name. If the referenced variable is not defined in any scope then the variable name is presented as the variable value. Processors may issue warning messages when variables cannot be resolved and may present unresolvable variable names in a distinct way so as to visually signal the resolution failure. Content model: (#PCDATA)* The value is a variable name. Variable names are case sensitive. Variable name matching is done with all whitespace normalized as for the XPath normalize-space() function. Specialization ancestry: topic/ph --------------------------------------- Implementation Complications/Questions * What is the effect of nested variable references? That is, if the content of a variable definition itself contains a variable reference, when is the contained variable reference resolved? My initial thinking is that it would resolved in the context of the reference to the top-level variable, so that the resolved nested variable would reflect the scope that applies to the initial reference, not the scope that applies to the variable definition. * What is the effect of conref of a variable reference? Should the variable be resolved before or after the conref? I can see both behaviors being either expected or required but I think it makes most sense to resolve variables after the conref, rather than before. -- Eliot Kimber Senior Solutions Architect "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368
www.reallysi.com www.rsuitecms.com