Description of <keyword> in 1.1 language spec

[Deborah_Pickett@moldflow.com]

Quoting from the 1.1 language 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, product name, or a lookup key for a message.

"Keyword" means any text that
has a unique or key-like value. For example, a product name. Where there
is a element that has a better meaning for what you are describing, use
that element. The keyword element is a generic element; use it when no
other element applies. The keyword element can also be used to contain
reusable text.
Specific markup recommendations:

    * Use apiname for API
names and cmdname for command names.
    * Term should be used
for inline paragraph definitions; to indicate what you're defining.
    * PH should be used for
general phrases; when you think that keyword is not appropriate.
    * Inside syntax diagrams
and syntax phrases, use kwd to indicate a programming keyword.
    * In metadata, a keyword
is used to create additional XHTML metadata.

Specialized elements derived from <keyword>
may also have extended processing, such as different formatting or automatic
indexing.

When DITA topics are output to XHTML,
any <keyword> or <indexterm> elements in the <keywords>
metadata element are placed in the Web page metadata. In addition, any
index terms in this context are also used for supported index processing
(for example, for print versions).

-----

It seems that this description is outdated
and that <keyword> isn't only used like that.

Specifically:

- "Keyword" means any text
that has a unique or key-like value.
There are plenty of non-keylike uses
of <keyword>, where the value is not unique.  In examples I've
seen, <keyword> is used as a marker that the contents have a meaning
that is beyond the literal content of the text, almost as a weaker version
of <q>.  <wintitle> and <cmdname> are examples in
this vein.

- The keyword element is a generic element;
use it when no other element applies.
The preceding text went to the effort
to explain that <keyword> has semantics, so it cannot also be generic.
 It is more generic than its specializations, true, but that's so
of any element.

- The keyword element can also be used
to contain reusable text.
In the light of #12020, <keyword>
isn't the element for this purpose, though re-use of keywords is more important
than for other elements, I agree.

- When DITA topics are output to XHTML[...]
This is about processing, and does not
belong in the language specification.  (Also, given how broad the
use of <keyword> has become, I don't think it's a good idea, but
that's beside the point.)

-- 
Deborah Pickett
Information Architect, Moldflow Corporation, Melbourne
Deborah_Pickett@moldflow.com