Re: [dita] Proposal 13088: Variable Facility

[Eliot Kimber <ekimber@reallysi.com>]

Non-link elements *become links* when you use keyref on them.

The way I like to think of it is, when a key definition is not bound to a
remote resource (has no @href value) then it binds to a "null resource".

Thinking about it that way, the replacement text is always the link text to
a (possibly-null) resource.

That helps to avoid thinking that keys are about text replacement.

I would object in the strongest possible terms to any attempt to make keys
into a more general variable mechanism as I have described it. It would be a
misapplication of the key facility and would make it much more complicated
than it already is.

I strongly suspect that any attempt we make to do even scoped keys will fail
due to complexity arguments. I hope not, but it would not surprise me.

One advantage of a separate variable facility is that it is separate,
meaning its complexity is contained to itself and it can be used or not,
implemented or not, without affecting anything else.

Trying to extend the key facility would make an already complex facility
much more complex and risk causing vendors to either not implement it at all
or not implement it completely.

Keys are about *addressing* and addressing is necessarily both complicated
and involved in the most fundamental aspects of DITA processing, meaning,
for example, that both authoring tools and content management systems, in
addition to output processors, must implement it in a fairly deep and
tightly-integrated way, because those processors are mostly about managing
addresses and knowledge of dependencies among resources.

A separate variable mechanism is *not* about addressing, its about semantic
processing of the data *once all the addresses have been resolved and base
processing has been applied*.

Variables are fundamentally a rendering-time concern, not a base processing
concern. That allows it to be kept separate from the the fundamental
DITA-awareness that CMS and editing tools must have.

For example, consider this form of variable reference:

<p>The <varref id="prodname">My Product</varref> is great.</p>

Even if *no* processing is implemented for the variable facility, the topic
is still processed and rendered in a useful way. Not so with keys.

Of course, editing tools will be well served to implement support for a
separate variable mechanism, but it won't be required simply to enable
*authoring*, whereas key handling is now a cost of entry.

I point again to my sample implementation in the DITA for Publishers
code--the implementation was easy and generic and could easily be adapted to
any of the current DITA-aware authoring tools that provide appropriate
extension facilities (e.g., Arbortext Editor, XMetal, OxygenXML, etc.).

Cheers,

E.


On 10/21/11 10:13 AM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> 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
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com