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: #34 Remove topicset and topicsetref Ready

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.



Eliot Kimber

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
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

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.


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?
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?
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>.


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?


  • 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?


  • 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?


  • 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.



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