RE: [dita] FW: Why "Key name"?

["Ogden, Jeff" <jogden@ptc.com>]

I don't think that that distinction between "key" and "key name" matters to us very much and so we should use one or the other and not both.  

I happen to prefer "key name" over "key". I just think that "key name" reads a little better when we are also using the phrases "key reference" and "key definition".  Having "key" by itself can be somewhat confusing, because it makes it seem like a "key" and a "key name" are two different things. And while they might be two different things in some strict sense, I don't see that difference as being helpful as we use the terms in the DITA 1.2 spec.

    -Jeff

> -----Original Message-----
> From: ekimber [mailto:ekimber@reallysi.com]
> Sent: Wednesday, November 04, 2009 12:18 PM
> To: Michael Priestley
> Cc: dita; Ogden, Jeff
> Subject: Re: [dita] FW: Why "Key name"?
> 
> On 11/4/09 10:34 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:
> 
> > I'm not sure I see the need either. "Key" and "key reference" are
> parallel
> > to "ID" and "ID reference", as Eliot points out. And that's
> sufficient for
> > the majority of cases, where the keyref is to a simple key, not a
> compound
> > value. So I don't think the problem case is all that big.
> >
> > I'm also not sure how, even if there is a problem, adding "name"
> helps.
> > Maybe we could see an example of a problem sentence, written both
> ways?
> 
> I just noticed that the 2nd review draft does have this language in the
> Langref topic on Using keys and keyref:
> 
> " A key value consists of one or more space separated key names. The
> following characters are prohibited in key names: ³{³, ³}², ³[³, ³]²,
> ³/²,
> ³#², ³?², and space characters. The case of key names is significant. A
> key
> may not resolve to sub-topic elements, although a keyref attribute may
> do so
> by combining a key with a sub-topic element id."
> 
> One problem with this particular paragraph is that the phrase "A key
> value
> consists of" should in fact be "The value of the @keys attribute
> consists
> of".
> 
> However, even after making that change, it is still useful, at least in
> the
> context of this paragraph, to use "key name" rather than unqualified
> "key",
> otherwise you get this:
> 
> The value of the @keys attribute consists of one or more space
> separated
> keys. The following characters are prohibited in keys: ³{³, ³}², ³[³,
> ³]²,
> ³/², ³#², ³?², and space characters. The case of keys is significant. A
> key
> may not resolve to sub-topic elements, although a keyref attribute may
> do so
> by combining a key with a sub-topic element id.
> 
> Note the potential confusion between the plural of "key" and mentions
> of the
> @keys attribute.
> 
> I'm not sure that means we should use "key name" in place of "key"
> throughout, but this is a case where "key name" helps.
> 
> Cheers,
> 
> E.
> 
> ----
> Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
> email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
> office: 610.631.6770 | cell: 512.554.9368
> 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
> www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
> <http://blog.reallysi.com> | www.rsuitecms.com
> <http://www.rsuitecms.com>