dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] Proposed revision for the keyword definition (was Keyw ords inDITA)
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Esrig, Bruce (Bruce)" <esrig@lucent.com>
- Date: Tue, 15 Mar 2005 11:02:21 -0500
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
|
|
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]
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]