Nice to talk
to you again France. The definition I espouse is more or less a clarification of
the one already in the spec. "The <keyword> element identifies a keyword or token, such as
a single value from an enumerated list, the name of a command or parameter, or a
lookup key for a message. e.g. <p>The
<keyword>assert</keyword> pragma statement allows messages to be
passed to the emulator, pre-compiler, etc.."
I DO like
your definition: "an element that identifies terms that define
or are closely related to a topic's content" -- but it sounds close to
the definition of an index entry to me. Or there is the suggestion of a
<searchTerm> element. Would you be able to use index items for these
"keywords"?
I really am
not trying to restrict the meaning of <keyword>. I would just like it to
have a consistent definition for all DITA users and across the DITA spec. The IT
world uses (at least) two definitions and IMO, DITA should pick
one.
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
"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
|