`<sort-as>`

The <sort-as> element can be used to specify an effective sort phrase when the base sort phrase is not appropriate for sorting, for example, Japanese characters. This element prepends text to the base sort phrase in order to construct an effective sort phrase.

Usage information

Sort 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 also useful for elements where the base sort phrase is inadequate or non-existent, such as an index entry for a Japanese Kanji phrase.

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.

Some elements in the base DITA vocabulary are natural candidates for sorting, including topics, definition list entries, index 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> or <titlealt> 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 <prolog> element in the topic.
For topic references, the <sort-as> element can be included directly in the <titlealt> element with a @title-role of navigation, such as <navtitle>, within <topicmeta> or as a child of <topicmeta>.
For glossary entry topics, the <sort-as> element can be included directly in <glossterm> or as a direct child of the <prolog> element.
For definition list items, the <sort-as> element can be included in the <dt> element.
For index entries, the <sort-as> can be included as a child of <indexterm>. In a multilevel <indexterm> element, the <sort-as> element only affects the level in which it occurs.

Processing expectations

If the @value attribute is not specified and the <sort-as> element does not contain content, then the <sort-as> element has no effect.

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 necessarily 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.

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.
It is an error if there is more than one <sort-as> child for a given <indexterm> element.
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".

Specialization hierarchy

The <sort-as> element is specialized from <data>. It is defined in the utilities-domain module.

Content model

(Text | <text> | <keyword> )*

Zero or more

Attributes

The following attributes are available on this element: universal attributes, @name, and @value.

For this element,

The @name attribute has a default value of sort-as.
The @value attribute specifies text to combine with the base sort phrase to create an effective sort phrase. When the <sort-as> element has content and the @value attribute is specified, the @value attribute takes precedence.

The following attributes are available on this element: universal attributes and the attributes defined below.

@name (data-element attributes): Defines a unique name for the object.; The @name attribute has a default value of sort-as.
@value (data-element attributes): Specifies a value associated with the current property or element.; The @value attribute specifies text to combine with the base sort phrase to create an effective sort phrase. When the <sort-as> element has content and the @value attribute is specified, the @value attribute takes precedence.

Example

This section is non-normative.

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):

Example 1. <sort-as> within <glossterm>

In the following code sample, the <sort-as> element is located within the <glossterm> element:

<glossentry id="gloss-dada">
  <glossterm>
    <sort-as value="dada"/>
    &#x5927;&#x5927;
  </glossterm>
  <glossdef>Literally "big big".</glossdef>
</glossentry>

Example 2. <sort-as> within <prolog>

In the following code sample, the <sort-as> element is located within the <prolog> element of the glossary entry topic:

<glossentry id="gloss-dada">
  <glossterm>&#x5927;&#x5927;</glossterm>
  <glossdef>Literally "big big".</glossdef>
  <prolog>
    <sort-as>dada</sort-as>
  </prolog>
</glossentry>