`<sort-as>`

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 1. 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 2. 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.