OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita] Keywords in DITA


I wonder if Bruce could provide an example of the distinction between keyword as description and keyword as content. I'm not certain I understand how they are being distinguished from this explanation.
 

JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
joann.hackos@comtech-serv.com
http://www.comtech-serv.com

 


From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
Sent: Wednesday, March 09, 2005 1:13 AM
To: 'Don Day'; Paul Prescod
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Keywords in DITA

A future release of the architecture should provide language to distinguish between two specializations of the archetype: a description (keyword-as-description) and an object (keyword-of-content). This would provide a clear distinction that would cue authors and processing about the difference in purpose.
 
Not all field names or function names make good search terms, so including all such identifiers among the candidate targets for search impairs the specificity that users want when they search. This means there is a benefit to being able to mark up identifiers for special presentation in output (keyword-of-content) without including them among search terms.
 
Indexterm is really a special case of keyword-as-description. Keyword-as-description could be permitted in content to permit authors to identify text that is to be used as a search target. It is often convenient to mark up identifying text on first occurrence.
 
The clash comes when an author wants both usages simultaneously: keyword-as-description to indicate a search target and keyword-of-content because the identifier is a special identifier in the content. The keyword-of-content usage must take precedence. In order to accomodate the keyword-as-description usage, the author could choose to write some descriptive text to hold the keyword-as-description usage, or else place a keyword-as-description entry in a metadata context. Although it is tempting to use the unspecialized markup in these cases, there is still the question of whether to trigger an index entry, so a third specialization of the archetype (keyword-desc-and-content) may be needed.
 
Best wishes,
 
Bruce Esrig
-----Original Message-----
From: Don Day [mailto:dond@us.ibm.com]
Sent: Tuesday, March 08, 2005 11:13 PM
To: Paul Prescod
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Keywords in DITA

I buy it in the strict sense, Paul, but life can be so darned non-linear. How about this scenario:

As a content owner, I created a domain for marking up both widgettype and widgetname words in my product descriptions, both specialized from keyword. Authors have generally used these elements to tag names and types throughout the content. Later, I run a consolidation tool against my content to retrieve all elements based on keyword, create a single copy of each unique element/value, and put these into the keywords metadata of the topic as a pre-processed pool that I intend to use as search keys. Domain substitution means that the keywords element can contain keyword as well as the elements specialized from it--widgetname and widgettype. Although your definitions might differentiate the name as being "API-like" and the type as metadata, yet both are here, based on the same element , in both content and metadata contexts. From my point of view as a user, there is no need for too fine-grained a definitional distinction because my domain specialization and my subsequent use of the elements in both contexts effectively makes the distinction moot--the specialized elements are describing my product semantically and are providing the consistent search/relevance behavior I desired.

My real world experience bets that most authors will be inconsistent about what they mark up as keyword in the metadata vs in the content. Thus jaded, I'm back to the suggestion of keeping the description high level. keyword is just an archetype--the significant distinctions come when it is specialized to clearly indicate what it is for.

Regards,
--
Don Day <dond@us.ibm.com>
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
11501 Burnet Rd., MS 9037D018, Austin TX 78758
Ph. 512-838-8550 (T/L 678-8550)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
Inactive hide details for "Paul Prescod" <paul.prescod@blastradius.com>"Paul Prescod" <paul.prescod@blastradius.com>


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

          03/08/2005 07:45 PM


To

"JoAnn Hackos" <joann.hackos@comtech-serv.com>, Don Day/Austin/IBM@IBMUS

cc

<dita@lists.oasis-open.org>

Subject

RE: [dita] Keywords in DITA

Okay, an emerging consensus seems to be that <keyword> in <keywords> means <keyword> in the HTML/Docbook sense.
http://www.docbook.org/tdg/en/html/keyword.html . It is typically hidden from the user as metadata and embedded in the HTML meta tag.

<keyword> in other contexts is more like a word from an API or language.

Should we just document it that way? If so, I can suggest some wordings.

Paul Prescod



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]