DITA 2.0 stage one proposal: reconcile class attributes for shortdesc, linktext, searchtitle

["Robert D Anderson" <robander@us.ibm.com>]

Here comes my first official proposal for a backwards incompatible change.

In DITA 1.0, for reasons lost to history, the "map.mod" and "topic.mod" modules each contained their own definition of three elements: shortdesc, linktext, and searchtitle.

This resulted in inconsistent content models, which frustrated authors, and was resolved in DITA 1.2 by moving those definitions to the common elements module.

However, back in DITA 1.0, each definition also came with a unique class attribute. For example, shortdesc was "- map/shortdesc " in maps, and "- topic/shortdesc " in topics. The other two have the same pattern. Note the awkward text in the "Inheritance" section of each:
http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/base/linktext.html
http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/base/shortdesc.html
http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/base/searchtitle.html

I'd like to propose that we make the class attribute definition common. Like all other elements that can be used in both modules, it should use the "topic/shortdesc", "topic/linktext", and "topic/searchtitle" version.

This inconsistency was recognized early on, but couldn't be resolved when the content model definitions became common, because using just one @class value breaks backwards compatibility. An application today that assumes you use map/shortdesc in maps will not find topic/shortdesc.

That said ... in every application I've worked with, because elements like these get pushed back/forth by automated processes, I've had to make every <shortdesc> test into "If map/shortdesc or topic/shortdesc". Any applications that do this will continue to work with a common @class definition. Applications that do not will have to update their tests to use the new string.

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA