Formatting conventions in the XHTML version of the specification

Given the size and complexity of the specification, it is not generated as a single XHTML file. Instead, each DITA topic is rendered as a separate XHTML file. The XHTML version of the specification uses certain formatting conventions to aid readers in navigating through the specification and locating material easily: Link previews and navigation links.

Link previews

The DITA specification uses the content of the DITA <shortdesc> element to provide link previews for its readers. These link previews are visually highlighted by a border and a colored background. The link previews are not normative; they contain the content of the <shortdesc> element for the child topic, which is rendered in a normative context as the first paragraph of the topic; the content is identical in both renditions. The link previews serve as enhanced navigation aids, enabling readers to more easily locate content. This usability enhancement is one of the ways in which the specification illustrates the capabilities of DITA and exemplifies DITA best practices.

The following screen capture illustrates how link previews are displayed in the XHTML version of the specification:

Link previews

Screenshot fragment showing three short portions of text with titles. Each title includes a chapter/section number such as 2.2.1, and is visually styled as a hyperlink (blue and underlined).

Navigation links

To ease readers in navigating from one topic to another, each XHTML file generated by a DITA topic contains the following navigation links at the bottom:

Parent topic
Takes readers to the parent topic, which the topic referenced by the closest topic in the containment hierarchy
Previous topic
Takes readers to the previous topic in the reading sequence
Next topic
Takes readers to the next topic in the reading sequence
Return to main page
Takes readers to the place in the table of contents for the current topic in the reading sequence

The following screen capture illustrates how navigation links are displayed in the XHTML version of the specification:

Navigation links

Screenshot fragment showing three labeled hyperlinks plus the sentence 'Return to main page' with 'main page' styled as a hyperlink (blue and underlined). The first three hyperlinks are labeled 'Parent topic', 'Previous topic', and 'Next topic', and each hyperlink text consists of a chapter/section number along with a topic title.

When readers hover over the navigation links, the short description of the DITA topic also is displayed.

Was this helpful?