DITA 2.0 proposed feature #36 Remove elements and attributes that have been designated as deprecated, reserved for future use, or defined by mistake and retained only to maintain backwards compatibility Date and version information Proposal version 1 Completion date 1 February 2018 Proposal champion Kristen James Eberlein, Eberlein Consulting LLC Initial suggestion The stage one proposal was sent to the TC list on 6 June 2017:
https://lists.oasis-open.org/archives/dita/201706/msg00016.html . It was discussed and moved to stage two on 6 June 2017. GitHub issue
https://github.com/oasis-tcs/dita/issues/36 Original requirement or use case Remove deprecated/reserved for future use items (elements and attributes) from the DITA base Use cases Not applicable New terminology None Proposed solution Modify the grammar files and documentation to remove elements and attributes that have been designated as deprecated, reserved for future use, or defined by mistake and retained only to maintain backwards compatibility Benefits Reduced technical debt Technical requirements Figure 1. Element types to be removed Element type Module in which the element is defined Status Replacement <boolean> commonElements.mod Deprecated since DITA 1.0 <state> <indextermref> commonElements.mod Reserved for future use None Figure 2. Attributes to be removed Attribute type Module in which the attribute is defined Status Replacement @alt commonElements.mod Deprecated since DITA 1.0 <alt> @collection-type = tree on <linkpool> and <linklist> topic.mod Deprecated. Only present in DTDs, not XSD or RNG. None @collection-type on <reltable> and <relcolspec> The elements are defined in map.mod . Both attribute declaration groups reference the %topicref-atts-no-toc-no-keyscope; entity. Undefined and reserved for future use None @keyref on <navref> map.mod “… unintentionally defined for <navref> in the original DITA grammar files. It is retained for backwards compatibility. The attribute will be removed in a future release, and processors are not expected to support it.” None @locktitle on <topichead> and <topicgroup> <topichead> and <topicgroup> are defined in mapGroup.mod. In each case, the % %topicref-atts;; entity is referenced. Housekeeping to correct an unintentional mistake; the attribute was present only because attribute definitions were reused between several elements None @longdescref on <image> commonElements.mod Deprecated since DITA 1.2 <longdescref> @navtitle map.mod Deprecated since DITA 1.2 <navtitle> @print map.mod Deprecated since DITA 1.3 @deliveryTarget @query <topicref> : map.mod <anchorref> , <mapref> , <topicset> , <topicset ref> , and <keydef> : mapGroup.mod <link> : topic.mod Declared but never defined None @refcols The attribute is declared in the %simpletable.attributes; group in commonElements.mod . Undefined and reserved for future use None @role = sample and @role = external %relational-atts; and %rel-atts; in topic.mod Deprecated since DITA 1.0 None @type = internal and @type = external on <lq> commonElements.mod Note: While @type = internal is listed as deprecated in the DITA 1.3 spec, it is not a defined attribute value in commonElements.mod Deprecated since DITA 1.2? @scope and @format on <lq> Backwards compatibility Figure 3. Elements and attributes deprecated in DITA 1.0 @alt <boolean> @role = sample and @role = external Figure 4. Elements and attributes deprecated in DITA 1.2 @navtitle @longdescref on <image> @type = internal and @type = external on <lq> Figure 5. Elements and attributes deprecated in DITA 1.3 @print Figure 6. Impact to specialization modules If implementations have specialized from <boolean> or <indextermref> , they will need to redefine the specialization base. Figure 7. Impact to constraint modules The following constraint modules will need to be refactored: Constraint modules that include <boolean> or <indextermref> in a content model. Constraint modules that list any of the deprecated attributes. This will most likely to be encountered in regard to @alt , @navtitle , and @print . Migration plan For most cases, migration could be handled by any of the following methods: Search and replace across the body of DITA topics and maps Prebuilt XLST scripts Implementation that use the @print attribute will need to do more comprehensive rework of their information architecture. This might include the following: Determining values for use with the @deliveryTarget attribute (Optional) Developing a subjectScheme map to control values for the @deliveryTarget attribute Developing or modifying DITAval files to include or exclude content tagged with specific values for the @deliveryTarget attribute Costs This feature will have an impact on the following: Maintainers of the grammar files The following grammar files will need to be edited: commonElements.mod map.mod mapGroup.mod metaDecl.mod topic.mod A new entity will need to be created for use on <reltable> and <relcolspec> . A new entity will need to be created for use on <topicgroup> and <topicgroup> , which currently reference the % %topicref-atts;; entity. Editors of the DITA specification The following topics will need to be added or removed: One new topic about migrating from DITA 1.3 to DITA 2.0 Remove the following topics from DITA maps: <boolean> <indextermref> This proposal will affect all of the following topics (and probably others that I missed). The @navtitle attribute appears in MANY examples. Edits to the following element-reference topics: 3.3.1.4 <anchor> <anchorref> 3.6.1.10 <attributedef> Base DITA elements, A to Z 3.6.1.8 <enumerationdef> 3.6.1.3 <hasInstance> 3.6.1.4 <hasKind> 3.6.1.5 <hasNarrower> 3.6.1.6 <hasPart> 3.6.1.7 <hasRelated> 3.5.1.3 <hazardsymbol> <image> <keydef> <link> <linklist> <linkpool> <lq> 3.2.2.25 <object> <mapref> <navref> 3.2.1.5 <navtitle> 3.2.2.1 <alt> 3.6.1.15 <relatedSubjects> <relcolspec> <reltable> <resourceid> Simpletable attributes 3.3.2.5 <topichead> 3.4.1.14 <metadata> 3.6.1.14 <subjectdef> 3.6.2.1 <subjectref> 3.6.1.1 <subjectScheme> 3.6.1.2 <schemeref> 3.6.2.2 <topicapply> <topicgroup> <topichead> <topicref> <topicset> <topicsetref> 3.6.2.3 <topicsubject> 3.6.2.4 <topicSubjectTable> 3.10.1.2 Metadata attribute group 3.10.3 Attributes common to many map elements 3.10.12 Topicref element attributes group 3.10.13.5.1 Using the -dita-use-conref-target value Edits to the following appendix topics: Element-by-element recommendations for translators: Base edition Edits to the following architectural specification topics: 2.2.2.4 DITA map attributes 2.2.2.5.4 Example: How the @cascade attribute functions 2.2.3.6 Scaling a list of controlled values to define a taxonomy 2.2.3.8.1 Example: How hierarchies defined in a subject scheme map affect filtering 2.2.3.8.2 Example: Extending a subject scheme 2.2.3.8.3 Example: Extending a subject scheme upwards 2.2.3.8.4 Example: Defining values for @deliveryTarget 2.2.4.2.1 Conditional processing attributes 2.2.4.4 Cascading of metadata attributes in a DITA map 2.2.4.5 Reconciling topic and map metadata elements 2.2.4.6.1 Cascading of attributes from map to map 2.3.4.9 Processing key references to generate text or link text [ @alt ] 2.4.1.1 Table of contents 2.4.3.4 Conditional processing to generate multiple deliverable types 2.4.5.2 Chunking examples 2.6.3.3 DTD: Coding requirements for element type declarations 2.6.4.3 RELAX NG: Coding requirements for element type declarations 2.3.4.9 Processing key references to generate text or link text No changes to the basic information architecture of the specification No new terminology Vendors of tools: XML editors, component content management systems, processors, etc. If tool vendors have built features around any of the deprecated items, those features will need to be migrated to use alternate markup. DITA community-at-large Removing the @navtitle and @print attributes is likely to have the greatest impact. While DITA maps that contain @navitle attributes could be automatically rewritten to use <navitle> elements, reworking maps that use the @print attribute will require more fundamental architectural rework. DITA migration procedures or tools Migration procedures can be covered in a Migrating from DITA 1.3 to DITA 2.0 topic cluster; It is possible that a separate document might be needed to cover migration procedures. It is possible that the TC should provide some basic scripts to make migration easier. Examples The following table contains examples of code that contains deprecated elements and attributes; it also provides example of how the code could be constructed in DITA 2.0. Deprecated item DITA 1.3 markup DITA 2.0 markup @alt <image href= alt= Two-wheeled bicycle /> <image href= <alt>Two-wheeled bicycle</alt> </image> <boolean> She said <boolean state= yes /> when I asked her to marry me! <step><cmd>Verify the presence of an on or high condition at the input gate (ie, <state name= inflag value= high />)</cmd></step> @print <topicref href= print= no > <topicref href= deliveryTarget= Web-only > @navtitle <subjectScheme> <subjectdef keys= os navtitle= Operating system > <subjectdef keys= linux navtitle= Linux > <subjectdef keys= redhat navtitle= RedHat Linux /> <subjectdef keys= suse navtitle= SuSE Linux /> </subjectdef> <subjectdef keys= windows navtitle= Windows /> <subjectdef keys= zos navtitle= z/OS /> </subjectdef> <enumerationdef> <attributedef name= platform /> <subjectdef keyref= os /> </enumerationdef> </subjectScheme> <subjectScheme> <subjectdef keys= os > <topicmeta> <navtitle>Operating systems</navtitle> </topicmeta> <subjectdef keys= linux > <topicmeta> <navtitle>Linux</navtitle> </topicmeta> <subjectdef keys= redhat > <topicmeta> <navtitle>RedHat Linux</navtitle> </topicmeta> </subjectdef> <subjectdef keys= suse > <topicmeta> <navtitle>SUSE Linux</navtitle> </topicmeta> </subjectdef> </subjectdef> <subjectdef keys= windows > <topicmeta> <navtitle>Windows</navtitle> </topicmeta> </subjectdef> <subjectdef keys= zos > <topicmeta> <navtitle>z/OS</navtitle> </topicmeta> </subjectdef> </subjectdef> <enumerationdef> <attributedef name= platform /> <subjectdef keyref= os /> </enumerationdef> </subjectScheme> @longdescref on < image> <image href= longdescref=
http://www.example.org/birds/puffin.html > <alt>Puffin pigure</alt> </image> <image href= > <alt>Puffin pigure</alt> <longdescref href= class= moz-txt-link-rfc2396E href=
http://www.example.org/birds/puffin.html >
http://www.example.org/birds/puffin.html scope= external format= html /> </image> -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)