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

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

I think Bruce's summary is a good step. However this part doesn't look
right:

>Undefined key name: a key name which is not bound to a resource in an
effective <topicref>. (Also: undefined key.)

Shouldn't this be: 

>Undefined key name: a key name which is not found in the @keys
attribute of any effective <topicref>. (Also: undefined key.)

Also note that an unresolvable keyref can include an resolvable key
name.

Su-Laine


-----Original Message-----
From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com] 
Sent: Thursday, April 28, 2011 2:25 PM
To: Eliot Kimber; Su-Laine Yeo; dita
Subject: RE: [dita] Question: Definition of "undefined key"

Putting that in definitional form:

Key name: the string that is bound to one or more resources in a key
definition. Within the key defining element,it can be bound to any or
all of: the resource specified by a @keyref attribute; the resource
specified by an @href attribute; content of a <topicmeta> element.

Key: the binding of a key name to a resource. The @keys attribute
creates such bindings.

Unresolved key name: a key name that is bound to a resource that cannot
be found. (Also: unresolved key, unresolvable key name, unresolvable
key.) 

Undefined key name: a key name which is not bound to a resource in an
effective <topicref>. (Also: undefined key.)

Effective <topicref>: in a map, a <topicref> element that is not
filtered out. 

"Key defining element" is used here but not defined. Other stuff is more
commentary on the spec than definitional. If a key definition is
associated with <topicmeta> content that may be used as its bound
content, it can never be unresolved. Could talk about the precedence and
other interrelation of the several resources that could be bound to a
key name in a given key definition. That sort of thing.

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Thursday, April 28, 2011 3:08 PM
> To: Su-Laine Yeo; dita
> Subject: Re: [dita] Question: Definition of "undefined key"
> 
> 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_ad
> > dr 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_r
> > ef
> > 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
> 
> 
> ---------------------------------------------------------------------
> 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_workgr
> oups.php 
> 
>