JoAnn T. Hackos, PhD
President
Comtech Services,
Inc.
710 Kipling
Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<!-- Created with XMetaL (http://www.xmetal.com) -->
<concept id="concept_B53B5D0F8C8848978E10D769D3BA5696">
<title>Keywords: why, where and when to use them</title>
<shortdesc>In DITA, the <keyword> element and the elements that are specialized from it
contain text that has a unique or key-like value.
</shortdesc>
<prolog>
<metadata>
<keywords><keyword>keyword</keyword><keyword>test</keyword>
</keywords></metadata>
</prolog><conbody><p> This article explains these elements in more detail and proposes guidelines for how to use them.
</p>
</conbody>
<concept id="concept_7A3F40D0B45D4C2D9BD4B58A1E01EEA0">
<title>Keywords and the <keyword> element </title>
<shortdesc>The keyword elements that are available in DITA
cover a wide variety of situations in which
you need to introduce new terms to the reader. For these situations,
DITA provides a variety of specialized elements.
</shortdesc>
<conbody>
<p>
The <keyword> element is used to specify
any of several common types of terms in DITA.
What do all of these elements have in common? They are elements
designed to contain text "that has a unique or key-like value"<fn>DITA Release
1.1 Language Specification , page 71</fn>
By "text with a unique or key-like value," we mean
text that has a specific purpose.
You designate a term as a keyword when you want to indicate
that the term has a special meaning.
</p>
<p>For example, if you consistently apply the <wintitle> element for the names of windows in the graphical user interface, you can process the
<wintitle> element differently from other text. If the corporate style is
to format window names as bold text, then you can specify that the transform apply bold styling to all <wintitle> elements upon processing.
</p>
<p>
When used in the metadata of a topic, keywords are
"Terms from a controlled or uncontrolled subject vocabulary that
apply to the topic."<fn>DITA Release 1.1 Architectural Specification</fn>
Whether used as metadata or in the body of a topic,
"the <keyword> element identifies a keyword or token, such as a
single value from an enumerated list, the name of a command or parameter,
product name, or a lookup key for a message."<fn>DITA Release 1.1 Language
Specification, page 71
</fn>
</p>
<p>The <keyword> element is a generic element designed to allow easy specialization. For example, the <apiname>, <kwd>,
<option>, <parmname>, <cmdname>, <msgnum>,
<varname> <shortcut>, <wintitle>, and <shape> elements
are all specializations of the <keyword> element.
</p>
</conbody>
</concept>
<concept id="concept_E62F91C620AE4C3D876E5B4D87FC7EF2">
<title>Why use keywords </title>
<shortdesc>The ability to control output processing for specific types of
text is one of the main reasons to use the <keyword> element.
</shortdesc>
<conbody>
<p>Another reason for specifying keywords is to aid in Web content
indexing and retrieval. When the DITA Open Toolkit (OT) processes DITA topics
and maps to XHTML, it places any <keyword> and <indexterm> elements
that appear in the prolog of a topic into the metadata of the generated Web page.</p>
<p>However, because of abuses of Web page metadata by sites attempting to optimize their ranking in search engine results, search engines that are designed for use on the public portions of the Web tend not to trust Web page metadata.</p></conbody>
</concept>
<concept id="concept_9A141EBF45E04797BFEBF93FE08482BE">
<title>Where to use keywords </title>
<shortdesc>You can include keywords in different places in DITA topics.
This ability is useful because it gives you flexibility in applying the
keywords; however, you need to consider where the keywords are appropriate.
</shortdesc>
<conbody>
<p>If you have a word or phrase to which you want to apply a semantic
identification, simply make any inline text a keyword by including the text
within the <keyword> element. The following example shows how to make
DITA a keyword in a sentence from DITA XML.org.
<codeblock><p><keyword>DITA</keyword> builds content reuse into the authoring process, defining an
XML architecture for designing, writing, managing, and publishing many kinds of information in print and on
the Web.</p>
</codeblock>
</p>
<p>You can also specify keywords in the prolog of a topic, which implies
that the keyword applies to the full topic AND it will apply to the full topic
in any context. The following example shows the XML markup:
<codeblock><prolog><metadata>
<keywords><keyword>Whitepaper</keyword></keywords>
</metadata></prolog>
</codeblock>
</p>
<note>You insert the <prolog> element between the closing
<shortdesc> tag and the opening tag for the topic body element.
</note>
<p>If a keyword applies to a topic but only in a specific context, you
can specify the keywords in the DITA map. The following example shows the XML
markup for specifying a keyword for a topic in a map:
<codeblock><topicref href="Topic_a.xml">
<topicmeta><keywords><keyword>XML Whitepapers</keyword></keywords></topicmeta>
</topicref>
</codeblock>
</p>
</conbody>
</concept>
<concept id="concept_83826A78D62A4A4582B32417BB623B48">
<title>When to use keywords </title>
<shortdesc>There are several DITA elements that seem to serve the same or
similar purposes. For example, when do you specify a word as an index term,
term, phrase, or keyword?
</shortdesc>
<conbody>
<section id="section_71D4329238A243F896CA3623239D2699">
<title><indexterm> or <keyword></title>
<p>Although the DITA OT processes <keyword> and <indexterm>
elements the same way for Web content, it provides additional processing for
<indexterm> elements and compiles them into an alphabetized index for
print, help, or another medium that includes an index. In addition, unlike
<keyword> elements, <indexterm> elements do not appear in output
text. To illustrate the difference in the output, the example shows the
generated text with "DITA" as a keyword.
<table id="table_DCD1505C4CA2484C8755A0D360DAC133">
<tgroup cols="1"><colspec colnum="1" colname="col1" colwidth="*"/>
<tbody>
<row>
<entry colname="col1">DITA builds content reuse into the
authoring process, defining an XML architecture for designing, writing,
managing, and publishing many kinds of information in print and on the Web.
</entry>
</row>
</tbody>
</tgroup>
</table>
</p>
<p>In contrast, the following text shows the generated text with
<codeph><indexterm>DITA</indexterm></codeph>:
<table id="table_017760E7962B44E88CE95529EFA22DF1">
<tgroup cols="1"><colspec colnum="1" colname="col1" colwidth="*"/>
<tbody>
<row>
<entry colname="col1">builds content reuse into the authoring
process, defining an XML architecture for designing, writing, managing, and
publishing many kinds of information in print and on the Web.
</entry>
</row>
</tbody>
</tgroup>
</table>
</p>
<p>In the second example, the word "DITA" is missing. To have a word or
phrase appear in the text as well as in the index, you must apply both
<indexterm> and <keyword>.
<codeblock><indexterm>DITA</indexterm><keyword>DITA</keyword> builds content reuse
into the authoring process, defining an XML architecture for designing, writing, managing, and
publishing many kinds of information in print and on the Web.
</codeblock>
</p>
<p>Although it looks redundant when you view the XML markup, the output
from the above example generates the text with "DITA" as the keyword and
includes "DITA" in the index.
</p>
</section>
<section id="section_22A8E9C9397D47EF8BC58F6B507E9953">
<title><term> or <keyword>?</title>
<p> The important distinction to note between a keyword and a term is
the purpose of the text. If you are defining a term in the text, then use the
<term> element rather than <keyword> for the inline element. The
<term> element identifies words that may have or require extended
definitions or explanations."
<fn>DITA Release 1.1 Language Specification, page 204.
</fn> If you consistently apply the <term> element when you are
defining words or phrases, you can easily format the text according to your
corporate style, such as formatting terms in text with italics.
</p>
</section>
<section id="section_C7DBE4A9C3014B3F9F865A5CEF75799C">
<title><phrase> or <keyword>?</title>
<p>The <phrase> and <keyword> elements are valid in almost
all of the same places in DITA topics, but they are not interchangeable. The
primary difference is the purpose of the elements. If you want to classify text
as semantically important, use the <keyword> element. If you simply want
to encapsulate text in a generic element for reuse or conditional processing,
then use the <phrase> element.
</p>
<p>For example, if you want to reuse a word, but it does not have
semantic meaning, you can apply the <phrase> element, assign an ID to the
<phrase> element, and then reference the ID using the conref attribute.
Granted, you can achieve the same outcome with the <keyword> element, but
the DITA OT also processes the <keyword> element for the Web metadata.
</p>
<p>Another point to note is that the default .css that ships with the
DITA OT applies the bold style to keywords. Of course, you can override this
formatting with your own .css.
</p>
</section>
</conbody>
</concept>
<concept id="concept_D2D8A0776059431D95FD808096619977">
<title>Summary</title>
<shortdesc>The rule when applying elements is to apply the element that
provides the minimum processing that you need. If you do not need the semantic
processing that the <keyword> element provides, do not use it; rather,
use the element that provides the appropriate processing power and output.
</shortdesc>
<conbody>
<p>If you are generating XHTML for Web output or need to identify text
with semantic distinction, then the <keyword> element provides value. In
many other cases, you can achieve the desired resulting processing and output
with other elements.
</p>
</conbody>
</concept>
</concept> <?Pub *0000009820 0?>