sort-as

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

Document
Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition
Version
1.3
Author
OASIS DITA Technical Committee

For elements that are sorted, the sort-as element provides text that is combined with the base sort phrase to construct the effective sort phrase. The text can be specified in the content of the sort-as element or in the value attribute on the sort-as element. The sort-as element is useful for elements where the base sort phrase is inadequate or non-existent, for example, a glossary entry for a Japanese Kanji phrase.

Content models

See appendix for information about this element in OASIS document type shells.

The sort-as element can contain text and keyword elements in order to enable content referencing. If a keyword element is used within sort-as, the keyref attribute can be used to set the sort phrase. If a keyword uses keyref and would otherwise also act as a navigation link, the link aspect of the keyref attribute is ignored.

As a specialization of data, the sort-as element is allowed in any context where data is allowed. However, the presence of sort-as within an element does not, by itself, indicate that the containing element should be sorted. Processors can choose to sort any DITA elements for any reason. Likewise, processors are not required to sort any elements. See Sorting for more information on sorting.

Some elements in the base DITA vocabulary are natural candidates for sorting, including topics, definition list entries, and rows in tables and simple tables. Authors are likely to include sort-as elements in the following locations:
  • For topics, the sort-as element can be included directly in title, searchtitle, or navtitle when the different forms of title need different effective sort phrases. If the effective sort phrase is common to all the titles for a topic, the sort-as element can be included as a direct child of the topic prolog anywhere data is allowed.
  • For glossary entry topics, the sort-as element can be included directly in glossterm or as a direct child of prolog.
  • For topic references, the sort-as element can be included directly in the navtitle or title element within topicmeta or as a child of topicmeta.
  • For definition list items, include the sort-as element in the dt element.

Processors SHOULD expect to encounter sort-as elements in the above locations. Processors that sort SHOULD use the following precedence rules:

  • A sort-as element that is specified in a title takes precedence over a sort-as element that is specified as a child of the topic prolog.
  • Except for instances in the topic prolog, processors only apply sort-as elements that are either a direct child of the element to be sorted or a direct child of the title- or label-defining element of the element to be sorted.
  • When an element contains multiple, direct-child, sort-as elements, the first direct-child sort-as element in document order takes precedence.
  • When located within the indexterm element, the sort-as element is equivalent to index-sort-as. It is an error for an indexterm element to directly contain both sort-as and index-sort-as elements.
  • Sort phrases are determined after filtering and content reference resolution occur.

When a sort-as element is specified, processors that sort the containing element MUST construct the effective sort phrase by prepending the content of the sort-as element to the base sort phrase. This ensures that two items with the same sort-as element but different base sort phrases will sort in the appropriate order.

For example, if a processor uses the content of the title element as the base sort phrase, and the title of a topic is "24 Hour Support Hotline" and the value of the sort-as element is "twenty-four hour", then the effective sort phrase would be "twenty-four hour24 Hour Support Hotline".

Inheritance

+ topic/data ut-d/sort-as

Example

The following examples illustrate how a glossary entry for the Chinese ideographic character for "big" might specify an effective sort phrase of "dada" (the Pin-Yin transliteration for Mandarin):

Figure. The sort-as element located within glossterm
<glossentry id="gloss-dada">
  <glossterm><sort-as value="dada"/>&#x5927;&#x5927;</glossterm>
    <glossdef>Literally "big big".</glossdef>
</glossentry>
Figure. The sort-as element within prolog
<glossentry id="gloss-dada">
  <glossterm>&#x5927;&#x5927;</glossterm>
  <prolog>
    <sort-as>dada</sort-as>
  </prolog>
    <glossdef>Literally "big big".</glossdef>
</glossentry>

Attributes

The following attributes are available on this element: Universal attribute group and the attributes defined below.

name
Names the metadata item that the element represents. The default value is "sort-as". Specializations of sort-as can set the default value of the name attribute to reflect the tag name of the specialized element.
value
The value of the metadata item. When the sort-as element has content and the value attribute is specified, the value attribute takes precedence. If the value attribute is not specified and the sort-as element does not contain content, then the sort-as element has no effect.