Remove topicset and topicsetref.
Date and version information
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
-
- 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.