|
Here is the draft. Some things to note: ·
Once I started working on the
article, I realized that it would be too long if I tried to address keywords
and index entries, so I focused on keywords. ·
I would appreciate any suggestions
for better keywords to use in the examples. ·
I used <codeblock> for all
my examples, but if someone can suggest a better element to use for the
generated output (=non-markup) examples, I’d be happy to use it. ·
I would love any input on the Why
section, especially about the Web metadata. From the folks I talked with, the
story is that many search engines do not use this metadata because of the
optimization engines that manipulate the data. Of course, any other feedback that would improve the article is
welcome. Thanks, A -----Original Message----- XML works for me JoAnn T. Hackos, PhD President Comtech Services, Inc. 303-232-7586 joann.hackos@comtech-serv.com joannhackos Skype www.comtech-serv.com -----Original Message----- From: Amber Swope [mailto:amber.swope@xmetal.com] Sent: Monday, April 30, 2007 9:02 AM To: JoAnn Hackos; Carol Geyer; dita-fa-edboard@lists.xml.org Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site Hi there, The good news is that I have the first draft of the next article ready for your review. Of course, I wrote it in XML and can provide it in all the usual formats for review. What format is best? Thanks, A -----Original Message----- From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] Sent: Monday, April 30, 2007 6:44 AM To: Carol Geyer; dita-fa-edboard@lists.xml.org Subject: RE: [dita-fa-edboard] Traffic Report for DITA XML.org site Interesting -- we're seeing a regular decline. Probably need to have
new content. JoAnn JoAnn T. Hackos, PhD President Comtech Services, Inc. 303-232-7586 joann.hackos@comtech-serv.com joannhackos Skype www.comtech-serv.com -----Original Message----- From: Carol Geyer [mailto:carol.geyer@oasis-open.org] Sent: Monday, April 30, 2007 8:02 AM To: dita-fa-edboard@lists.xml.org Subject: [dita-fa-edboard] Traffic Report for DITA XML.org site DITA XML.org Editorial Board, Attached are site stats for April. We may want to discuss these on our next call. Carol _________________________________ Carol Geyer Director of Communications OASIS +1.978.667.5115 x209 --------------------------------------------------------------------- This publicly archived list is provided by OASIS for the use of the Editorial Board of DITA XML.org. Subscription and posting privileges are reserved for members of the Editorial Board; others should contact communications@oasis-open.org for assistance. [Un]Subscribe: dita-fa-edboard-[un]subscribe@lists.xml.org List archives: http://lists.xml.org/archives/dita-fa-edboard/ XML.org DITA Focus Area: http://dita.xml.org Committee homepage: http://www.oasis-open.org/committees/dita List Guidelines: http://www.oasis-open.org/maillists/guidelines.php |
<?xml version="1.0"?> <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> <!-- Created with XMetaL (http://www.xmetal.com) --> <concept id="concept_B53B5D0F8C8848978E10D769D3BA5696"> <title>Keywords: where, why and when to use them</title> <shortdesc> According to Wikipedia, a keyword "is a word or concept with special significance." This is a very broad definition that emcompasses a wide range of uses. This article explains what keywords are in DITA and proposes guidance for keyword usage.</shortdesc> <prolog><metadata><keywords><keyword>keyword</keyword></keywords></metadata></prolog><conbody> </conbody><concept id="concept_7A3F40D0B45D4C2D9BD4B58A1E01EEA0"><title>Keywords and the <keyword> element </title> <shortdesc>The DITA Release 1.1 Architectural Specification defines keywords as "Terms from a controlled or uncontrolled subject vocabulary that apply to the topic." This definition provides some context in that it specifies that keywords apply to topics, but it doesn't help us determine what words to designate as keywords. </shortdesc><conbody><p>The way to specify keywords in DITA is to use the <keyword> element. "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 that is designed to easily allow specialization. For example, the <apiname>, <kwd>, <option>, <parmname>, <cmdname>, <msgnum>, <varname> <shortcut>, <wintitle>, and <shape> elements are all specializations of the <keyword> element. </p><p>What do all of these elements have in common? They are elements designed to capture text "that has a unique or key-like value"<fn>DITA Release 1.1 Language Specification , page 71</fn> This means that the text falls into a category of text with a specific purpose, and for which you may want to attach semantic value. If you consistently apply the <wintitle> element for the names of windows in the graphical user interface, then you can process the <wintitle> element differently than 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> </conbody></concept> <concept id="concept_E62F91C620AE4C3D876E5B4D87FC7EF2"><title>Why to use keywords </title> <shortdesc>The ability to control output processing for specific types of text is one 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 in the Web page metadata. Web metadata is important is that it enables styles and search/retrieval. </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 is useful in that you have flexibility for 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 semantic identification, then you simply make any in-line 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 <xref href="http://dita.xml.org"; scope="external" format="html"><?xm-replace_text http://dita.xml.org?></xref>:<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 for 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 can only 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. In addition, unlike <keyword> elements, <indexterm> elements do not appear in output text. To see the difference in the output, the first example shows the generated text with "DITA" as a keyword.<codeblock><b>DITA</b> 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>In contrast, the following text shows the generated text with <codeph><indexterm>DITA</indexterm></codeph>:<lines>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. </lines></p><p>To have a word or phrase appear in the text as well as in the index, you must apply both elements to the text. <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 tags, 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 in-line 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 defining words or phrases, you can easily format the text according to your corporate style, such as to format 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, they are not interchangeable. The primary difference is the purpose of the elements. If you want to classify text as being semantically important, then 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, then you can apply the <phrase> element, assign an ID to the <phrase> element, and then reference the ID using the conref attribute in many of the DITA elements. Granted, you can accomplish 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 with your own .css.</p></section></conbody></concept><concept id="concept_D2D8A0776059431D95FD808096619977"><title>Summary</title> <shortdesc>The rule of thumb 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 using other elements.</p></conbody></concept></concept>