dita — archive

Re: [dita] Keywords in DITA

From: Erik Hennum
To: [email protected]
Date: Mon, 14 Mar 2005 20:49:00 -0000

 MHonArc v2.5.0b2 -->



























dita message






[Date Prev]
 | [Thread Prev]
 | [Thread Next]
 | [Date Next]

--

[Date Index]
 | [Thread Index]
 | [List Home]








Subject: Re: [dita] Keywords in DITA




From: Erik Hennum <[email protected]>
To: Dana Spradley <[email protected]>, [email protected],       Don Day <[email protected]>,       JoAnn Hackos <[email protected]>,       Paul Prescod <[email protected]>,       Rob Frankland <[email protected]>
Date: Mon, 14 Mar 2005 12:48:31 -0800







Hi, Dana, JoAnn, and Rob:


I'd like to submit some reservations about defining elements based on the expected output instead of the content semantics:



An HTML generator could legitimately choose to populate the keyword metadata with semantic words that are delimited by <term> and <keyword> elements within the text.


A PDF generator could legitimately choose to display semantic words associated with the topic as a whole in the page header.


A specialization designer should be able to specialize an element once to indicate a particular vocabulary (for instance, <chemicalterm> or <programword>) regardless of whether an instance of the vocabulary appears in the text or is associated with the topic as a whole.  That's possible only if the base element can appear in both contexts.  Here's an example:

<metadata>
<keywords>
    <chemicalterm>molecule</chemicalterm>
    <programword>element</programword>
</keywords>

</metadata>

...

<p>You list each <chemicalterm>atom</chemicalterm> in the <programword>array</programword>....</p>


If anything, I'd suggest that the culprit in creating confusing expectations might be the <keywords> element.  A metadata <topicwords> element that can contain <keyword>, <term>, or <indexterm> might be better, but I wouldn't expect serious consideration of that thought until after DITA 1.0


The need for enhancement never ends, and if we try to squeeze in this one, I'm sure lots of others will come out of the woodwork (such as the deferred <data> element).



Hoping that's useful,



Erik Hennum

[email protected]


[email protected]>">Dana Spradley <[email protected]>









Dana Spradley <[email protected]> 
03/14/2005 10:05 AM







To 

Dana Spradley <[email protected]>



cc 

JoAnn Hackos <[email protected]>, Rob Frankland <[email protected]>, Paul Prescod <[email protected]>, Don Day/Austin/IBM@IBMUS, [email protected]



Subject 

Re: [dita] Keywords in DITA








erratum: "otherwise you're sending mixed messages..."


In fact, it seems to me this whole discussion was provoked by a bad definition for <keyword> in the language spec, which defined it as a keyword in the technical programming sense, while from the <keywords> definition you would have expected it to be defined as in DocBook.


We could solve the entire issue by just revising that <keyword> definition to be what <keywords> expects.


If people feel there is a need for keywords in the technical sense to migrate beyond the confines of syntax diagrams, then that's a separate issue for the folks working on the Programming Domain vis-a-vis the <kwd> element - which *is* defined as a keyword in the technical programming sense.


--Dana


Dana Spradley wrote:

I agree on the DocBook part, but disagree on the <keyword> in other contexts is more like a word from an API or language clause.


The <kwd> element exists for that.


<keyword> outside <keywords> should have the same meaning it does within - outwise you're sending mixed messages to authors, and mixing up the use.


JoAnn Hackos wrote:

Sounds like a good solution.

 
JoAnn 
JoAnn T. Hackos, PhD 

President 

Comtech Services, Inc. 

710 Kipling Street, Suite 400 

Denver, CO 80215 

303-232-7586 

[email protected] 

http://www.comtech-serv.com 
 


From: Rob Frankland [mailto:[email protected]] 

Sent: Monday, March 14, 2005 9:29 AM

To: 'Paul Prescod'; JoAnn Hackos; 'Don Day'

Cc: [email protected]

Subject: RE: [dita] Keywords in DITA



I agree, having followed this thread. Your suggested solution covers both use cases. I believe the largest number of users will want the HTML/Docbook usage and this enables the programmer writers to meet their needs as well.

 

Rob

 
From: Paul Prescod [mailto:[email protected]] 

Sent: Tuesday, March 08, 2005 5:46 PM

To: JoAnn Hackos; Don Day

Cc: [email protected]

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

 












Follow-Ups:

Re: [dita] Keywords in DITA
From: Dana Spradley <[email protected]>



References:

Re: [dita] Keywords in DITA
From: Dana Spradley <[email protected]>






[Date Prev]
 | [Thread Prev]
 | [Thread Next]
 | [Date Next]

--

[Date Index]
 | [Thread Index]
 | [List Home]