"Variables" Proposal

[Eliot Kimber <ekimber@reallysi.com>]

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