summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/doc/faq-1.html
blob: 31fcfba7abdf20877f90fa52f3d38073828a2e08 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>XINDY FAQ: General Questions</TITLE>
 <LINK HREF="faq-2.html" REL=next>

 <LINK HREF="faq.html#toc1" REL=contents>
</HEAD>
<BODY>
<A HREF="faq-2.html">Next</A>
Previous
<A HREF="faq.html#toc1">Contents</A>
<HR>
<H2><A NAME="s1">1. General Questions</A></H2>

<H2><A NAME="ss1.1">1.1 Why a completely new indexing tool? <CODE>makeindex</CODE> works fine!</A>
</H2>

<P>
<P>With the <EM>International MakeIndex</EM> project, Joachim Schrod and
Gabor Herr have shown that adding extensions to
<CODE>makeindex</CODE> 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:
<P>
<OL>
<LI> Roger Kehr, <SF>xindy</SF> -- <EM>A Flexible Indexing System</EM>,
Proceedings of the EuroTeX'98, St. Malo, France, March 1998
</LI>
<LI> Roger Kehr, <SF>xindy</SF> -- <EM>A Flexible Indexing System</EM>,
Technical Report No. 11/1997, Computer Science Department, Darmstadt
University of Technology, 1997. Also accessible from the xindy
homepage.
</LI>
<LI> Roger Kehr, xindy <EM>Ein Flexibles Indexierungssystem</EM>,
Studienarbeit FB Informatik, TH-Darmstadt, November 1995.
</LI>
<LI> Joachim Schrod, <EM>An International Version of MakeIndex</EM>,
Cahiers GUTenberg, 10, p81-90, 1991
</LI>
<LI> Joachim Schrod and Gabor Herr, <EM>MakeIndex Version 3.0</EM>,
Technical University of Darmstadt, 1991
</LI>
</OL>
<P>
<P>
<P>
<H2><A NAME="ss1.2">1.2 I'm an old <CODE>makeindex</CODE> wizard. What does <SF>xindy</SF> offer that <CODE>makeindex</CODE> doesn't?</A>
</H2>

<P>
<P>Here are the most important differences between <SF>xindy</SF> and
<CODE>makeindex</CODE>:
<P>
<P>
<DL>
<P>
<DT><B>Internationalization</B><DD><P><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
&Agrave;, &Aacute;, &ntilde;. Other languages from northern Europe
have letters like &Auml;, &Oslash;, &aelig; or &szlig; 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 <EM>sort</EM> and
<EM>merge-rules</EM> that allow expressing of language specific rules.
One example of such a rule would be
<P>
<PRE>
(sort-rule &quot;ä&quot; &quot;ae&quot;)
</PRE>
<P>defining that a word containing the umlaut-a will be sorted as if it
contained the letters <CODE>ae</CODE> 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.
<P>
<DT><B>Location classes.</B><DD><P><CODE>makeindex</CODE> 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 <EM>location-classes</EM>. 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:
<P>
<BLOCKQUOTE><CODE>
<PRE>
(define-location-class "page-numbers" ("arabic-numbers"))
</PRE>
</CODE></BLOCKQUOTE>
<P>This declares that page numbers consist of the enumeration of the
arabic numbers. The arabic numbers are referred to as <EM>alphabets</EM>.
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.
<P>
<DT><B>The concept of attributes.</B><DD><P>With <CODE>makeindex</CODE> 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
<P>
<BLOCKQUOTE><CODE>
<PRE>
\index{xindy|bold}
</PRE>
</CODE></BLOCKQUOTE>
<P>the encapsulator is <CODE>bold</CODE> 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
<EM>attributes</EM>. 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.
<P>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 <CODE>makeindex</CODE>-like markup is only a small subset of
<SF>xindy</SF>s features.
<P>
<DT><B>Cross references.</B><DD><P>Cross-references were implemented in
<CODE>makeindex</CODE> 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 <EM>checked</EM> cross references,
i.e. cross-refernces that can be checked if they point to an existing
index entry instead of somewhere ``behind-the-moon''.
<P>
<DT><B>Less command-line options.</B><DD><P><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 <CODE>makeindex</CODE> 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.
<P>
<DT><B>Raw index parser.</B><DD><P>The parser built into <CODE>makeindex</CODE> 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 <CODE>makeindex</CODE>, but in our opinion
more maintainable than the <CODE>makeindex</CODE> format. This requires a
separate filter that transforms arbitrary indexes to the <SF>xindy</SF>
format. An example filter is the program <CODE>tex2xindy</CODE> that comes
with this distribution.
<P>
</DL>
<P>Summed up, some of the implicit assumptions made by <CODE>makeindex</CODE>
have been replaced and now burdend to the user. The reason is that
many of <CODE>makeindex</CODE>'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.
<P>
<P>
<P>
<P>
<HR>
<A HREF="faq-2.html">Next</A>
Previous
<A HREF="faq.html#toc1">Contents</A>
</BODY>
</HTML>