summaryrefslogtreecommitdiff
path: root/Build/source/utils/xindy/doc/faq-1.html
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/xindy/doc/faq-1.html')
-rw-r--r--Build/source/utils/xindy/doc/faq-1.html169
1 files changed, 169 insertions, 0 deletions
diff --git a/Build/source/utils/xindy/doc/faq-1.html b/Build/source/utils/xindy/doc/faq-1.html
new file mode 100644
index 00000000000..31fcfba7abd
--- /dev/null
+++ b/Build/source/utils/xindy/doc/faq-1.html
@@ -0,0 +1,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>