Index sorting

Each index is regarded as a series of entries, where an entry consists of a <tl:ndxN> (N=1 to 9) which in turn consists of a <tl:title> (entry text) and a <tl:folio> (page reference). Note that <tl:folio> is honored only at the lowest level of each entry group, higher level entries are generally regarded as headings only.

By default, TopLeaf leaves your index unsorted. To obtain a sorted index, add the <index-sorter> command to the pre-content box of your $document mapping. This command may contain the following attributes:


This is a two-letter language code which determines the sorting rules to use. If this is omitted the language/locale set by the content will be used.


This is a locale code in the form “xx-XX” which determines the sorting rules to use. If this is omitted the language/locale set by the content will be used.


If this is yes (the default) sorting of index entries is case-insensitive. If it is no upper-case names will sort before lower-case.


If this is yes (the default) spaces are ignored for the purposes of sorting. For example, setting this to no will cause “et cetera” to sort before “eta”.


If this is yes (the default) punctuation characters are ignored when sorting. For example, if punctuation is ignored “AC/DC” will be sorted as if it were “ACDC”.

If this is inner punctuation at the start of an entry is used for sorting, but punctuation within the entry is ignored. This allows entries like “+ (addition)” to sort to the front.

If this is no all punctuation is used when sorting.


If this is yes (the default) strings of digits are sorted by their numeric value rather than as a sequence of characters. For example, setting this to yes will produce “9”, “13”, “124” while selecting no will produce “124”, “13”, “9”.


This is one or more tag names (separated by commas) that are used to set the sort key for the entry. If one of these tags is found, it is removed and its content is used to determine the position of the index item.


This defines a tag used to create the first page of a range. See below for more information.


This defines a tag used to create the last page of a range. See below for more information.


If this is yes (the default) the sorted output will contain information to indicate when a new group of entries starts. See below for more information.


If this is yes (the default) grouping is determined by the unaccented (“base”) first letter of the entry. For example, if this is yes then “Österreich” will be grouped under “o”.


This is the index level used for “see” items. See below for more information.


This is the index level used for “see also” items. See below for more information.


This controls whether markup is added to facilitate the creation of links for “see” and “see also” items. The default of no does not create links. If this is yes links are created if the target item is found. If it is all links are also added if the target does not exist. See below for more information.


This is the name of the tag used to separate levels in the “see” and “see also” text.


This is a prefix added to the link/target strings used for “see” and “see also” links. If you use hyperlinks elsewhere you can set this to a value which will make these distinct from other link strings.

[Note] Note

Older stylesheets may use the deprecated <index-sort> command. This has less functionality than the new command, and is not suitable for languages other than English.


If grouping is selected the sorter also inserts an element to identify when the first letter of the top-level entry changes, for example:

<tl:grouping letter="a"/>

In most cases the letter attribute is a single lower-case letter. If the first character is not alphabetic, the letter attribute value will be empty and a type attribute will be added with the value “numeric” if the first character of the index entry is a digit, or “symbol” if the entry starts with some other character (such as punctuation).


A range indicates an inclusive range of pages that relate to the index item. To create a range there must be a start item that determines the first page, and an end item for the last page. These two items are connected by a range key which is a string unique to that range.

To create ranges, you must define values for the startrange-tag and endrange-tag attributes of the index-sorter command. Both of these attributes contain either a tag name, or a tag name and attribute name separated by ‘@’. The range key value is the text of the element if just a tag name is given, or the attribute value if both are specified.

The text that appears in the sorted index is taken from the start item. The content of the end item is ignored.

A range appears as a single tl:folio element. The end page is contained in a tl:endrange element within the tl:folio.

For example, using the following command:

<index-sorter startrange-tag="range" endrange-tag="end@id"/>

and these level-1 index values in the data:

<index1>farm animals<range>XYZ</range></index1>
<index1><end id="XYZ"/></index1>

produces the following in the sorted index:

  <tl:title>farm animals</tl:title>

See and See Also items

It’s common for an index to contain items that direct the reader to an alternate item, for example:

       See Cows

or to items that contain related information, such as:

    Cows, 23, 29
       See Also Dairy farming

These are referred to below as “see” and “see also” items, respectively.

A common convention is that when a “see” item is present it should be the only item for that index item. However, the index sorter does not require that you follow this convention.

The index sorter allows you to reserve a level in the index hierarchy for each of these item types. The only restriction on the choice of number is that you may not use levels with a higher number for index entries. For example, if you choose level 3 for “see” items, then only levels 1 and 2 are available for use. The recommended approach is to use level 8 for “see” items and level 9 for “see also”.

You must define mappings that assign content to these levels in the Content tab of the mapping.

The index sorter generates the <tl:ndx-see> and <tl:ndx-seealso> elements to represent these items. The above examples would generate data like this:



    <tl:folio id="tl:pub1177.26">23</tl:folio>
    <tl:folio id="tl:pub1177.41">29</tl:folio>

      <tl:title>Dairy farming</tl:title>

The sorter can also add information into the generated index which makes it easy to create a link from a “see” or “see also” item to the referenced index item. To enable this, set the seelink-enable attribute to yes or all. Setting the attribute to all creates a link even if the target item cannot be found, so you can check for missing index items.

Links are created by making a sort key from the “see” text and locating the item with a matching sort key. If the reference is to a lower-level item, it is necessary to use a tag to identify the text of each lower level. Use the seelink-leveltag attribute to specify the name of the tag used.

A link is created by adding a ref attribute to the <tl:ndx-see> or <tl:ndx-seealso> element. The link target is created by adding an id attribute to the corresponding <tl:ndxline>. See the Content tab of the Mapping Guide for information on how to create links and targets from attribute values.

The following fragment shows an example of this, using <level> to identify the levels:


    <tl:ndxline id="tl.see.000002">
      <tl:folio id="tl:Template.25">2</tl:folio>


  <tl:ndx-see ref="tl.see.000002">