21.3.2 Details of texindex

In Texinfo version 6, released in 2015, the texindex program was completely reimplemented. The principal functional difference is that index entries beginning with a left brace or right brace (‘{’ resp. ‘}’) can work properly. For example, these simple index entries are processed correctly, including the “index initial” shown in the index:

@cindex @{
@cindex @}
...
@printindex cp

However, to enable this behavior, it’s necessary (for the time being) to give a special option to TeX early in a source document:

@tex
\global\usebracesinindexestrue
@end tex

This is because the previous texindex implementation aborted with an incorrect error message (‘No page number in \entry...’) on such index entries when handled in the normal way. Therefore TeX wrote out an incorrect “sort string” using the ‘|’ character; this did not affect the text of the entry, but the index initial was the incorrect ‘|’, and sorting was not perfect.

Because of that fatal error, and because relatively few documents have index entries beginning with braces, we want to provide some transition time for installations to have the new texindex. At some point in the future, we’ll make \usebracesinindexes true by default (the above TeX code will continue to work fine).

Although not a matter of functionality, readers may be interested to know that the new texindex is a literate program (http://en.wikipedia.org/wiki/Literate_programming) using Texinfo for documentation and (portable) awk for code. A single source file, texindex/ti.twjr in this case, produces the runnable program, a printable document, and an online document.

The system is called texiwebjr and was created by Arnold Robbins, who also wrote the new texindex. Not coincidentally, he is also the long-time maintainer of Gawk, see The GNU Awk User’s Guide). The file texindex/Makefile.am shows example usage of the system.