DITA 1.3 proposed feature 13117

Allow <xref> within <shortdesc>.

Date and version information

Include the following information:

Original requirement

Some users have a need for cross references within short descriptions. As short descriptions may include elements that act as links as of DITA 1.2, there is no reason to disallow <xref>, as processors must already handle links within short descriptions.

Use cases

Use cases include:
  • A topic whose only content is a short description that points to another topic as the real source of information for some purpose.
  • A topic where the first sentence of the first paragraph happens to include a cross reference and needs to be the short description.

Benefits

This change ensures that the content model of <shortdesc> is not over constrained, allowing authors who need to have a cross reference in a short description to do so without having to wrap the cross reference in another element (e.g., <ph>).

Costs

  • Maintainers of the DTDs and XSDs:
    • Add <xref> the content model of <shortdesc>.
  • Editors of the DITA specification:
    • How many new topics will be required?
      • No new topics
    • How many existing topics will need to be edited?
      • The generated content model description for <shortdesc> will reflect the addition of <xref>.
    • Will the feature require substantial changes to the information architecture of the DITA specification?
      • The feature does not represent a substantial change to the architecture.
  • Vendors of tools:
    • XML editors will need to allow editing of the updated content models.
    • Processors may need to provide additional rules for handling cross references within short descriptions when using the short description content to produce text for use in contexts where a navigable cross reference would not be possible or meaningful, such as tooltips in HTML.
  • DITA community-at-large. Will this feature add to the perception that DITA is becoming too complex?
    • This change should not add to the perception of complexity for authors.

Technical requirements

Update the existing content models as described above under "costs".

Processors will need to provide appropriate ways to render cross references within short descriptions when the short description text is used in contexts where a navigable cross reference would not be possible or meaningful. Processors should always reflect appropriate text for the cross reference even if the cross reference cannot be rendered as a navigable hyperlink in a particular context.

Examples

Short description as a redirection:

<topic id="topic_lxq_jnf_5g">
  <title>Old Concept Title</title>
  <shortdesc>Old concept is now new concept. See 
<xref keyref="new-concept"/>.</shortdesc> 
  ....
</topic>