Re: [dita] Keywords in DITA

[Michael Priestley <mpriestl@ca.ibm.com>]

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

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

03/07/2005 08:28 PM

To	<dita@lists.oasis-open.org>
cc
Subject	[dita] Keywords in DITA

In computer science there are two meanings for the
word "Keyword". One
is, as Docbook puts it, "a term describing the content of a document.
The keyword applies to the document component that contains it. Keywords
are rarely displayed to a reader. Usually, they are reserved for
searching and retrieval purposes." FOLDOC[1] says: "A small set
of words
designed to convey the subject of a technical article." So the DITA
Language Reference examples of "installing", "uninstalling",
"wizards",
etc. seems to suggest this usage.

Then there are keywords in computer languages and command lines. In
other words: "A single value from an enumerated list, the name of
a
command or parameter, or a lookup key for a message" FOLDOC[1] says:
"One of a fixed set of symbols built into the syntax of a language.
Typical keywords would be if, then, else, print, goto, while, switch."
The DITA Language Reference example of "<p>The <keyword>assert</keyword>
pragma statement allows messages to be passed to the emulator,
pre-compiler, etc..." seems to ALSO suggest this usage.

I infer from the examples in the DITA specification that I should use
keyword in the FIRST sense if it occurs within the "keywords"
element
and in the SECOND sense if it occurs in document content. Is that
correct? If so, I feel that it is somewhat of a confusing combination.
 ----
 Paul Prescod
 Blast Radius XMetaL