DITA Proposed Feature # 12009

Relax the related links content model so it can be empty.

Longer description

The topic document type is overly restrictive in requiring at least one link element within related-links. Relaxing this model would allow the use case described below, which cannot be implemented legally today. While it seems illogical to add a <related-links> element with no links, doing so will not break anything within the topic, so there is no reason to forbid it. Creating the empty element is no worse than creating an empty <prolog> element, which is also not forbidden.

Original request to the TC: http://lists.oasis-open.org/archives/dita/200509/msg00050.html

Original approval for 1.1, before 1.1 was cut down to a short list of items: http://www.oasis-open.org/committees/download.php/14855/TC-Meeting-Minutes-2005-10-04.txt

Scope

Trivial. Need to change + to a * in one DTD file and one Schema file. Need to update content model description in the language specifiecation.

Use Case

An actual use case that we have encountered is a specialization that allows for these specific types of links:
  • one optional link to setup information for the topic
  • one optional link to a zip that contains materials related to the topic
  • one optional link to in-depth information about this topic
  • one optional link to a PDF version of the topic
  • any number of links to bio topics about the authors
  • any number of generic links
Ideally, the content model would look something like this:
(setupLink?, downloadMaterials?, 
 inDepthInfo?, pdfVersion?, authorInfo*, link*)

This content model is not a valid specialization, because no link is required. The workaround is to add an extra required element, a specialization of linkpool, which then allows the necessary model.

Another use case is a topic type that includes links for support information. The user wishes to provide the following content model:
(email*, emailcc*, url*)

This model is also not valid without an extra container. The user chose to simply remove the order requirement rather than create a container, but again this user was not able to get what he wanted.

Technical Requirements

Need to change a line in the DTD and a line in the Schema.

Costs

The time it takes to discuss this issue at the TC. Implementation is trivial, and should not impact DITA tools.

Benefits

Increased flexibility with specialization; ability to accurately describe linking models for a given information type.

Time Required

A few minutes.

Specification impact

Only need to change the description of the content model of <related-links>.