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

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

        "The name of the song is called 'Haddocks' Eyes.'"
        "Oh, that's the name of the song, is it?" Alice said, 
        trying to feel interested.
        "No, you don't understand," the Knight said, looking 
        a little vexed. "That's what the name is called. 
        The name really is 'The Aged Aged Man.'"
        "Then I ought to have said 'That's what the song is 
        called'?" Alice corrected herself.
        "No, you oughtn't: that's quite another thing! 
        The song is called 'Ways And Means': but that's only 
        what it's called, you know!"
        "Well, what is the song, then?" said Alice, who was 
        by this time completely bewildered.
        "I was coming to that," the Knight said. "The song 
        really is 'A-sitting On A Gate': and the tune's my 
        own invention."
                -- Lewis Carroll, Through The Looking Glass

We're stumbling over the use-mention distinction. (1) Generally, the name of a thing is not the thing itself. Accordingly, a key name is the name of a key, and we can talk of "a key" generically without identifying any particular key by name. (2) A requirement to substitute "key name" in place of "key" stipulates that in this aspect of DITA nomenclature the name is in fact the thing named, and "key" is just a less explicit and careful way of saying "key name".

For example, in <topicref keys="water" href="waterbirds.dita"/>

(1) We see the definition of a key, the name of which is "water", and the value (or reference) of which is "waterbirds.dita". The key, then, is the bound combination of name and value.

Or

(2) We see the definition of the key name "water" with the given value or reference, and we should strictly speaking refer to it as a key name, not as a key.

        /Bruce


> -----Original Message-----
> From: Bruce Nevin (bnevin) 
> Sent: Wednesday, November 04, 2009 1:14 PM
> To: ekimber; Michael Priestley
> Cc: dita; Ogden, Jeff
> Subject: RE: [dita] FW: Why "Key name"?
> 
> The quoted example uses both "key name" and "key". It uses 
> "key name" only when talking of the details of a key value; 
> then it reverts immediately to "key". The fact that no one 
> noticed this may be evidence that the distinction is 
> relatively unimportant, and that doing without it is 
> transparent to the reader. 
> 
> > -----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>
> > 
> > 
> > 
> ---------------------------------------------------------------------
> > 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 
> 
>