RE: [dita] Proposal 13088: Variable Facility

["Nitchie, Chris" <cnitchie@ptc.com>]

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