Re: [dita] Question: Definition of "undefined key"

[Eliot Kimber <ekimber@reallysi.com>]

Undefined key and undefined key name are synonymous ("undefined key name" is
the more correct construction because we tried to be consistent in the use
of "key name" to make the string value you utter, as distinct from the key
as the binding of the key name to one or more resources.

An undefined key is definitely distinct from an unresolvable key.

An undefined key has no effective binding. That is, there is no topicref
element that is effective (that is, that is not filtered out) that specifies
the key name as a value of its @keys attribute.

A key that is defined but for which the associated resource cannot be
resolved is an unresolvable key.

A key definition that has <topicmeta> that may be used as the key's bound
resource can never be unresolvable.

Note that a key binding may be bound to just a remote resource, just
descendant content of the topicref, or *both*.

One could argue that we need to distinguish the case where a key definition
specifies a remote resource as well as <topicmeta> content and the remote
resource cannot be resolved separate from the case where there is no
<topicmeta> content.

In the second case the implications are clear: there is only one possible
resource and it either can be resolved or it can't.

In the first case you probably want to know that the remote resource
couldn't be resolved and possibly have the system act in a certain way in
that case, even though there is still, technically a (local) resource bound
to the key definition.

For example, I can imagine wanting to have the @href fallback behavior apply
when the remote resource cannot be resolved even when the key definition has
<topicmeta> content.

The spec is definitely silent on that particular issue.

Cheers,

E.

On 4/28/11 1:24 PM, "Su-Laine Yeo" <su-laine.yeo@justsystems.com> wrote:

> Hi everyone,
> 
> I think we're going to need a FAQ item about what the definition of
> "undefined key" is.
> 
> Eliot, after re-reading your response I am not sure if you are saying
> that case 3 would be considered an undefined key. In case 3, obviously
> the keyref can't be resolved, but are you saying that this should be
> treated as it can't be resolved in spite of there being a defined key,
> or are you saying that it should be treated as an undefined key?
> 
> The fourth paragraph in this topic:
> http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_addr
> ess_dita_elements.html implies that "undefined key name" and "key
> reference cannot be resolved to a resource" are distinct cases. I am not
> sure if the spec intends "undefined key" and "undefined key name" to
> mean the same thing.
> 
> I don't have time to take the lead in sorting out this issue. Can anyone
> else volunteer to draft an FAQ item?
> 
> Cheers,
> Su-Laine       
> 
> 
> -----Original Message-----
> From: Su-Laine Yeo
> Sent: Thursday, April 28, 2011 10:53 AM
> To: dita
> Subject: RE: [dita] Question: Definition of "undefined key"
> 
> Thanks Eliot. What if you have:
> 
>  <map>
>  <keydef keys="topic1" href="topic1.dita">
> <topicmeta><keywords><keyword>foo</keyword></keywords></topicmeta>
>  </map>
> 
> Then in case 2 and 3, are the keys still considered undefined? This part
> of the spec:
> http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/overview_of_keys.h
> tml#overview_of_keys seems to say that the key would be considered
> defined because it is bound to topicmeta. Is that the intention?
> 
> Best,
> Su-Laine
> 
> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Wednesday, April 27, 2011 6:13 AM
> To: Su-Laine Yeo; dita
> Subject: Re: [dita] Question: Definition of "undefined key"
> 
> An "undefined" key is a key name for which no binding is effective.
> 
> In the case of the key "topic1", the key is defined but it's resource
> does
> not and there is no other content in the topicref, so there is no
> resource
> bound to the key.
> 
> In that case, the fallback rules for unresolvable keys applies.
> 
> That is, there are three ways that key references can fail to resolve to
> a
> resource:
> 
> 1. There is no effective binding for the key at all.
> 
> 2. There is a binding for the key but the resource to which it is bound
> cannot be accessed.
> 
> 3. Where the key reference includes an element ID component, if the key
> reference can be resolved (that is, the key component of a
> key/element-id
> pair) but the specified element isn't there, then the key reference is
> unresolvable.
> 
> If this isn't clear from the spec as written then we definitely need to
> make
> it clearer because it's fundamental to the key mechanism.
> 
> Cheers,
> 
> E.
> 
> On 4/26/11 3:05 PM, "Su-Laine Yeo" <su-laine.yeo@justsystems.com> wrote:
> 
>> Hi everyone,
>> 
>> One more question on the "Processing key references" topic here:
>> 
> http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_ref
> erence
>> s.html
>> 
> <http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_re
> ferenc
>> es.html>
>> 
>> It says, "If a referencing element contains a key reference with an
> undefined
>> key, it is processed as if there were no key reference".  What does
> "undefined
>> key" mean? For example, say you have:
>> 
>> <map>
>> 
>> <keydef keys="topic1" href="topic1.dita"/>
>> 
>> </map>
>> 
>> <topic>
>> 
>> S
>> 
>> <xref keyref="topic1/para1" href="topic2.dita#topic2/para2"></xref>
>> 
>> S
>> 
>> </topic1>
>> 
>> 
>> Case 1) If the topic1.dita file cannot be found, does the xref have an
>> undefined key?
>> 
>> Case 2) If the topic1.dita file does not contain an element with
> id="para1",
>> does the xref have an undefined key?
>> 
>> If an xref is considered to have an undefined key, the href will be
> used. If
>> it is not considered to have an undefined key, the processor should
> presumably
>> treat it as an error condition.
>> 
>> Su-Laine
>> 
>> Su-Laine Yeo
>> Solutions Consultant
>> 
>> JustSystems Canada, Inc.
>> Office: 1 (778) 327-6356
>> syeo@justsystems.com <mailto:syeo@justsystems.com>
>> 
>> XMetaL Community Forums: http://forums.xmetal.com
>> 
>> For partners only: http://www.justpartnercenter.com
>> 
> 
> --
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 512.554.9368
> www.reallysi.com
> www.rsuitecms.com
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 

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