← Prev in month
← Prev in 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