summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/doc/faq-2.html
blob: 00be36138dc7edb8b4af023480f6b938a01eaedf (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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE>XINDY FAQ: xindy Usage</TITLE>
 <LINK HREF="faq-3.html" REL=next>
 <LINK HREF="faq-1.html" REL=previous>
 <LINK HREF="faq.html#toc2" REL=contents>
</HEAD>
<BODY>
<A HREF="faq-3.html">Next</A>
<A HREF="faq-1.html">Previous</A>
<A HREF="faq.html#toc2">Contents</A>
<HR>
<H2><A NAME="s2">2. <SF>xindy</SF> Usage</A></H2>

<H2><A NAME="ss2.1">2.1 I don't want to write style files. How can I proceed?</A>
</H2>

<P>
<P>You can use the wrapper program <CODE>makeindex4</CODE>. It tries to do it's
very best to make <SF>xindy</SF> behave as <CODE>makeindex</CODE> does. But if you
ever need to use some of the features of <SF>xindy</SF> you should learn
how to write an index style. Its easy!
<P>
<P>
<P>
<H2><A NAME="ss2.2">2.2 How do I use <CODE>makeindex4</CODE>?</A>
</H2>

<P>
<P>Process your document as usual. Then run <CODE>makeindex4</CODE> on the index
file. It produces an index that should equal the one you would get
with an ordinary <CODE>makeindex</CODE> run. As far as you are satisfied with
the default behaviour of <CODE>makeindex</CODE>, <CODE>makeindex4</CODE> will produce
comparable results.
<P>Some of the command-line options of <CODE>makeindex</CODE> are accepted by
<CODE>makeindex4</CODE>, others aren't. This may change in future releases,
but we recommend using plain <SF>xindy</SF> after a phase of
investigation, since one cannot use all of its features with
<CODE>makeindex4</CODE>. You will be informed about unsupported command-line
arguments when running <CODE>makeindex4</CODE>.
<P>If you have written special style files for <CODE>makeindex</CODE> they will
no longer work with <CODE>makeindex4</CODE>. Go ahead and write a new style
file for <SF>xindy</SF>.
<P>
<P>
<P>
<H2><A NAME="ss2.3">2.3 How works <CODE>makeindex4</CODE>?</A>
</H2>

<P>
<P>This job is now done automatically by <CODE>makeindex4</CODE>. It calls
<CODE>tex2xindy</CODE> to transform the raw-index into the format suitable for
<SF>xindy</SF>. <CODE>tex2xindy</CODE> emits some information about the attributes
(aka. encapsulators in <CODE>makeindex</CODE>) and the usage of
cross-references into a file, which has the extension `<CODE>.sta</CODE>'. The
<CODE>makeindex4</CODE> program, written in <CODE>perl</CODE>, parses this
statistics-file and generates the above presented indexstyle commands
for you automatically including the required declaration of all
attributes in the whole index and their markup.
<P>Another problem is the automatic detection of cross-references. As
noted above, <CODE>makeindex</CODE> handles cross-references with its
encapsulation mechanism, a scheme which has been dropped in <SF>xindy</SF>
and replaced by a more powerful mechanism. To implement a simple
plug-in mechanism we have extended the syntax of the <CODE>tex2xindy</CODE>
filter to identify encapsulators of the form
<P>
<BLOCKQUOTE><CODE>
<PRE>
\indexentry{...|encap{...}}{...}
</PRE>
</CODE></BLOCKQUOTE>
<P>as a cross-reference, whereas encapsulators of the form
<P>
<BLOCKQUOTE><CODE>
<PRE>
\indexentry{...|encap}{...}
</PRE>
</CODE></BLOCKQUOTE>
<P>are treated as ordinary attributes. This is standard practice
defining cross-references in <CODE>makeindex</CODE>. Thus, <CODE>tex2xindy</CODE>
distinguishes these two forms of encapsulators as opposed to
<CODE>makeindex</CODE> and our plug-in <CODE>makeindex4</CODE> generates the
appropriate definitions of the cross-reference classes as well.
<P>
<P>
<P>
<P>
<HR>
<A HREF="faq-3.html">Next</A>
<A HREF="faq-1.html">Previous</A>
<A HREF="faq.html#toc2">Contents</A>
</BODY>
</HTML>