Next Previous Contents

## 1. General Questions

## 1.1 Why a completely new indexing tool? `makeindex` works fine!

With the International MakeIndex project, Joachim Schrod and Gabor Herr have shown that adding extensions to `makeindex` is a difficult job. Thus we have decided to develop a new indexing tool from scratch. The new tool is based on a new requirements analysis and offers very interesting features for processing very complex indexing schemes. The resulting index model is described in:

1. Roger Kehr, <SF>xindy</SF> -- A Flexible Indexing System, Proceedings of the EuroTeX'98, St. Malo, France, March 1998
2. Roger Kehr, <SF>xindy</SF> -- A Flexible Indexing System, Technical Report No. 11/1997, Computer Science Department, Darmstadt University of Technology, 1997. Also accessible from the xindy homepage.
3. Roger Kehr, xindy Ein Flexibles Indexierungssystem, Studienarbeit FB Informatik, TH-Darmstadt, November 1995.
4. Joachim Schrod, An International Version of MakeIndex, Cahiers GUTenberg, 10, p81-90, 1991
5. Joachim Schrod and Gabor Herr, MakeIndex Version 3.0, Technical University of Darmstadt, 1991

## 1.2 I'm an old `makeindex` wizard. What does <SF>xindy</SF> offer that `makeindex` doesn't?

Here are the most important differences between <SF>xindy</SF> and `makeindex`:

Internationalization

  <SF>xindy</SF> can be configured to process indexes for many languages with different letter sets and different sorting rules. For example, many roman languages such as Italian, French, Portuguese or Spanish contain accentuated letters such as À, Á, ñ. Other languages from northern Europe have letters like Ä, Ø, æ or ß which often can't be processed by many index processors not talking about sorting them correctly into an index. The <SF>xindy</SF>-system can be configured to process these alphabets by defining sort and merge-rules that allow expressing of language specific rules. One example of such a rule would be

      (sort-rule "ä" "ae")

  defining that a word containing the umlaut-a will be sorted as if it contained the letters `ae` instead. This is one form of how the umlaut-a is sorted into german indexes. With an appropriate set of rules one can express the complete rules of a specific language.

Location classes.

  `makeindex` is able to recognize and process arabic numbers, roman numerals and letter-based alphabets as specifiers for the indexed location. Simple composite structures of these are also possible to process. This implicit recognition scheme has completely been dropped in favour of a well-defined and very powerful declaration scheme called location-classes. Thus, <SF>xindy</SF> initally does not know any location-class by default and must be instructed to accept certain location-classes. A typical declaration might look like:

  > `

  >     (define-location-class "page-numbers" ("arabic-numbers"))

  > `

  This declares that page numbers consist of the enumeration of the arabic numbers. The arabic numbers are referred to as alphabets. Users may use the pre-defined alphabets arabic numbers, roman numerals, etc. or define new alphabets as needed. See the tutorial that comes with this distribution for some examples.

The concept of attributes.

  With `makeindex` one can assign a markup to each index entry using the encapsulators (usually following the vertical bar sign in an index entry command). For example in the specification

  > `

  >     \index{xindy|bold}

  > `

  the encapsulator is `bold` which encapsulates the page-numbers in the markup-phase. An additional TeX-macro must be supplied to assign some markup with the page number. This concept has completely been dropped in <SF>xindy</SF> in favour of a more powerful scheme called attributes. Attributes can be used to (i) define several grouping and ordering rules with locations and we can define (ii) markup-tags for the document preparation system.

  The result of this design decision is that the user is required to define the attributes in the style file and not in the document preparation system. The reasons lie in the more powerful markup scheme of <SF>xindy</SF> which can't be specified in the document processor anymore. In fact, the `makeindex`-like markup is only a small subset of <SF>xindy</SF>s features.

Cross references.

  Cross-references were implemented in `makeindex` with the encapsulation mechanism, which only served for markup purposes. This has been completely separated in <SF>xindy</SF>. Here we distinguish cleanly between attributes and cross references. This makes it possible to implement checked cross references, i.e. cross-refernces that can be checked if they point to an existing index entry instead of somewhere ``behind-the-moon''.

Less command-line options.

  <SF>xindy</SF> has dropped the usage of command-line options in favour of a well-defined indexstyle description language. Thus, options that could be activated at the command-line level of `makeindex` must now be specified in the indexstyle file. This sounds more restrictive than it is, because the indexstyle files can be composed from several modules which makes it possible to write style files in just a few lines of code.

Raw index parser.

  The parser built into `makeindex` has completely been separated from the core <SF>xindy</SF> system. <SF>xindy</SF> understands a well-defined specification language for the raw index that is completely different from `makeindex`, but in our opinion more maintainable than the `makeindex` format. This requires a separate filter that transforms arbitrary indexes to the <SF>xindy</SF> format. An example filter is the program `tex2xindy` that comes with this distribution.

Summed up, some of the implicit assumptions made by `makeindex` have been replaced and now burdend to the user. The reason is that many of `makeindex`'s assumptions were no longer valid in multi-language environments or documents with arbitrary location structures. This also characterizes <SF>xindy</SF> more as a framework instead of a end-user-tailored product. One should notice that writing an appropriate index style is an essential part of the document preparation process and should be tailored to each document anew.

Next Previous Contents