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 understand the argument that keyref is intended to be for referencing,
and whatever facility it has for variable text is an incidental
side-effect. The fact remains that as it is, keyref is very close to
being able to satisfy the same use cases that would be satisfied by a
brand-new variable text mechanism, and I'd prefer to fix the former
rather than invent the latter. Having one feature for variable links
(that can do variable text in a limited way) and another, completely
separate feature for variable text just strikes me as wrong.

<quote>
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.
</quote>

I think the distinction between link text in a link to a null resource
on the one hand, and simple variable text on the other, is going to be
lost on most people, and frankly I think it's meaningless even when
understood. It's a distinction without a difference.

Yes, a non-linking element becomes a link when it has a keyref to a key
definition with an href (though why you wouldn't use a linking element
in the first place in such cases is completely lost on me). But when an
empty non-linking element, like <ph>, refers to a key definition with no
href but which does specify text, the reference will still receive the
text specified by the definition. This makes it functionally, if not
semantically, identical to a variable text feature.

There's an example in the Key Examples section of the 1.2 spec that
shows how to define a non-linking keydef and reference it from a
non-linking keyref for "product-name." If, as Eliot says, "it would be a
misapplication of the key facility" to use it for variable text, why
does the spec highlight how to do it?

I also understand the argument that keyref processing is necessary for
basic dita processing, and variable text resolution could be done
separately, even as late as rendering time. That's a benefit, but not a
compelling enough one to justify the functionality overlap with keyref,
IMHO.

Here are some blue-sky, off the top of my head ideas for how we could
modify keyref to fully support variable text. 
 
1. Add key scopes. My key scoping proposal will cover this in detail,
but basically, you can flag any map or topicref as a "key scope". Keys
defined on or within that scope only apply within that scope. The same
key can be defined differently in different scopes. Keys defined in
"parent" scopes override definitions specified in "child" scopes. Note
that even if we accept a new variable mechanism, I'd argue that this is
necessary just for keyref to be functionally complete. The same argument
for allowing different (dare I say, "varying") variable text definitions
at different locations in the map structure also applies for variable
references.

2. Add a new attribute to keyref-bearing elements, something like
keytext="derive|ignore|derive-if-empty*|-dita-use-conref-target". If
keytext="derive" then the key reference will get its effective text from
the key definition, even if it contains content, thus allowing authors
to specify a fallback. We could also introduce a <ph> specialization
that defaults @keytext to "derive", as a special-purpose element for
variable text.

3. Introduce new markup within <prologue> for specifying key
definitions. It wouldn't be the full <keydef> content model - I don't
think we want to introduce topicrefs into topics - but a simple way to
specify text and/or href/scope/format for key references within the
topic. These definitions would apply to the body of the topic and any
nested topics, and thus apply to content included via conref. They could
be overridden by definitions from the referencing key scope.

Keys are already too complex. That milk's been spilt. Indirection as a
concept is something most normal people struggle with, never mind the
sometimes baroque rules for handling keys as defined in DITA 1.2. We
(PTC) had to split our implementation over two releases (Dave actually
finished text insertion via key just last week, which is why this stuff
is fresh in my mind). We (the DITA TC) have to balance the added
complexity to the already-complex keyref feature against the complexity
of a whole new feature with its own markup, its own processing
implications, and its own interactions with other DITA features. (Can
you have a key reference within a variable definition? Can you have a
variable reference within a key definition? What about conref and
conkeyref? And how would all that work? I think I could figure it all
out, but just asking the questions makes me tired.)

Chris

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com] 
Sent: Friday, October 21, 2011 1:49 PM
To: Nitchie, Chris; dita
Subject: Re: [dita] Proposal 13088: Variable Facility

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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]