RE: [dita] Proposed revision for the keyword definition (was Keyw ords inDITA)

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

For comparison/voting, here's what's
in the draft of the spec I'm about to upload:

<keyword> represents a word or phrase with special
significance in a particular domain. In the general case, <keyword>
elements typically do not have any special semantics and processing associated
with them, but can still be useful for organizing content for reuse or
special processing. <keyword> specializations are more meaningful
and are therefore preferable. <keyword> in the <keywords> element
distinguishes a word or phrase that describes the content of a topic (a
topic description keyword). Topic description keywords are typically used
for searching, retrieval and classification purposes.

Specialized elements derived from <keyword> may also have extended processing, such as different formatting or automatic indexing. If the keyref attribute is used, or some other method of key-based lookup based on the value of the element itself, then the keyword can be turned into a hyperlink on output (not currently supported).

When DITA topics are output to XHTML, any <keyword> elements in the <keywords> element are placed in the Web page metadata.

Michael Priestley
mpriestl@ca.ibm.com

"Esrig, Bruce (Bruce)" <esrig@lucent.com>

03/15/2005 10:57 AM

To	dita@lists.oasis-open.org
cc
Subject	RE: [dita] Proposed revision for the keyword definition (was Keyw        ords in DITA)

Here is some updated text for consideration.
 
Bruce
 
========
 
The <keyword> element and its specializations are used to mark a word or compound word with special meaning in a particular domain. For special treatment of phrases, see <ph>.

In the prolog of a topic, the <keyword> element may appear within the <keywords> element. In this context, the contents of the <keyword> element indicate the subject of the topic. This information is intended to help an author classify and identify a topic, which can be used for search and retrieval applications and other applications such as flagging.

In the body of a topic, the <keyword> element delimits words and compound words that also appear within the text of the topic.

In either context, the preferred approach is to use a specialization of <keyword>. The specializations have special semantics associated with them. In the body of a topic, the specializations can be processed with special formatting in the output. If no appropriate specialization has been created, the author can use the outputclass attribute to indicate the semantic scope.
-----Original Message-----
From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: Tuesday, March 15, 2005 10:02 AM
To: Esrig, Bruce (Bruce)
Cc: dita@lists.oasis-open.org; Michael Priestley; 'Paul Prescod'
Subject: RE: [dita] Proposed revision for the keyword definition (was Keyw ords in DITA)

Hi, Paul and Bruce:

You're right to mention the <ph> element. Like <keyword>, the <ph> element doesn't have much semantic weight. The two elements differ, however, in the structural scope.

The <ph> element is expected to mark up a portion of a block -- for instance, <ph outputclass="caution">if you need to provide an inline warning.</ph>

The <keyword> element is expected to mark up a semantic word -- for instance, beware the <keyword outputclass="mythicalCreature">frumious bandersnatch</keyword> -- which is smaller than a phrase.

That is, the DITA content models have three levels of discourse granularity (block, phrase, and word) where some XML vocabularies only have two (block and inline).

DITA is not alone in having generic elements -- witness DocBook <phrase> or XHTML <div> and <span>. In all of these markups, an attribute (role in DocBook, class in XHTML, and outputclass in DITA) can refine the semantic intent. In DITA, however, you can also specialize for more formal declaration and better guidance to authors.

You note that more specialized elements are preferred to <keyword> -- but that's true of all elements. You should always use the most specialized element that applies.


Hoping that's useful,


Erik Hennum
ehennum@us.ibm.com


"Esrig, Bruce (Bruce)" <esrig@lucent.com>

"Esrig, Bruce (Bruce)" <esrig@lucent.com>

03/15/2005 06:41 AM

To	"'Paul Prescod'" <paul.prescod@blastradius.com>, Michael Priestley <mpriestl@ca.ibm.com>
cc	dita@lists.oasis-open.org
Subject	RE: [dita] Proposed revision for the keyword definition (was Keyw ords in DITA)

I would favor treating <keyword> as a virtual element in the body. Usually, one of its specializations would be used. <keyword> is only used directly in the body as an interim measure when an appropriate specialization has not yet been defined.

Bruce Esrig

================

The <keyword> element and its specializations are used to mark a word or phrase with special significance in a particular domain.

In the prolog of a topic, the <keyword> element may appear within the <keywords> element. In this context, the contents of the <keyword> element introduce a word or phrase that describes the content of the topic. This information is intended to help an author classify and identify a topic and to help an end user search for and retrieve topics.

In the body of a topic, the usual approach is to use a specialization of <keyword>. The specializations have special semantics and processing associated with them. If <keyword> is used in the body of a topic, it is often because no appropriate specialization has been created. In this context, any special semantics or processing for the <keyword> element are a matter of local practice.
-----Original Message-----
From: Paul Prescod [mailto:paul.prescod@blastradius.com]
Sent: Tuesday, March 15, 2005 5:53 AM
To: Michael Priestley
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Proposed revision for the keyword definition (was Keywords in DITA)

You may be able to convince me but you haven't yet Michael. I think that your claims that "<keyword> has almost no semantics" and "<keyword> could be used for specialized processing" are somewhat at odds. We write standards so that we can exchange documents and get reliable behaviour. If you start linking unspecialized keywords to topics in your processing then when I send you my documents your process will do that to my documents as well. So we should either all decide that the <keyword> element implies a reference to a similarly-named topic or we should all decide it doesn't. If you want your keywords to have special behaviour then you should specialize.

Sound-bite: "Special processing" should always go along with "specialization". (as an aside, if specialization is too heavy-weight for some special processing then maybe we need ways of making it lighterweight. I've had some ideas about how to use outputclass as a lightweight way of specializing without changing DTDs).

As far as reuse, why not use <ph>?

Nevertheless, I could agree to the text below if you are not convinced by my argument.

---

From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Monday, March 14, 2005 7:05 PM
To: Paul Prescod
Cc: Dana Spradley; dita@lists.oasis-open.org; Don Day; Erik Hennum;
JoAnn Hackos; Rob Frankland
Subject: RE: [dita] Proposed revision for the keyword definition (was
Keywords in DITA)


One reason to use keyword in content is when a specialized element is not
available, but some semantic significance is still there that may provide
fodder for processing. For example, the source for the DITA language reference
marks up XML element names with <keyword>. That info could be used
to turn the keywords into links to their equivalent reference topics.

Another reason to use keyword is when you need reuse of a specific word
or phrase, again for which a specialized element is not available. For
example, it's a standard practice not to enter the product name directly
in content, but reuse it from a common elements repository, so it can be
updated it in one place when the product name changes. 

I like your description, but would want to modify it to allow for some
of these alternate uses. How about: 

<keyword> represents a word or phrase with special significance in
a particular domain. In the general case, <keyword> elements typically
do not have any special semantics and processing associated with them,
but can still be useful for organizing content for reuse or special processing.
<keyword> specializations are more meaningful and are therefore preferable.
<keyword> in the <keywords> element distinguishes a word or
phrase that describes the content of a topic (a topic description keyword).
Topic description keywords are typically used for searching, retrieval
and classification purposes." 

Michael Priestley
mpriestl@ca.ibm.com 
[attachment "graycol.gif" deleted by Michael Priestley/Toronto/IBM]
[attachment "ecblank.gif" deleted by Michael Priestley/Toronto/IBM]