I will freely admit that I am not the most
technical to comment on this thread. However, since the need for a good
single-sourcing tool in the technical documentation community is huge and DITA
is a good solution, we should make sure that something as important as keywords
is not obscure to the user. The average user will not be aware of the fine
point of content semantics.
That is why I felt the suggestion made by Paul
this morning fits the bill for 1.0.
Rob
From: Dana Spradley [mailto:dana.spradley@oracle.com]
Sent: Monday, March 14, 2005 2:49
PM
To: Erik Hennum
Cc: dita@lists.oasis-open.org; Don
Day; JoAnn Hackos; Paul Prescod; Rob Frankland
Subject: Re: [dita] Keywords in
DITA
I agree, Erik - which is why I'd like to see the
<keyword> definition changed in the draft spec to reflect one single
meaning - the meaning implied by the meaning of <keywords>, and not a
meaning that duplicates the meaning of <kwd> - than two divergent ones.
After that, I also agree that a userful enhancement down the road would be
replacing <keywords> with something like <topicwords> or, say,
<semes> or <coverTerms> or <conceptualBreadcrumbs> or
<searchHooks> or <topicHandles> or something, and including all
metadata elements that seek to encapsulate the overall gist of the topic into
it, if they aren't put inline in the body of the text instead.
I'm new to the TC, and hesitate to propose a replacement definition myself.
Paul Prescod, do you feel like risking a definition in advance of tomorrow's
meeting? Your offer to try your hand did, after all, begin this subthread.
--Dana
Erik Hennum wrote:
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
ehennum@us.ibm.com
Dana
Spradley <dana.spradley@oracle.com>
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
joann.hackos@comtech-serv.com
http://www.comtech-serv.com
From: Rob Frankland [mailto:robf@rascalsoftware.com]
Sent: Monday, March 14, 2005 9:29 AM
To: 'Paul Prescod'; JoAnn Hackos; 'Don Day'
Cc: dita@lists.oasis-open.org
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:paul.prescod@blastradius.com]
Sent: Tuesday, March 08, 2005 5:46 PM
To: JoAnn Hackos; Don Day
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