dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] Keywords in DITA (example)
- From: "Esrig, Bruce (Bruce)" <esrig@lucent.com>
- To: "'JoAnn Hackos'" <joann.hackos@comtech-serv.com>, Don Day <dond@us.ibm.com>, Paul Prescod <paul.prescod@blastradius.com>
- Date: Wed, 9 Mar 2005 14:45:33 -0500
Oops
... I had a <p> out of context in the task.
Deleted it.
Bruce
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>
<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>
<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>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>
</reference>
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
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
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
"Paul Prescod"
<paul.prescod@blastradius.com>
"Paul Prescod"
<paul.prescod@blastradius.com>
03/08/2005 07:45 PM |
|
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]
