(eplain.info)Index entries with special characters

---

Next: Proofing index terms Prev: Modifying index entries Up: Indexing terms

---

Enter node , (file) or (file)node

4.12.1.3 Index entries with special characters
..............................................

Indexing terms with special characters can become quite cumbersome
because you have to keep both TeX and MakeIndex happy at the same time.
For example, while '!' has no special meaning for TeX, it is a subentry
separator for MakeIndex, therefore you'd have to escape occurrences of
literal '!' in index terms. Things get even more interesting with
characters which are special in both TeX and MakeIndex.

   This in turn has some implications for the non-silent forms of the
indexing commands (Note: Indexing terms), since TeX and MakeIndex use
different conventions for escaping characters. For example, this will
not typeset the exclamation point correctly within the text, while it
will come out right inside the index, after MakeIndex strips the quoting
character ('"'):

     \idx{"!}

This would have to be rewritten using the silent command:

     !\sidx{"!}

In general, it is a good idea to eschew the non-silent commands whenever
index term contains anything unusual.

   To understand this keep in mind that indexing commands read the terms
verbatim so that the terms can embed almost any character, and that's
what gets written into the '.idx' file. The non-silent forms then
typeset the term by rescanning the verbatim copy, hence for the
non-silent commands the term, besides being a valid MakeIndex input,
must also represent a valid TeX input. The silent commands don't have
this restriction--their terms only need to become valid TeX input
_after_ MakeIndex processes the '.idx' file and writes the '.ind' file.
This is what makes the non-silent commands less powerful and more
troublesome when dealing with special characters.

   Here's an example showing that terms for the silent commands can
contain almost any character:

     \sidx[see]{comments}[with %@with \verbatim %"|endverbatim]
       {commenting with \verbatim %"|endverbatim}

We didn't have to escape '%' in the sort string for MakeIndex, while we
had to put it inside the verbatim environment (Note: Verbatim listing)
in the part which MakeIndex will pass back to TeX. Also, we had to
escape the '|' character because it is special for MakeIndex. If you
have trouble understanding the reasons for the different types of
escaping used, it is best to examine the '.idx' and '.ind' files
resulting from processing the above input.

   As was mentioned, index terms can embed "almost any character", so
now we'll describe the exceptions.

   The following characters are reset to their usual meanings because
they are not useful verbatim: multiple consequent spaces are converted
into a single space; ASCII tab characters are treated as spaces; ASCII
return is treated as end-of-line (this means, among other things, that
long terms can be broken across several lines).

   You have to be careful with the begin- and end-group characters ('{'
and '}' by default). If they are matched, you don't have to do anything
special. For example:

     \sidx {braces {, }@braces
       \verbatim {"|endverbatim, \verbatim }"|endverbatim}

However, if they are not matched you have two problems on hand. The
first one is TeX--you have to instruct TeX to use something else as
begin- and/or end-group characters. Eplain provides an easy way to do
this: just define '\idxargopen' and/or '\idxargclose' to the begin- and
end-group characters you are going to use with indexing macros, and use
braces inside index terms without any restrictions. Here's an example:

     \def\idxargopen{`\<}
     \def\idxargclose{`\>}
     \sidx <left brace "{@left brace \verbatim "{"|endverbatim>

In this example we've also dealt with the second problem--braces are
MakeIndex's grouping characters as well (by default), so we have escaped
unmatched braces with '"'.

   And the final note: if you need a subentry containing brackets ('['
and ']'), avoid the optional argument of '\sidx' and friends, and use
instead MakeIndex's subentry separator to create the subentry with the
brackets in it:

     \sidx{entry!subentry with a bracket [}