OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Updated stage 2 proposal: #36 (Remove deprecated features)


Changes marked in red; primary change is to add @title on <map>
---------------------------------------------------------------------------


DITA 2.0 stage two proposal: #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
02
Completion date
Stage two proposal sent to DITA TC on 1 February 2019. First revision on 19 February 2018.
Proposal champion
Kristen James Eberlein, Eberlein Consulting LLC
Links to any previous versions of the proposal
https://lists.oasis-open.org/archives/dita/201802/msg00006.html
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 incommonElements.mod. Undefined and reserved for future use None
@role="sample" and @role="external" %relational-atts; and %rel-atts; intopic.mod Deprecated since DITA 1.0 None
@title on <map> mapGroup.mod Deprecated since DITA 1.1 <title>
@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.1
  • @title on <map>
Figure 5. Elements and attributes deprecated in DITA 1.2
  • @navtitle
  • @longdescref on <image>
  • @type="internal" and @type="external" on <lq>
Figure 6. Elements and attributes deprecated in DITA 1.3
  • @print
Figure 7. Impact to specialization modules

If implementations have specialized from <boolean> or <indextermref>, they will need to redefine the specialization base.

Figure 8. 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:

  • 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>
    • <map>
    • <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

The DITA TC will deliver a separate document that contains migration information.

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>
@longdescrefon < 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>
@title on <map>
<map id="mybats" title="Bats>
  <topicref href="" type="topic">
    <topicref href="" type="task"/>
    <topicref href="" type="task"/>
    <topicref href="" type="concept"/>
    <topicref href="" type="reference"/>
    <topicref href="" type="reference"/>
  </topicref>
</map>
<map id="mybats">
  <title>Bats</title>
  <topicref href="" type="topic">
    <topicref href="" type="task"/>
    <topicref href="" type="task"/>
    <topicref href="" type="concept"/>
    <topicref href="" type="reference"/>
    <topicref href="" type="reference"/>
  </topicref>
</map>
--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]