Proposal 13088: Variable Facility

[Eliot Kimber <ekimber@reallysi.com>]

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