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: Stage 2 Proposal 21: Resolve inconsistent class values for <shortdesc>, <linktext>, and <searchtitle> Ready

I have incorporated the review comments and updated proposal in SVN. Proposal is attached.

The actual grammar work has been done and submitted as a pull request to the git repo.


Eliot Kimber

Title: DITA 2.0 proposed feature #21

DITA 2.0 proposed feature #21

Resolve inconsistent class values for <shortdesc>, <linktext>, and <searchtitle>.

Date and version information

Date that this feature proposal was completed
12 March 2018
Champion of the proposal
Robert Anderson
Links to any previous versions of the proposal
Links to minutes where this proposal was discussed at stage 1 and moved to stage 2
Links to e-mail discussion that resulted in new versions of the proposal
Link to the GitHub issue

Original requirement or use case

These elements are the same semantic and thus should have a single consistent @class value across all DITA document types.

Use cases

Remove the need to have separate handling for the different map and topic versions of these elements.

New terminology

No new terminology.

Proposed solution

Move the declarations for <shortdesc>, <linktext>, and <searchtitle> to commonElements, making them available to both maps and topics.


Who will benefit from this feature?
Implementors of DITA processors. Creators of specializations <shortdesc>, <linktext>, or <searchtitle>.
What is the expected benefit?
Simplifies DITA processor implementation by removing the need for special cases for these very common elements. Removes the need for specializers to be careful to select the correct base for their specializations or to be forced to create two different specializations for the same semantic.
How many people probably will make use of this feature?
Affects all DITA processor implementors.
How much of a positive impact is expected for the users who will make use of the feature?
Minor reduction in implementation complexity.

Technical requirements

Renaming or refactoring an element
  • Remove all declarations for <shortdesc>, <linktext> and <linktitle> from mapMod.
  • Move declarations for <shortdesc>, <linktext> and <linktitle> from topicMod to commonElementsMod.
Processing impact
No change
Overall usability
No change

Backwards compatibility

DITA 2.0 is the first DITA release that is open to changes affecting backwards compatibility. To help highlight any impact, does this proposal involve any of the following?

Was this change previously announced in an earlier version of DITA?
Change is new to DITA 2.x
Removing a document type that was shipped in DITA 1.3?
Removing a domain that was shipped in DITA 1.3?
Removing a domain from a document type shell was shipped in DITA 1.3?
Removing or renaming an element that was shipped in DITA 1.3?
Removing or renaming an attribute that was shipped in DITA 1.3?
Changing the meaning of an element or attribute in a way that would disallow existing usage?
Changing a content model by removing something that was previously allowed, or by requiring something that was not?
Changing specialization ancestry?
Yes: Removing map/* versions of the <shortdesc>, <linktext>, and <searchtitle> elements.
Removing or replacing a processing feature that was defined in DITA 1.3?
Are element or attribute groups being renamed or shuffled?

Migration plan

If the answer to any question in the previous section is "yes":

Might any existing documents need to be migrated?
Documents that have literal @class values for these elements will need to either remove the @class attributes from the source or update them to reflect the new @class values. Otherwise existing documents will not be affected.
Might any existing processors or implementations need to change their expectations?
Processors that have processing that looks for the map/* versions of the @class values can remove those checks.
Might any existing specialization or constraint modules need to be migrated?
There are no OASIS-defined specializations of <shortdesc>, <linktext>, or <searchtitle>.
Local specializations can be updated with a simple search and replace to change "map" to "topic" for these three element types.


Outline the impact (time and effort) of the feature on the following groups.

Maintainers of the grammar files
Update grammar files to reflect removal of map/* versions of the files. Work done as part of this Stage 2 proposal.
Editors of the DITA specification
No impact.
Vendors of tools
May need to update tools to remove matches on map/shortdesc, map/linktext, and map/searchtitle.
DITA community-at-large
  • Will this feature add to the perception that DITA is becoming too complex?

    This proposal reduces complexity.

  • Will it be simple for end users to understand?

    Most DITA authors should be completely unaware of the change.

  • If the feature breaks backwards compatibility, how many documents are likely to be affected, and what is the cost of migration?

    Documents that use default @class values will not be affected. Map documents that have literal @class values will need to be updated to either remove the @class attributes or update the values if the @class values must be maintained in the source.

Producing migration instructions or tools
  • How extensive will migration instructions be, if it is integrated into an overall 1.3 â 2.0 migration publication or white paper?

    One or two paragraphs at most.

  • Will this require an independent white paper or other publication to provide migration details?


  • Do migration tools need to be created before this change can be made? If so, how complex will those tools be to create and to use?

    Might be useful to include as part of a general migration tool but definitely not critical.



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