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
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
|