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] Question: Definition of "undefined key"


Hi Bruce,

Consider case #2 from below: If the topic1.dita file does not contain an
element with id="para1", does the xref have an undefined key?
Assuming topc1.dita can be found, the key is resolvable. However, the
keyref is not resolvable, because the keyref points to a key *and an
element ID*. 

Su-Laine

-----Original Message-----
From: Bruce Nevin (bnevin) [mailto:bnevin@cisco.com] 
Sent: Friday, April 29, 2011 3:47 PM
To: Su-Laine Yeo; dita
Subject: RE: [dita] Question: Definition of "undefined key"

I like it. In some sense they're equivalent, but it's a shorter
cognitive route to understand your definition. My paraphrase of Eliot
requires you to remember how a key name is bound to a resource; yours
doesn't.

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

You're saying that there's more than one reason for failure to resolve a
key reference.  

The reason a key name is unresolvable is because the resource it's bound
to can't be found.

One reason a keyref is unresolvable is because the resource to which it
refers can't be found--in other words, because it depends on a key name
that is unresolvable.

What's the other reason a keyref is unresolvable? In other words, how is
the keyref unresolvable when the key name that it uses is resolvable?

Presumably that would apply to any key reference (@keyref or
@conkeyref).

	/B

> -----Original Message-----
> From: Su-Laine Yeo [mailto:su-laine.yeo@justsystems.com] 
> Sent: Friday, April 29, 2011 6:00 PM
> To: dita
> Subject: RE: [dita] Question: Definition of "undefined key"
> 
> 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
> > 
> > 
> 
> ---------------------------------------------------------------------
> 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 
> 
> 


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