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] Keywords in DITA


I think that the semantics of keyword can actually be quite crisp and clear. I would propose: "A keyword is a word from a software language, user interface or other interface. Examples include a programming language class name or menu item text."
 
You correctly stated that it is tricky to come up with a generic example. After some thought I came up with this one:
 
<keywords><keyword>stdio.h</keyword><keyword>string.h</keyword></keywords>
 
But this brings us to the fact that the <keywords> element uses the word "keyword" with a different meaning than they <keyword> element does. I suppose nobody would approve of a name-change this late in the game but this has caused us considerable confusion at Blast Radius. There really are two distinct meanings for the word keyword (a couple of different online dictionaries agree on that fact). DITA goes back and forth between the two definitions.


From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, March 08, 2005 7:14 AM
To: Paul Prescod
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Keywords in DITA


I don't think the current examples are necessarily wrong. The keyword element is not intended just for programming keywords, especially when semantic specializations of keyword are available such as <apiname>.  Given that <keyword> has very little semantics of its own, and given that specializations of it exist for many specific cases, coming up with a generic example that isn't more suited for a specialization is actually pretty hard. Generic search terms from the text do seem reasonable to me, as an example of when to use <keyword> specifically rather than one of its specializations.

Michael Priestley
mpriestl@ca.ibm.com
Dept PRG IBM Canada  phone: 416-915-8262
Toronto Information Development



"Paul Prescod" <paul.prescod@blastradius.com>

03/08/2005 08:02 AM

To
Michael Priestley/Toronto/IBM@IBMCA
cc
<dita@lists.oasis-open.org>
Subject
RE: [dita] Keywords in DITA





Thank you. Your description clarifies things. This is what I would have thought except were it not for the example in the specification under "keywords".
 

The following example is metadata from an installation task:

<prolog><keywords> <keyword>installing</keyword> <keyword>uninstalling</keyword> <keyword>prerequisites</keyword> <keyword>helps</keyword> <keyword>wizards</keyword> </keywords> </prolog>

I would have understood if the example was:

<prolog><keywords> <keyword>class</keyword> <keyword>if</keyword> <keyword>else</keyword> <keyword>elseif</keyword> <keyword>assert</keyword> </keywords> </prolog>

Those are keywords in the sense that you define it in your email.



From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent:
Mon 3/7/2005 7:32 PM
To:
Paul Prescod
Cc:
dita@lists.oasis-open.org
Subject:
Re: [dita] Keywords in DITA



Hi Paul, welcome to the list.


The reason we support keyword in both locations (as well as a bunch of specializations of keywords) is to allow the same range of semantic specificity in both places. For example, <apiname> is a type (specialization) of keyword. If we have an occurrence of an <apiname> in content, we may also want to index it specifically for search, if the occurrence is significant. So we add it to the keyword list for the topic. But just because it is a keyword for the topic doesn't mean it stops being an <apiname>. In both contexts, being able to distinguish <apiname>blue</apiname> from <wintitlel>blue</wintitle> is worthwhile. So we support the same keyword element in both places.


In other words, <apiname> as content and <apiname> as keyword for search are both still <apiname>s, so it doesn't make sense to have a different set of elements just because they are processed differently: their containment context (body or prolog)  is enough, and allows us to infer processing behavior without undermining the common semantics.


Michael Priestley
mpriestl@ca.ibm.com



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