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 (example)
From: Dana Spradley <>
To: JoAnn Hackos <>
Date: Wed, 09 Mar 2005 12:41:12 -0800
According to the spec, JoAnn - which I also am
fairly new to - a <term> will link to its definition in the
glossary in some future DITA development. (I just looked it up myself)
Similarly, in line with Don's comments I don't see why inline
<keyword> elements shouldn't be mined to populate the web page
metadata on output, in some future development of the DITA toolset - if
desired. Not everyone wants to make a second labor of putting them in
the <keywords> element.
I think the confusion that has sparked this discussion comes from
insisting too narrowly on the difference between a keyword in the
technical programming sense ("keyword-of-content") and a keyword in the
metadata sense ("keyword-of-description"). While a difference certainly
exists - it evaporates fairly quickly when we're talking about
*documenting* a programming language.
For then, the keywords of the language are the keywords of your
descriptions and the keywords you want in your metadata, right? So if
someone is searching for information on how to use this keyword in a
programming sense, they'll find the pages that describe it.
The definition of <keyword> in the spec, though, should be tuned
up a bit, to avoid (or deal with) this potential confusion.
--Dana
JoAnn Hackos wrote:
I don' t understand the
<term> element. Can that now be used? Is there processing
avialable?
JoAnn
JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver, CO 80215
303-232-7586
http://www.comtech-serv.com
From: Esrig,
Bruce (Bruce) [mailto:]
Sent: Wednesday, March 09, 2005 12:40 PM
To: JoAnn Hackos; Don Day; Paul Prescod
Cc:
Subject: RE: [dita] Keywords in DITA (example)
Yes, a good example would help ... anyone
want to buy a snow shovel (see example) ?
Here goes,
Bruce
=============
First the hierarchy.
Keyword archetype.
- keyword-as-description
o existing keyword element, in the
sense defined by HTML/Docbook
o existing indexterm element
- keyword-as-content
o wintitle
o widgettype
o widgetname
Now some markup.
<task id="snowShovelInventory-task"
xml:lang="en-us">
<title>Checking the inventory of snow
shovels</title>
<taskbody>
<context><p>Check whether
snow shovels are available before running out to buy
one.</p></context>
<steps>
<p>The <wintitle>Inventory
Window</wintitle>
provides
a count of items given the name of the item.
The
<widgetname>Item</widgetname> field contains the name of an
item.
The
<widgetname>Count</widgetname> field states how many items
with that name
are in stock according to the inventory
records.</p>
<step><cmd>Access the
<wintitle>Inventory
Window</wintitle>.</cmd></step>
<step><cmd>Enter
<userinput>snow shovel</userinput> in the
<widgetname>Item</widgetname> field and click on
<widgetname>Update</widgetname>.</cmd></step>
<step><cmd>Look at the
<widgetname>Count</widgetname> field
to find out how
many snow shovels are in stock.</cmd></step>
</steps>
</taskbody>
<related-links>
<link
href="../concepts/snowShovel.xml" format="xml" type="concept">
<linktext>Snow
shovel</linktext></link>
<link
href="../reference/inventoryWindow.xml" format="xml"
type="reference">
<linktext>Inventory
window</linktext></link>
</related-links>
</task>
<concept id="snowShovel-concept"
xml:lang="en-us">
<prolog><metadata>
<keywords>
<keyword>snow</keyword>
<keyword>tool</keyword>
<indexterm>tools
<indexterm>snow
shovel</indexterm></indexterm>
</keywords></metadata></prolog>
<title>Snow shovel</title>
<conbody>
<p>A <indexterm>snow
shovel</indexterm> snow shovel is used to clear the driveway and
sidewalk of snow in the winter.
A good snow shovel has a straight, wide
<term>scoop</term> and a strong
<term>handle</term>.
To help snow come off the scoop, spray
the scoop with cooking spray.</p>
</conbody>
<related-links>
<link
href="../tasks/snowShovelInventory.xml" format="xml" type="task">
<linktext>Snow shovel
inventory</linktext></link>
</related-links>
</concept>
<reference
id="inventoryWindow-reference" xml:lang="en-us">
<prolog><metadata>
<keywords>
<indexterm>windows
<indexterm>Inventory
Window</indexterm></indexterm>
<indexterm>fields
<indexterm>Item</indexterm></indexterm>
<indexterm>fields
<indexterm>Count</indexterm></indexterm>
</keywords></metadata></prolog>
<title>Inventory window</title>
<refbody><refsyn>
<p>The <wintitle>Inventory
Window</wintitle>
provides
a count of items given the name of the item.
The <widgetname>Item</widgetname> field contains the name
of an item.
The
<widgetname>Count</widgetname> field states how many items
with that name
are in stock according to the inventory
records.</p>
</refsyn></refbody>
</reference>
-----Original
Message-----
From: JoAnn Hackos [mailto:]
Sent: Wednesday, March 09, 2005 10:45 AM
To: Esrig, Bruce (Bruce); Don Day; Paul Prescod
Cc:
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
http://www.comtech-serv.com
From: Esrig, Bruce (Bruce)
[mailto:]
Sent: Wednesday, March 09, 2005 1:13 AM
To: 'Don Day'; Paul Prescod
Cc:
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:]
Sent: Tuesday, March 08, 2005 11:13 PM
To: Paul Prescod
Cc:
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 <>
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
"Paul
Prescod" <>
"Paul Prescod"
<>
03/08/2005 07:45 PM
To
"JoAnn Hackos"
<>, Don Day/Austin/IBM@IBMUS
cc
<>
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
References:
RE: [dita] Keywords in DITA (example)
From: "JoAnn Hackos" <>
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
