<sort-as>

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

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.