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. Cheers, E. -- Eliot Kimber
http://contrext.com 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 N/A Links to minutes where this proposal was discussed at stage 1 and moved to stage 2
https://lists.oasis-open.org/archives/dita/201705/msg00022.htmlhttps://lists.oasis-open.org/archives/dita/201705/msg00022.html Links to e-mail discussion that resulted in new versions of the proposal N/A Link to the GitHub issue
https://github.com/oasis-tcs/dita/issues/21https://github.com/oasis-tcs/dita/issues/21 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 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? No. 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. Examples N/A.