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
Original requirement or use case
Remove deprecated/reserved
for future use items (elements and attributes) from the DITA
base
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 |
@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
incommonElements.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
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>
.
- 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:
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>
<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)