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.
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
|