The short description (<shortdesc>) element occurs between the topic title and the topic body, as the initial paragraph-like content of a topic, or it can be embedded in an abstract element. The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching. The <shortdesc> element also can be used in a DITA map.
Use the <shortdesc> element when the first paragraph of topic content is simple enough to be suitable for use as a link preview or for summaries. Otherwise use the <abstract> element to provide richer content around the <shortdesc>. See the 3.1.1.1.7 abstract description for more details on the behavior of <shortdesc> in an abstract.
While inclusion of the <shortdesc> element is not mandated by DITA or the tools, it is recommended that topics contain this element. In cases where a topic contains only one paragraph, then it is preferable to include this text in the <shortdesc> and leave the topic body empty.
The short description should be a single, concise paragraph containing one or two sentences of no more than 50 words.
The <shortdesc> element is also available in maps within the <topicmeta> element. In a map, the element specifies that a topic has a short description that is specific to the context of that topicref in that map. When constructing link previews, links that are generated according to the context of the map should use the <shortdesc> content provided in the map rather than the <shortdesc> provided in the topic. The <shortdesc> element in the map allows authors to provide short descriptions for references to non-DITA objects.
The content of the <shortdesc> element also can be used to override the short description of the topic, when the copy-to attribute is specified.
Processors may or may not implement this behavior.
topic (base), map (base), classifyMap, subjectScheme, learningAssessment, learningBookmap, learningContent, learningMap, learningOverview, learningPlan, learningSummary |
( text data or boolean or keyword or ph or b or i or sup or sub or tt or u or q or term or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number) |
topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap |
( text data or boolean or keyword or apiname or option or parmname or cmdname or msgnum or varname or wintitle or ph or b or i or sup or sub or tt or u or codeph or synph or filepath or msgph or systemoutput or userinput or menucascade or uicontrol or q or term or abbreviated-form or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number) |
( text data or boolean or keyword or wintitle or ph or b or i or sup or sub or tt or u or menucascade or uicontrol or q or term or tm or state or data or data-about or foreign or unknown or image or draft-comment) (any number) |
map (base), map (technical content), classifyMap, learningMap |
|
topic, abstract, learningBase, task, concept, reference, learningSummary, learningAssessment, learningContent |
|
"- topic/shortdesc " when used in topics, and "- map/shortdesc " when used in maps.
The following example demonstrates the use of a stand-alone shortdesc inside of a concept topic.
<concept id="concept"> <title>Introduction to Bird Calling</title> <shortdesc>If you wish to attract more birds to your Acme Bird Feeder, learn the art of bird calling. Bird calling is an efficient way to alert more birds to the presence of your bird feeder.</shortdesc> <conbody> <p>Bird calling requires learning:</p> <ul> <li>Popular and classical bird songs</li> <li>How to whistle like a bird</li> </ul> </conbody> </concept>
<topicref href="myThing.dita"> <topicmeta> <navtitle>Navigation title for my topic</navtitle> <shortdesc>A description of myThing that is specific to this context.</shortdesc> </topicmeta> </topicref> <topicref href="http://www.example.org" scope="external"> <topicmeta> <navtitle>Example website</navtitle> <shortdesc>The example.org address is often used in examples</shortdesc> </topicmeta> </topicref>
<abstract>The abstract is being used to provide more complex content. <shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc> The abstract can put text around the shortdesc. </abstract>
The abstract is being used to provide more complex content. The shortdesc must be directly contained by the abstract. The abstract can put text around the shortdesc.
The shortdesc must be directly contained by the abstract.
<abstract><p>The abstract is being used to provide more complex content.</p> <shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc> <p>The abstract can put text around the shortdesc.</p> </abstract>
The abstract is being used to provide more complex content.
The shortdesc must be directly contained by the abstract.
The abstract can put text around the shortdesc.
The shortdesc must be directly contained by the abstract.
<abstract>The abstract is being used to provide more complex content. <shortdesc>The shortdesc must be directly contained by the abstract.</shortdesc> <p>The abstract can put text around the shortdesc.</p> <shortdesc>There can be more than one shortdesc.</shortdesc> </abstract>
The abstract is being used to provide more complex content. The shortdesc must be directly contained by the abstract.
The abstract can put text around the shortdesc.
There can be more than one shortdesc.
The shortdesc must be directly contained by the abstract. There can be more than one shortdesc.
univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) |
A set of related attributes, described in 3.4.1.3 univ-atts attribute group |
|||
A set of related attributes, described in 3.4.1.2 global-atts attribute group |
||||
Common attributes described in 3.4.1.9 Other common DITA attributes |