Proposal 34, Remove topicset and topicsetref has been reviewed by Tom Magliery and his corrections have been incorporated. The updated proposal is in SVN and is attached. I've already done the work on the grammars and DITA source and submitted as a pull request to the git repo, although that pull request is now quite out of date. But the work has been done. Cheers, E. -- Eliot Kimber
http://contrext.com Title: DITA 2.0 proposed feature #34 DITA 2.0 proposed feature #34 Remove topicset and topicsetref. Date and version information Date that this feature proposal was completed 11 March 2018 Champion of the proposal Eliot Kimber 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/201706/msg00013.htmlhttps://lists.oasis-open.org/archives/dita/201706/msg00013.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/34https://github.com/oasis-tcs/dita/issues/34 Original requirement or use case The <topicset> and <topicsetref> elements seem to provide very little value over ordinary <topicref> elements. In addition, they regularly suggest to authors that they should result in some sort of standard special processing (which they do not). The semantic of <topicset> was never clearly distinguished from any other use of topic reference elements to group topicrefs (e.g., <topicgroup> ). The semantics of the <topicsetref> element were never clearly defined in a way that was not tied directly to specific delivery tools (i.e., Eclipse help). Map references and the DITA 1.3 cross-deliverable linking facility appear to satisfy all the requirements implied for <topicsetref> . As far as can be determined, there are no DITA processors in general use that provide any special processing for <topicset> or <topicsetref> . Use cases This removes elements. No usage use case. New terminology No new terminology. Proposed solution Remove the <topicset> and <topicsetref> elements from the grammars and all specification topics that reference them. Benefits Who will benefit from this feature? All DITA users currently confused by the presence of these elements. DITA tool implementors who have no idea how to implement these elements correctly or worry about having ignored a DITA feature by not implementing them. What is the expected benefit? Reduced complexity. How many people probably will make use of this feature? N/A How much of a positive impact is expected for the users who will make use of the feature? Hard to quantify impact of removing an element that few if any DITA users are using. Will reduce the set of <topicref> specializations one has to consider when learning about or authoring DITA maps. Technical requirements Grammar and specification changes Remove <topicset> and <topicsetref> from the Map Group domain: Remove from mapGroupDomain.rng Remove from mapGroup.ent Remove from mapGroup.mod Remove from mapGroupMode.xsd Update the following topics to remove references to <topicset> and <topicsetref> : ditamap-elements.dita commonNavLibraryTable.dita base-elements-a-to-z.dita all-elements-a-to-z.dita map-group-elements.ditamap Regenerate content model files to reflect removal from grammar files. Remove the following topics entirely: langRef/base/topicsetref.dita langRef/base/topicset.dita Processing impact Any processor that actually provides special processing for <topicset> or <topicsetref> can remove it. If a processor provides unique processing for <topicset> or <topicsetref> for which support needs to be retained, the processor will need to either provide its own specializations to which the processing can then be applied or provide some other way to signal the desired behavior, for example, processor-specific values for @outputclass . Overall usability No impact. Backwards compatibility Was this change previously announced in an earlier version of DITA? No. Removing or renaming an element that was shipped in DITA 1.3? The <topicset> and <topicsetref> elements will be removed, so any documents currently using them cannot be valid against the DITA 2.0 grammars as provided by OASIS. Migration plan Might any existing documents need to be migrated? Anyone currently using these elements will need to either replace them with normal topicrefs or define their own specializations to replace <topicset> or <topicsetref> . Might any existing processors or implementations need to change their expectations? If a processor provides unique processing for <topicset> or <topicsetref> for which support needs to be retained, the processor will need to either provide its own specializations to which the processing can then be applied or provide some other way to signal the desired behavior, for example, processor-specific values for @outputclass . As far as the TC can determine, there are no implementations of <topicset> or <topicsetref> in general use. Might any existing specialization or constraint modules need to be migrated? In the unlikely event that there are specializations of <topicset> or <topicsetref> , those specializations will need to be redefined to either specialize directly from <topicref> or another suitable <topicref> specialization, such as <mapref> , or define a new domain module that provides the equivalent of <topicset> and <topicsetref> to then serve as the specialization base of the specializations of <topicset> and <topicsetref> . Costs Maintainers of the grammar files Remove all declarations and comments that mention or use <topicset> or <topicsetref> (already done as part of this Stage 2 proposal). Regenerate content model topics and any generated navigation lists to reflect the removal (inherent in work that will have to be done for DITA 2.0 in any case). Editors of the DITA specification How many new topics will be required? None How many existing topics will need to be edited? Five authored topics (see above) plus removal of topicrefs from one map. (Work already done as part of this Stage 2 proposal) Will the feature require substantial changes to the information architecture of the DITA specification? If so, what? No architectural change required. If there is new terminology, is it likely to conflict with any usage of those terms in the existing specification? No new terminology. Vendors of tools Tool vendors will need ensure that there are not any hard-coded references to the <topicset> and <topicsetref> elements. Any processing specific to those elements will need to either be removed or rebound to different elements or ways of signaling the need for the special processing, whatever it might be. DITA community-at-large Will this feature add to the perception that DITA is becoming too complex? It should not as we are removing a confusing and largely unused element. Will it be simple for end users to understand? Yes. If the feature breaks backwards compatibility, how many documents are likely to be affected, and what is the cost of migration? There should be few documents using <topicset> or <topicsetref> . Those that are can very likely simply replace their use with normal <topicref> elements. 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? Migration instructions should not require more than a paragraph or two 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? It might be useful to include a general <topicset> and <topicsetref> to <topicref> transform as part of a general migration tool. Examples N/A