6.5 Special Effects

In the normal case entries such as

\indexentry{alpha}{1}  
\indexentry{alpha!beta}{3}  
\indexentry{alpha!beta!gamma}{10}

in the raw index file will be converted to

\item alpha, 1 
  \subitem beta, 3 
    \subsubitem gamma, 10

in the output index file by Make-Index. Notice that the level symbol (!) is used to delimit levels of nesting.

It is possible to make an item appear in a designated form by using the actual (@) operator. For instance,

\indexentry{alpha@{\it alpha\/}}{1}

will become

\item {\it alpha\/} 1

after the conversion. The idea is that the pattern preceding @ is used as sort key, whereas the one following it is put in the actual result. However, the same key with and without the actual part are regarded as distinct entries.

It is also possible to encapsulate a page number with a designated command using the encap (|) operator. For example, in the default case,

\indexentry{alpha|bold}{1}

will be converted to

\item alpha \bold{1}

where \bold{n} will expand to {\bf n}. This allows the encap operator to be used to set pages in different fonts, thereby conveying more information about whatever being indexed. For instance, given the same key the page where its definition appears can be in one font while where its primary example is given can be in another, with other ordinary appearances in a third. Notice that in this example, the three output attributes associated with page encapsulation encap_prefix, encap_infix, and encap_suffix correspond respectively to backslash, left brace, and right brace. If this is to be formatted by languages other than , they would be defined differently.

By the same token, the encap operator can be used to make cross references in the index. For instance,

\indexentry{alpha|see{beta}}{1}

will become

\item alpha \see{beta}{1}

in the output index file after the conversion, where

\see{beta}{1}

will expand to

{\it see\/} beta

Notice that in a cross reference like this the page number disappears. Therefore, where to insert such a command in the source is immaterial.

A pair of encap concatenated with range_open (|() and with range_close (|)) creates an explicit page range. That is,

\indexentry{alpha|(}{1}  
\indexentry{alpha|)}{5}

will become

\item alpha, 1--5

Intermediate pages indexed by the same key will be merged into the range implicitly. This is especially useful when an entire section about a particular subject is to be indexed, in which case only the range opening and closing operators need to be inserted at the beginning and end of the section, respectively.

This explicit page range formation can also include an extra command to set the page range in a designated font. Thus

\indexentry{alpha|(bold}{1}  
\indexentry{alpha|)}{5}

will become

\item alpha, \bold{1--5}

A couple of special cases are worth mentioning here. First, entries like

\indexentry{alpha|(}{1}  
\indexentry{alpha|bold}{3}  
\indexentry{alpha|)}{5}

will be interpreted as

\item alpha, \bold{3}, 1--5

but with a warning message in the transcript about the encounter of an inconsistent page encapsulator. Secondly, an explicit range beginning in a Roman page number and ending in Arabic is considered an error. In a case like this the range is broken into two subranges, if possible, one in Roman, the other in Arabic. For instance,

\indexentry{alpha|(}{i}
\indexentry{alpha}{iv}
\indexentry{alpha}{3}
\indexentry{alpha|)}{7}

will be turned into

\item alpha, 1--iv, 3--7

with a warning message in the transcript complaining about the illegal range formation.

Finally, every special symbol mentioned in this section may be escaped by the quote operator ("). Thus

\indexentry{alpha"@beta}{1}

will actually become

\item alpha@beta, 1

as a result of executing Make-Index. However, if quote is preceded by escape (\), its following letter is not escaped. That is,

\indexentry{f\"ur}{1}

means

\item f\"ur, 1

which represents umlaut accented u to the family of processors.