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

[Erik Hennum <ehennum@us.ibm.com>]

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