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
joann.hackos@comtech-serv.com
http://www.comtech-serv.com
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.
<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>
<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>
<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>
</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>
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