Resolve inconsistent class values for <shortdesc>,
<linktext>, and <searchtitle>.
Date and version information
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.
Benefits
- 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?
- No.
- Removing a domain that was shipped in DITA 1.3?
- No
- Removing a domain from a document type shell was shipped in DITA 1.3?
- No.
- Removing or renaming an element that was shipped in DITA 1.3?
- No.
- Removing or renaming an attribute that was shipped in DITA 1.3?
- No.
- Changing the meaning of an element or attribute in a way that would disallow existing
usage?
- No.
- Changing a content model by removing something that was previously allowed, or by requiring
something that was not?
- No.
- 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?
- No.
- Are element or attribute groups being renamed or shuffled?
- No.
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.
Costs
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
-