OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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


-----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
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
specific to a given use of the topic within a map, such that two uses of
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
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
(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
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
it doesn't really change the implementation complexity).

Even if we define a way to have scoped key bindings within a map, it
not address point 2 at all or point 3 complete (non-map-related

The text replacement feature of keys was always intended primarily as a
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
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
prolog, set an appropriate default value there, reference that variable
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
have a natural default, a topic author must still create a key
and integrate it with all relevant maps simply to provide *any* value
the variable. That seems like a deal breaker to me.

The variable mechanism puts the primarily definition of variables *and
meaning* in the topic. Coordination between variables in topics and
definitions in maps is only required when the topic is re-used in
contexts. If the purpose of the topic-defined variable is simply to
values to conreffed content, then the topic author never has to worry
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
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

The failure is not in user's expectations but in the misapplication of
and the lack of a separate variable feature that works as users expect

From an implementation standpoint, variable resolution can be, in fact
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
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
in the DITA for Publishers vocabulary and Toolkit plugins. The D4P
works but doesn't reflect the full depth of thought that a complete
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
years I've always had some sort of "variable" mechanism because you
have to have one. The fact that DITA never has had one is a bit
actually, because it's really a hard requirement for production
documentation when re-use is involved.



Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368

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]