<shortdesc> in a DITA map

[Kristen James Eberlein <keberlein@pobox.com>]

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