DITA Proposed Feature # 42 (and 41)

More flexibility for shortdesc element.

Longer description

Expand the content model of shortdesc to make it equivalent to section; add a subelement to identify a portion of the shortdesc to be used for previews.

Alternatively, add a new element "abstract" that can be authored instead of shortdesc, and which can contain shortdesc (maintaining shortdesc's current processing model intact, but adding an optional container element that can hold a wider variety of content)

Scope

Minor

Use Case

  1. Author wants to create a rich introductory section that includes a bulleted list summarizing the major points in the topic. The summary is appropriate for use in the output for the topic itself, and even for generated summaries in overview topics, but is too big and structured for use in link previews/hoverhelp.
  2. The author puts the content into the new more generic element, and identifies only the final two sentences of the summary as the short description for use in previews.
  3. On output, the entire summary is used in the output for the topic and in the output for overview topics, but only the subelement is used for link previews.
Figure 1. Example - option 1
<topic id="x">
	<title>My topic</title>
	<shortdesc><p>I can have paragraphs.</p>
		<previewpara>And also a special kind of para</previewpara>
	</shortdesc>
	<body>...</body>
</topic>
Figure 2. Example - option 2
<topic id="x">
	<title>My topic</title>
	<abstract><p>I can have paragraphs.</p>
		<shortdesc>And also a special kind of para</shortdesc>
	</abstract>
	<body>...</body>
</topic>

Technical Requirements

Changing the doctype to allow a new peer element of shortdesc similar to section, or changing the doctype to make shortdesc more like section but contain a more restrictive subelement.

Costs

Time to redesign the document types is minimal, and either option allows backwards compatibility.

Implementers will need to update logic for generating summaries and for selecting link previews.

Benefits

Currently the different uses of the shortdesc put some pressure on the author, and can result in compromise introductions/overviews that are longer than strictly appropriate for a link preview, or shorter than would be useful for a generated summary.

Time Required

2 meetings to agree on design.

ca. 1 week to update code.