← Prev in month ← Prev in thread

<shortdesc> in a DITA map

From
Kristen James Eberlein <>
Date
2009-08-19T17:23:22+00:00
ID
Thread
<shortdesc> in a DITA map
The review of the DITA 1.2 architectural spec has generated some
disagreement about how the content of the <shortdec> element in a
DITA map is used. Everyone agrees that the content of the
<shortdesc> element is used for link previews, but there is
disagreement about whether or not the content of the <shortdesc>
element, when used in a DITA map, overrides the content of the
<shortdec> element in the DITA topic.

(If you want to read the Wiki comments about this, go to
http://wiki.oasis-open.org/dita/ditaMaps and search on
<shortdesc>.)

Both the DITA 1.1 architectural spec and language reference contained
contradictory information about how the content of the
<shortdesc> element is used (emphasis added):

Architectural spec

  
"Metadata inheritance between maps and topics" states that the
content of the <shortdesc> element is "not added to the topic;
applies to links created based
on this occurrence in the map".

http://docs.oasis-open.org/dita/v1.1/OS/archspec/topicmetainheritance.html

  
"Common DITA map attributes and metadata" states "When a set of
topics is transformed using a
map, duplicate topic versions can be created using the copy-to
attribute.
The copied topic will have a new file name or location as provided in
the
copy-to attribute, and the map can override the default title and
shortdesc
for this particular copy by providing values for them in the map using
the
topicref's navtitle and shortdesc."

http://docs.oasis-open.org/dita/v1.1/OS/archspec/dita_spec_23_common.html

  

Language reference

  
"shortdesc" states "When used within a DITA map, the short
description of the <topicref> can be used to override the
short description in the topic."

http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/shortdesc.html

  
"abstract" states that the <abstract> element "can contain
paragraph-level content
as well as one or more shortdesc elements which can be used for
providing
link previews or summaries. The <abstract> element cannot be
overridden
by maps, but its contained <shortdesc> elements can be, for
the purpose
of creating link summaries or previews."

http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/abstract.html

How do we want to handle this? Currently the DITA OT and IBM's
implementation use the content of a <shortdesc>, when used in a
DITA map, only for link previews. IBM has created a specialized element
(<overrideShortdesc>) to enable people editing a DITA map to
force content into the DITA topic.

I see three possible choices:

  
A: The content of the <shortdesc> element, when used in a
DITA map, is used only for link previews.

  
B: The content of the <shortdesc> element, when used in a
DITA map, overrides the content of  the <shortdesc> element in
the DITA topic.

  
C: The content of the <shortdesc> element, when used in a
DITA map, may or may not override the content of the <shortdesc>
element in the DITA topic; the behavior varies depending on the
implementation.

Thoughts? I like A, personally.

Kris
← Prev in month ← Prev in thread