|
Paul,
I do not support your proposed definition of a keyword. I find it too
restrictive.
Not
all topics are about software languages or user interfaces. Yet, keywords
are always important to identify the topics' most important terms or
concepts. For example, I am currently documenting a product that aggregates news
content for automated press clipping activities. Some of my keywords are "news",
"articles", "biographies", "press clipping", "news monitoring",
"embargo", etc.
Basically, I think our definition of keyword should be closer
to: "Keyword is an element that identifies terms that define
or are closely related to a topic's content". However, I can see how
keyword could be specialized to become more restrictive and identify only words
from a software language or gui items.
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
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
|