OASIS Darwin Information Typing Architecture (DITA) TC

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

<linktext> is another such element; see http://docs.oasis-open.org/dita/dita/v1.3/errata01/os/complete/part1-base/langRef/base/linktext.html Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) On 5/3/2017 5:12 PM, Robert D Anderson wrote: 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