summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/xindy
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/xindy
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/xindy')
-rw-r--r--Master/texmf-dist/doc/xindy/NEWS25
-rw-r--r--Master/texmf-dist/doc/xindy/README14
-rw-r--r--Master/texmf-dist/doc/xindy/README.distrib-source127
-rw-r--r--Master/texmf-dist/doc/xindy/alphabets-doc.pdfbin0 -> 380525 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/dataflow.gifbin0 -> 1988 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/faq-1.html169
-rw-r--r--Master/texmf-dist/doc/xindy/faq-2.html95
-rw-r--r--Master/texmf-dist/doc/xindy/faq-3.html83
-rw-r--r--Master/texmf-dist/doc/xindy/faq-4.html668
-rw-r--r--Master/texmf-dist/doc/xindy/faq.html90
-rw-r--r--Master/texmf-dist/doc/xindy/index.gifbin0 -> 9066 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/manual-1.html42
-rw-r--r--Master/texmf-dist/doc/xindy/manual-2.html302
-rw-r--r--Master/texmf-dist/doc/xindy/manual-3.html1160
-rw-r--r--Master/texmf-dist/doc/xindy/manual-4.html230
-rw-r--r--Master/texmf-dist/doc/xindy/manual-5.html63
-rw-r--r--Master/texmf-dist/doc/xindy/manual-6.html53
-rw-r--r--Master/texmf-dist/doc/xindy/manual-7.html53
-rw-r--r--Master/texmf-dist/doc/xindy/manual.html73
-rw-r--r--Master/texmf-dist/doc/xindy/mappings.gifbin0 -> 878 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial-1.html92
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial-2.html361
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial-3.html263
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial-4.html41
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial.html66
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw20
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex16
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw35
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex16
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/index.tex16
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy55
-rw-r--r--Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy80
-rw-r--r--Master/texmf-dist/doc/xindy/tex2xindy.pdfbin0 -> 4825 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/texindy.pdfbin0 -> 12313 bytes
-rw-r--r--Master/texmf-dist/doc/xindy/xindy.pdfbin0 -> 11444 bytes
35 files changed, 4308 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/xindy/NEWS b/Master/texmf-dist/doc/xindy/NEWS
new file mode 100644
index 00000000000..7de83008e91
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/NEWS
@@ -0,0 +1,25 @@
+# $Id: NEWS,v 1.2 2008/01/09 15:14:20 jschrod Exp $
+#------------------------------------------------------------
+
+XINDY RELEASE NOTES
+===================
+
+Version Date Remarks
+
+2.3 2008-01-09 `Gour and Jörg Waited Too Long For It Release'.
+ Source distribution with canonical install procedure.
+ Includes UTF-8 and Omega support.
+ Bug fixes in base modules and *.idx parsing.
+
+2.2 rc2 2005-05-10 2nd release candidate for `LaTeX Companion Release'.
+ Resolved issues:
+ -- Linux release works on glibc 2.3
+ -- Two double quotes in index key are supported
+ -- Options are checked carefully and errors are reported
+ -- Structured version numbers
+ -- Style file tutorial commands work
+
+2.2 rc1 2004-05-28 First release candidate for `LaTeX Companion Release'.
+ New command interface, new distribution strategy
+ (ready-to-run), consolidated distribution of run time
+ engine, kernel, and language modules.
diff --git a/Master/texmf-dist/doc/xindy/README b/Master/texmf-dist/doc/xindy/README
new file mode 100644
index 00000000000..90440f93683
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/README
@@ -0,0 +1,14 @@
+$Id: README.distrib,v 1.3 2008/01/09 11:11:46 jschrod Exp $
+------------------------------------------------------------
+
+This directory contains documentation of `xindy'.
+
+Manual pages for the commands are created during installation and are
+placed in appropriate man directories.
+PDF versions of the manual pages have been added here for your convenience.
+
+The subdirectory ./style-tutorial/ contains the examples that are used
+in the xindy style tutorial.
+
+FAQ and style tutorial are out of date. (Updates are welcome, of course.)
+You find more documentation at the xindy Web Site, at http://www.xindy.org/.
diff --git a/Master/texmf-dist/doc/xindy/README.distrib-source b/Master/texmf-dist/doc/xindy/README.distrib-source
new file mode 100644
index 00000000000..6dd454e5273
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/README.distrib-source
@@ -0,0 +1,127 @@
+$Id: README.distrib-source,v 1.1 2008/01/09 15:14:21 jschrod Exp $
+------------------------------------------------------------
+
+xindy (`fleXible INDexing sYstem') is a flexible index processor that
+creates tagged index for publication system. xindy merges, sorts, and
+outputs markup for raw index entries. It is highly configurable. It
+supports many languages.
+
+This is the source distribution of xindy release 2.3,
+aka the `Gour and Jörg Waited Too Long For It Release'.
+Release notes are available in the file NEWS, in this directory.
+
+It is available from Sourceforge, see http://www.xindy.org/ for more
+information. This Web Site also contains the most up-to-date
+information about xindy.
+
+
+INSTALLATION (Short Version)
+------------
+Unpack the distribution archive, a directory xindy-<version> will
+be created. Usual steps follow:
+
+ $ cd xindy-<version>
+ $ ./configure
+ $ make
+ $ make install
+
+You need to use GNU make; e.g., on FreeBSD or on Solaris, you need to
+install it and use the command gmake instead of make.
+
+By default, installation will be done in the /usr/local/ tree.
+You can change that with the configure option `--prefix'.
+
+The long version of the installation instructions are in the file
+INSTALL.
+
+Please note: The xindy modules directory location (currently,
+$prefix/lib/xindy/modules/) is bound to be changed in future
+distributions. This only matters if you install additional modules
+there, at future updates.
+
+
+UPDATE INSTALLATION
+-------------------
+There is no specific update installation procedure, sorry. You need to
+install xindy anew.
+
+If you had installed xindy 2.2 RC1 (the LaTeX Companion Release)
+and you had additional xindy module files installed in the system-wide
+directories, you need to move them manually to the new modules tree.
+That is located in $prefix/lib/xindy/modules/ ($prefix is /usr/local/
+by default).
+
+
+USAGE
+-----
+There are two main commands:
+ -- texindy, for creation of indexes for LaTeX documents
+ -- xindy, for generic index creation
+
+Manuals for these commands are installed in appropriate man
+directories and additionally supplied in PDF format, in the
+/doc/ subdirectory of the distribution, which gets installed as
+$prefix/share/doc/xindy-<version>/.
+
+This documentation directory has more documentation. Technical reports
+are on our Web Site, http://www.xindy.org/.
+
+
+KNOWN ISSUES
+------------
+Known problems and wanted enhancements of xindy are documented in our
+SourceForge tracker system, accessible on the Web at
+https://sourceforge.net/tracker/?group_id=10646
+
+
+FEEDBACK / MAILING LIST
+-----------------------
+Everybody is encouraged to port xindy to new platforms. For any kind
+of suggestions, helpful comments, questions, bug reports and such,
+please mail to the xindy mailing list
+
+ xindy-discuss@lists.sourceforge.net
+
+This is a low-volume mailing list; with a few emails per month.
+You can subscribe to the list by visiting
+
+ http://lists.sourceforge.net/lists/listinfo/xindy-discuss
+
+Mailing list archives are public and can be read at
+
+ http://sourceforge.net/mailarchive/forum.php?forum=xindy-discuss
+
+
+DISTRIBUTION CONTENT
+--------------------
+This distribution contains
+ -- xindy run-time environment (rte/)
+ -- xindy kernel (src/, tex2xindy/, user-commands/)
+ -- sort-rules for many languages (make-rules/)
+ -- base xindy styles, as described in the LaTeX Companion (modules/)
+
+
+LEGALESE
+--------
+This package is freely distributable software; you can redistribute it
+and/or modify it under the terms of the GNU General Public License
+(GPL) as published by the Free Software Foundation.
+
+This software is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License in
+the file COPYING along with this package; if not, write to the Free
+Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+The xindy run-time environment contains CLISP, which is released under
+GPL version 2 (only). Please refer to rte/clisp-<version>/COPYRIGHT
+for the specific statement.
+
+The xindy run-time environment contains a xindy-specific CLISP-plugin
+named ordrules, which is released under GPL version 2 or later.
+
+The xindy kernel modules and base styles are released under GPL
+version 2 or later.
diff --git a/Master/texmf-dist/doc/xindy/alphabets-doc.pdf b/Master/texmf-dist/doc/xindy/alphabets-doc.pdf
new file mode 100644
index 00000000000..c827d872e7d
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/alphabets-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/dataflow.gif b/Master/texmf-dist/doc/xindy/dataflow.gif
new file mode 100644
index 00000000000..203b5521ba6
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/dataflow.gif
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/faq-1.html b/Master/texmf-dist/doc/xindy/faq-1.html
new file mode 100644
index 00000000000..31fcfba7abd
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/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>
diff --git a/Master/texmf-dist/doc/xindy/faq-2.html b/Master/texmf-dist/doc/xindy/faq-2.html
new file mode 100644
index 00000000000..00be36138dc
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/faq-2.html
@@ -0,0 +1,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>
diff --git a/Master/texmf-dist/doc/xindy/faq-3.html b/Master/texmf-dist/doc/xindy/faq-3.html
new file mode 100644
index 00000000000..12895e8cb29
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/faq-3.html
@@ -0,0 +1,83 @@
+<!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 and LaTeX</TITLE>
+ <LINK HREF="faq-4.html" REL=next>
+ <LINK HREF="faq-2.html" REL=previous>
+ <LINK HREF="faq.html#toc3" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="faq-4.html">Next</A>
+<A HREF="faq-2.html">Previous</A>
+<A HREF="faq.html#toc3">Contents</A>
+<HR>
+<H2><A NAME="s3">3. <SF>xindy</SF> and LaTeX</A></H2>
+
+<H2><A NAME="ss3.1">3.1 What is <CODE>tex2xindy</CODE>?</A>
+</H2>
+
+<P>
+<P><CODE>tex2xindy</CODE> is a filter that parses `<CODE>.idx</CODE>' or similar files
+and converts the <CODE>\indexentry</CODE> macros into a form readable by
+<SF>xindy</SF>.
+<P>The parser of <CODE>makeindex</CODE> can be configured to recognize different
+quoting characters, etc. (see the man-page for <CODE>makeindex</CODE>, section
+<EM>input style specifiers</EM> for further details). We have tried to
+extract the parser from <CODE>makeindex</CODE> but due to several probems we
+have finally rewritten the parser using <CODE>lex</CODE>. Scanners written
+with <CODE>lex</CODE> are usually fixed to a specific character set used in
+the regular expressions. Our parser, <CODE>tex2xindy</CODE> is therefore not
+configurable. If one uses a different configuration of the
+<CODE>makeindex</CODE> input style specifiers, one can change the source
+(<CODE>tex2xindy.l</CODE>) to generate a completely new parser. From our
+personal experience we have rarely used more than two different
+parsers in practice so we have written <CODE>tex2xindy</CODE> in a form that
+is easily maintainable. The input specifiers are stored symbolically
+in the source. The definiton section looks like this:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+KEYWORD \\indexentry
+ENCAP \|
+ACTUAL @
+ESCAPE \\
+LEVEL !
+QUOTE \"
+ROPEN \(
+RCLOSE \)
+ARGOPEN \{
+ARGCLOSE \}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>These definitions are essentially the input style specifiers as can be
+found in the man-page of <CODE>makeindex</CODE>. Changing this section
+according to your needs and recompiling <CODE>tex2xindy</CODE> should be an
+easy task. Maybe we will include more pre-defined parsers in future
+releases if necessary.
+<P>
+<P>
+<P>
+<H2><A NAME="ss3.2">3.2 What LaTeX-package should I use in conjunction with xindy?</A>
+</H2>
+
+<P>
+<P>We strongly recommend using the LaTeX2e-package <CODE>index</CODE> written
+by David M. Jones, which is available at CTAN. It supports multiple
+indexes as well as several shortcuts to easily index terms in a
+document. Multiple indexes support the generation of several indexes
+for one document. For instance, one can make an author or command
+index in addition to a global index.
+<P>Another option is to use the <CODE>xindy.sty</CODE> from Andreas Schlechte
+that comes with the <SF>xindy</SF> distribution. Take a look at the
+<CODE>contrib</CODE> directory that should contain a version.
+<P>
+<P>
+<P>
+<P>
+<HR>
+<A HREF="faq-4.html">Next</A>
+<A HREF="faq-2.html">Previous</A>
+<A HREF="faq.html#toc3">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/faq-4.html b/Master/texmf-dist/doc/xindy/faq-4.html
new file mode 100644
index 00000000000..81052562f1d
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/faq-4.html
@@ -0,0 +1,668 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY FAQ: Style Files</TITLE>
+ <LINK HREF="faq-3.html" REL=previous>
+ <LINK HREF="faq.html#toc4" REL=contents>
+</HEAD>
+<BODY>
+Next
+<A HREF="faq-3.html">Previous</A>
+<A HREF="faq.html#toc4">Contents</A>
+<HR>
+<H2><A NAME="s4">4. Style Files</A></H2>
+
+<H2><A NAME="ss4.1">4.1 Eventually, I decided to write my first index style. How can I start?</A>
+</H2>
+
+<P>
+<P>Congratulations! You have made a good decision, indeed.
+<P>For a first impression, how a style file can be written from scratch
+reference the <EM>tutorial</EM> that comes with this distribution. It is
+written as a guided step-by-step practicing exercise and you can learn
+the basic concepts quite easily.
+<P>Afterwards, the best starting point is to make a copy of the template
+file that contains all the necessary commands that are needed to make
+a <CODE>makeindex</CODE>-like index. You can find it in the subdirectory
+<CODE>markup/tex</CODE> of the module library. Starting from this template
+you can remove or add commands as necessary.
+<P>Additionally, consult the library of predefined <EM>index style
+modules</EM> that comes with this distribution. Solutions for most of the
+typical problems can be found there, such as a module for doing
+case-insensitive sorting rules, or a typical TeX-like markup. Most
+of the time is is enough to include some of these modules and add a
+few additional commands.
+<P>Maybe some of the examples coming with the <EM>test-suite</EM> are good
+examples of how unusual index style files can be written.
+<P>Thus, there are many ways to learn writing an index style file. But it
+is very easy and after some experience you can process indexes your
+friends will be jealous of.
+<P>
+<P>
+<H2><A NAME="ss4.2">4.2 How to write my first index style?</A>
+</H2>
+
+<P>
+<P>Copy the file <CODE>tex/makeidx.xdy</CODE> from the library to your
+local directory. It is documented in in a way that should make it easy
+to fill in new commands or remove or modify others.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.3">4.3 How works the actual key feature of <CODE>makeindex</CODE> with <SF>xindy</SF>?</A>
+</H2>
+
+<P>
+<P>The treatment of the actual key (usually denoted with <CODE>@</CODE>, the
+at-sign) has changed with <SF>xindy</SF>. Specifying index entries with a
+specific markup can be done in <CODE>makeindex</CODE> with the actual key. The
+<CODE>makeindex-3</CODE> system and <SF>xindy</SF> offer the <EM>merge-</EM> and
+<EM>sort-rules</EM> to transform a key into different representations,
+limiting the need to specify an actual key. For example they support a
+style of writing
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\index{\bf{VIP}}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>which can be transformed with a rule like
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "\bf{\(.*\)}" "\1" :again :bregexp)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>which removes the macro definition for merging and sorting keywords,
+but keeping the original definition for markup purposes. Therefore we
+don't need any actual keys for all keywords written in boldface.
+<P>The <CODE>makeindex</CODE> behaviour, that the two keywords
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\index{VIP}
+\index{VIP@\bf{VIP}}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>are seen as two distinct index entries, can be simulated using the
+following definition:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "\bf{\(.*\)}" "\1~e" :again :bregexp)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This rule tells <SF>xindy</SF> to remove the boldface macro for merging
+and sorting purposes but defines the replacement to include the
+special character <CODE>~e</CODE>, which is the last character in the
+alphabet (ISO-Latin in our case). This makes <SF>xindy</SF> treat them as
+different keywords and positions the boldface keyword right behind the
+one without any markup. Thus we receive the following mapping:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+Keyword: Merged and sorted as: Appears in the index as:
+VIP VIP VIP
+\bf{VIP} VIP~e \bf{VIP}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>With this new style of writing keywords and defining their markup, the
+need to explicitly specifying the print key (aka. actual key) has
+convinced us to remove the <CODE>makeindex</CODE> way of defining keywords.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.4">4.4 I want to process an index for my native language. What must I do?</A>
+</H2>
+
+<P>
+<P>What makes <CODE>makeindex</CODE> hardly usable in non-English speaking
+countries is its lack of support of language specific alphabets and
+sort orderings. For example, many roman languages such as Italian,
+French, Portuguese or Spanish contain accented letters such as
+&Agrave;, &Aacute;, &ntilde;. Other languages from northern Europe
+have letters like &Auml;, &Oslash;, &aelig; or &szlig; which often
+can't even be processed by many index processors let alone sorting
+them correctly into an index.
+<P>Two problems must be solved when processing indexes with a new
+languages:
+<P>
+<OL>
+<LI> The <EM>sort ordering</EM> of the indexed terms must be specified
+in an appropriate manner. This problem can be solved using the
+so-called <EM>keyword mappings</EM>.
+</LI>
+<LI> The <EM>letter groups</EM> that partition the indexed terms into
+separate sections must be specified.</LI>
+</OL>
+<P>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 language
+specific rules.
+<P>The keyword mappings are as follows: The <EM>merge key</EM> is generated
+from the <EM>main key</EM> with the so called <EM>merge mapping</EM>. The
+merge mapping can be specified with the command <CODE>merge-rule</CODE>. The
+<EM>sort key</EM> is derived from the merge key using the <EM>sort
+mapping</EM> specified with the <CODE>sort-rule</CODE> command. The following
+scheme shows this mapping process:
+<P>
+<FIGURE>
+<EPS FILE="mappings.eps">
+<IMG SRC="mappings.gif">
+</FIGURE>
+<P>
+<P>The index style commands accomplishing this task are
+<CODE>sort-rule</CODE> and <CODE>merge-rule</CODE>. One example of such a rule would
+be
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule "ä" "ae")
+</PRE>
+</CODE></BLOCKQUOTE>
+<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 on can express the complete rules of a specific language.
+<P>An example of how an appropriate mapping for some of the Roman
+languages could look like is:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule "à" "a")
+(sort-rule "á" "a")
+(sort-rule "ã" "a")
+(sort-rule "è" "e")
+(sort-rule "é" "e")
+(sort-rule "ç" "c")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This makes the accented letters be sorted as their unaccented
+counterparts, yielding the desired sort ordering.
+<P>Sometimes it is necessary to specify keyword mappings that tell the
+system to put something <EM>behind</EM> something else. For instance, we'd
+like to map the character <EM>ö</EM> behind the letter <EM>o</EM>. No problem
+if you use the special characters <CODE>~b</CODE> and <CODE>~e</CODE> which
+are called the <EM>beginning</EM> and <EM>ending</EM> characters. The first
+letter lexicographically precedes all other letters whereas the latter
+one comes after all others. Our mapping problem can now be specified
+as follows.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule "ö" "o~e")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Now the <EM>ö</EM> is directly positioned after the <EM>o</EM> but before
+<EM>p</EM>.
+<P>
+<P>See the manual for a detailed description of this feature.
+Also be informed that the keyword mappings can be specified with
+regular expressions. Rules of the form
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "[-$()]" "")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>are possible. This on removes all letters of the defined letter class.
+Regular expression substitutions are possible as well. Refer to the
+manual for an exact description.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.5">4.5 In my index the capitalized words appear after the lowercase words. Why?</A>
+</H2>
+
+<P>
+<P>The default sort ordering sorts letters according to their ordinal
+number in the ISO Latin alphabet. As a consequence the lowercase
+letters appear before the uppercase letters. To sort them
+case-insensitively use the command
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(require "lang/latin/caseisrt.xdy")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This module defines the appropriate sort rules for the letters `A-Z'
+for latin-based alphabets. If your language has more letters simply
+add the missing ones into your style file. Have a look at the module
+to see how to the sort rules are defined.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.6">4.6 In my index there are no letter groups, yet!</A>
+</H2>
+
+<P>
+<P>Letter groups for latin based alphabets can be defined with the command
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(require "lang/latin/letgroup.xdy")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>If your language needs additional letter groups you can insert them
+into the previously defined letter group with inserting definitions of
+the following form:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-letter-group "ly" :after "l" :before "m")
+(define-letter-group "ny" :after "n" :before "o")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This adds two more letter groups to the latin alphabet. Group <EM>ly</EM>
+is inserted between <EM>l</EM> and <EM>m</EM>, and <EM>ny</EM> is inserted between
+<EM>n</EM> and <EM>o</EM>. This is how two additional letters of the Hungarian
+alphabet can be inserted.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.7">4.7 How can I get rid of any formatting information in the keyword?</A>
+</H2>
+
+<P>
+<P>Assume you have index entries containing arbitrary formatting
+information. For example you write your index entries in TeX in the
+following form:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\index{\bf{In boldface please}}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>To avoid specifying for each index entry the print key separately as
+can be done with the following command
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\index{In boldface please@\bf{In boldface please}}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>you can instead define a rule doing this task for you:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "\\bf *{(.*)}" "\1" :eregexp :again)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This extended regular expression matches all strings that are
+surrounded by this formatting command and in the <EM>merge phase</EM> the
+formatting command is simply stripped off. Thus, you don't need to
+write an explicit print key anymore.
+<P>If for some reason the same word appears more than once in the index,
+each time having another markup tag as in the following example
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+index
+{\tt index}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>you must be warned that a rule like
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "{\\tt *(.*)}" "\1" :eregexp :again)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>is probably not correct. In this case the above strings are both
+mapped into the string <CODE>index</CODE> thus joining their location
+references into one index entry. This happens because the result of
+the merge mapping is used as the equality citerium which views both
+keywords as equal. To avoid this you should specify instead
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule "{\\tt *(.*)}" "\1~e" :eregexp :again)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>With the additional meta character <CODE>~e</CODE> the substitution of the
+second key word is placed <EM>after</EM> the first one making them
+different index entries. If the second keyword should appear first,
+use <CODE>~b</CODE> instead.
+<P>
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.8">4.8 In my index the word <EM>-foo</EM> appears before <EM>bar</EM>. What must I do?</A>
+</H2>
+
+<P>
+<P>Especially for hierarchical indexes sometimes the result is not as
+expected due to special characters appearing in the keyword. In the
+following example the word `card' should appear before `-eyed' since
+the hyphen should not count as an ordinary character by means of
+sorting.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ green
+ -eyed 12
+ card 15
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This is especially problematic if the list of words on the second
+level is very long. To make the hyphen be simply ignored during the
+sorting process you should specify the following command in the index
+style:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ (sort-rule "-" "")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This makes `-eyed' be sorted as `eyed' thus making it appear
+<EM>after</EM> `card' as desired.
+<P>
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.9">4.9 I want to use letter ordering instead of word ordering in my index.</A>
+</H2>
+
+<P>
+<P>According to the <EM>Chicago Manual of Style</EM> there exist two
+different schemes of sorting word lists. In <EM>word ordering</EM>
+a blank precedes any letter in the alphabet, whereas in <EM>letter
+ordering</EM> it does not count at all. The following example borrowed
+from the <CODE>makeindex</CODE> man-page illustrates the difference:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ Word Order: Letter Order:
+ sea lion seal
+ seal sea lion
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>By default, <SF>xindy</SF> uses word ordering. To use letter ordering
+include the appropriate module with the following command:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(require "ord/letorder.xdy")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>It actually defines the following command:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule " " "")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This simply removes all blanks from the keyword resulting in the
+desired behaviour.
+<P>
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.10">4.10 My document does not have page numbers, but a different scheme. What must I do?</A>
+</H2>
+
+<P>
+<P>The ability to deal with user-definable location structures is one of
+the most important new features of <SF>xindy</SF>. Many documents have a
+document structure that is not based on page numbers. Typical examples
+are manuals or appendices that come with a
+<EM>chapter/page-per-chapter</EM> numbering scheme, URLs, Bible verses,
+etc. One can even imagine the Greek alphabet as possibly appearing in
+a location reference. In our analysis we have found many interesting
+examples of location references that made us to develop the concept of
+<EM>location classes</EM>.
+<P>A location class is defined by a sequence of alphabets. An alphabet
+can be the set of arabic numbers (0, 1, 2, ...) or the roman numerals
+(i, ii, iii, ...). These are built-in alphabets in <SF>xindy</SF>.
+Addtionally, one can define more alphabets in the index style with a
+command like
+<P>
+<PRE>
+ (define-alphabet "weekdays"
+ ("mon" "tue" "wed" "thu" "fri" "sat" "sun"))
+</PRE>
+<P>Based on alphabets one can now compose a location class as follows:
+<P>
+<PRE>
+ (define-location-class "weekday-hours"
+ ("weekday" :sep ":" "arabic-numbers"))
+</PRE>
+<P>This class description indicates that all location refernces matching
+this template are viewed as correct instances of this class. Here
+<CODE>:sep</CODE> makes the dot serving as a <EM>separation string</EM> separation
+the alphabets from each other. Example instances of this class are:
+<P>
+<PRE>
+mon:23, thu:45, sun:17
+</PRE>
+<P>For more detailed information consult the description of the command
+<CODE>define-location-class</CODE> in the reference manual.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.11">4.11 I don't want to have ranges in my index. What can I do?</A>
+</H2>
+
+<P>
+<P>By default, <SF>xindy</SF> joins three successive location references into a
+<EM>range</EM>. Ranges are used as an abbrevation for a long sequence of
+location references. For exmaple the sequence
+<P>
+<PRE>
+12, 13, 14, 15, 16
+</PRE>
+<P>would be shorter represented as
+<P>
+<PRE>
+12-16
+</PRE>
+<P>If you don't want to have ranges, simply define your location class in
+the form
+<P>
+<PRE>
+ (define-location-class ... :min-range-length none)
+</PRE>
+<P>The argument <CODE>:min-range-length none</CODE> avoids forming of ranges.
+Arbitrary numbers instead of <CODE>none</CODE> define the minimum length of a
+sequence of location references that are needed to form a range.
+<SF>xindy</SF>s default value is&nbsp;2.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.12">4.12 I want to markup ranges of different length differently. How do I accomplish this?</A>
+</H2>
+
+<P>
+<P>A common way of tagging ranges is as follows: a range of length 1 is
+printed with the starting page number and the suffix `f.', those of
+length 2 with suffix `ff.', and all others in the form `<EM>X--Y</EM>'.
+<P>Assume we want to do this for the location class <EM>pagenums</EM> we can
+specify the markup as follows:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-range :class "pagenums" :close "f." :length 1 :ignore-end)
+(markup-range :class "pagenums" :close "ff." :length 2 :ignore-end)
+(markup-range :class "pagenums" :sep "--")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The first command indicates that a range <EM>(X,Y)</EM> of length 1 should
+be printed in the form <EM>Xf.</EM>, a range of length 2 as <EM>Xff.</EM> and
+all others in the form <EM>X--Y</EM>. The switch <CODE>:ignore-end</CODE> causes
+the end of range location reference Y to be suppressed in the
+resulting output.
+<P>
+<P>
+<H2><A NAME="ss4.13">4.13 I need to suppress some of the markup tags. How can I do this?</A>
+</H2>
+
+<P>Sometimes it is necessary to hide some of the parts of the index. If
+you have a text formatter that allows comments or macros that possibly
+expand to nothing, just define appropriate markup that makes things
+invisible to the formatter. For example, with TeX you can define a
+macro like this
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\def\ignore#1{}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>If you additionally define markup like this
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-index :open "\ignore{" :close "}")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>you can throw away the complete index if you like, which would be a
+real pity!
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.14">4.14 Whats it all about those cross references?</A>
+</H2>
+
+<P>
+<P>Cross references are references pointing to an item in the index
+itself. Typical examples are:
+<P>
+<BLOCKQUOTE><CODE>
+foo-bar <EM>see</EM> baz
+</CODE></BLOCKQUOTE>
+<P>With <CODE>makeindex</CODE> cross references could be specified with the
+encapsulation mechanism. This has completely been removed in <SF>xindy</SF>
+and we have made cross references real first-class objects.
+<P>In <SF>xindy</SF> one can declare different cross reference classes, whose
+purpose is (a) to make all instances of a certain class appear next to
+each other, and (b) to specify appropriate markup with them.
+<P>@begin-comment
+One very interesting feature is the ability to <EM>check</EM> the validity
+of cross-references.
+@end-comment
+<P><CODE>tex2xindy</CODE> recognises all index entries of the form
+<P>
+<PRE>
+ \index{...|\macro{where}}
+</PRE>
+<P>as cross references. Here <CODE>macro</CODE> stands for an arbitrary macro
+name and <CODE>where</CODE> is interpreted as the target keyword of the cross
+references.
+<P>If you want to use these cross references with <SF>xindy</SF>; add the
+following line to your style file.
+<P>
+<PRE>
+ (define-crossref-class "macro")
+</PRE>
+<P>Additionally, you can assign specific markup to cross references using
+the <CODE>markup-crossref</CODE>-commands.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.15">4.15 The keyword mappings don't work as expected!</A>
+</H2>
+
+<P>
+<P>Sometimes the keyword mappings don't work as expected. Especially in
+cases with several regular expressions one might get confused about
+what rule matches exactly when. We have incorporated a detailed
+logging mechanism that lets one step by step follow the rules that
+accomplish the keyword mapping.
+<P>When running <SF>xindy</SF> you can turn on this feature with the command
+line option `<CODE>-L</CODE>'. This option followed by one of the numbers 1,
+2, or 3 turns on the appropriate debugging level. Turning on level 2
+or 3 and specifying a log-file with the command line option `<CODE>-l</CODE>'
+a trace of the mappings is recorded in the log-file. A sample output
+looks like the following:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+Mappings: (add (merge-rule :eregexp `^\\bf{(.*)}' `\1' :again)).
+Mappings: (add (merge-rule :eregexp `^\\"([AEOUaeou])' `\1')).
+ ...
+Mappings: (compare `\"A\"a' :eregexp `^\\bf{(.*)}')
+Mappings: (compare `\"A\"a' :eregexp `^\\"([AEOUaeou])') match!
+Mappings: (compare `\"a' :eregexp `^\\bf{(.*)}')
+Mappings: (compare `\"a' :eregexp `^\\"([AEOUaeou])') match!
+Mappings: (merge-mapping `\"A\"a') -> `Aa'.
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This trace shows that initially two regular expression mappings have
+been added to the rule set. The second section shows how the keyword
+`<CODE>\"A\"a</CODE>' is compared to these rules and substitutions are
+applied as matches are found. In the last line the result of the
+keyword mapping is reported.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.16">4.16 I'm totally confused by the markup scheme!</A>
+</H2>
+
+<P>
+<P>A very important feature is the ability to <EM>trace</EM> all markup tags
+<SF>xindy</SF> emits in the markup phase. Simply use the command line
+switch <CODE>-t</CODE> or insert the command
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-trace :on)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>into the index style. This informs <SF>xindy</SF> to emit additional
+pseudo markup that can be used to understand and debug the
+markup phase. An example output might look like the following:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+&lt;INDEX:OPEN>
+ &lt;LETTER-GROUP-LIST:OPEN>
+ &lt;LETTER-GROUP:OPEN ["a"]>
+ &lt;INDEXENTRY-LIST:OPEN [0]>
+ &lt;INDEXENTRY:OPEN [0]>
+ &lt;KEYWORD-LIST:OPEN [0]>
+ &lt;KEYWORD:OPEN [0]>
+ ...
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The symbolic tags directly lead one to the command that is responsible
+for the definition of that markup tag. For example, the tag
+<CODE>LETTER-GROUP-LIST:OPEN</CODE> indicates that the command
+<CODE>markup-letter-group-list</CODE> is responsible for replacing this
+symbolic tag by a real one.
+Give it a try if you find yourself confused by your own markup
+specification.
+<P>
+<P>
+<P>
+<H2><A NAME="ss4.17">4.17 What editor should I use when writing xindy style files?</A>
+</H2>
+
+<P>
+<P>Use <CODE>Emacs</CODE> or <CODE>XEmacs</CODE>. Turn on the Lisp-mode with
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+M-x lisp-mode
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>and you can properly indent commands using <CODE>M-q</CODE>. To enter this
+mode automatically add the following lines to the end of the style
+file:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+^L
+;; Local Variables:
+;; mode: lisp
+;; End:
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The <CODE>^L</CODE> (Control-L) can be entered with <CODE>C-q C-l</CODE>.
+<P>
+<P>
+<P>
+<HR>
+Next
+<A HREF="faq-3.html">Previous</A>
+<A HREF="faq.html#toc4">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/faq.html b/Master/texmf-dist/doc/xindy/faq.html
new file mode 100644
index 00000000000..d049b766693
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/faq.html
@@ -0,0 +1,90 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY FAQ</TITLE>
+ <LINK HREF="faq-1.html" REL=next>
+
+
+</HEAD>
+<BODY>
+<A HREF="faq-1.html">Next</A>
+Previous
+Contents
+<HR>
+<H1>XINDY FAQ</H1>
+
+<H2>Or: <SF>xindy</SF> by Topic</H2>
+<H2>Roger Kehr</H2>
+<H3>Computer Science Department, Technical University of Darmstadt</H3>
+ and
+<H2>Joachim Schrod</H2>
+<H3>Joachim Schrod Net &amp; Publication Consultance GmbH</H3>
+$Revision: 1.2 $, $Date: 2004/05/24 21:43:16 $, for xindy version 2.2
+<P><HR>
+<EM> The <SF>xindy</SF> FAQ presents answers to questions that are not
+adequately covered in other parts of the documentation, or are hard to
+find. The FAQ has been constructed from the <EM><SF>xindy</SF> by Topic</EM>
+manual. The most up-to-date version of this FAQ can be obtained from
+the <SF>xindy</SF> homepage at
+<A HREF="http://www.xindy.org/doc/faq.html">http://www.xindy.org/doc/faq.html</A>.
+<p>
+While the content of this document is still valid, it has not been
+updated in years and doesn't describe new developments. In particular,
+it doesn't mention the many languages that are supported by Thomas
+Henlich's <EM>make-rules</EM> system, and also doesn't know anything about
+the new commands that got introduced with the "LaTeX Companion
+Release". So, caveat. We don't want to throw out the document, though,
+since it still contains lots of useful information that's not
+available elsewhere.</EM>
+<HR>
+<P>
+<H2><A NAME="toc1">1.</A> <A HREF="faq-1.html">General Questions</A></H2>
+
+<UL>
+<LI><A HREF="faq-1.html#ss1.1">1.1 Why a completely new indexing tool? <CODE>makeindex</CODE> works fine!</A>
+<LI><A HREF="faq-1.html#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>
+</UL>
+<P>
+<H2><A NAME="toc2">2.</A> <A HREF="faq-2.html"><SF>xindy</SF> Usage</A></H2>
+
+<UL>
+<LI><A HREF="faq-2.html#ss2.1">2.1 I don't want to write style files. How can I proceed?</A>
+<LI><A HREF="faq-2.html#ss2.2">2.2 How do I use <CODE>makeindex4</CODE>?</A>
+<LI><A HREF="faq-2.html#ss2.3">2.3 How works <CODE>makeindex4</CODE>?</A>
+</UL>
+<P>
+<H2><A NAME="toc3">3.</A> <A HREF="faq-3.html"><SF>xindy</SF> and LaTeX</A></H2>
+
+<UL>
+<LI><A HREF="faq-3.html#ss3.1">3.1 What is <CODE>tex2xindy</CODE>?</A>
+<LI><A HREF="faq-3.html#ss3.2">3.2 What LaTeX-package should I use in conjunction with xindy?</A>
+</UL>
+<P>
+<H2><A NAME="toc4">4.</A> <A HREF="faq-4.html">Style Files</A></H2>
+
+<UL>
+<LI><A HREF="faq-4.html#ss4.1">4.1 Eventually, I decided to write my first index style. How can I start?</A>
+<LI><A HREF="faq-4.html#ss4.2">4.2 How to write my first index style?</A>
+<LI><A HREF="faq-4.html#ss4.3">4.3 How works the actual key feature of <CODE>makeindex</CODE> with <SF>xindy</SF>?</A>
+<LI><A HREF="faq-4.html#ss4.4">4.4 I want to process an index for my native language. What must I do?</A>
+<LI><A HREF="faq-4.html#ss4.5">4.5 In my index the capitalized words appear after the lowercase words. Why?</A>
+<LI><A HREF="faq-4.html#ss4.6">4.6 In my index there are no letter groups, yet!</A>
+<LI><A HREF="faq-4.html#ss4.7">4.7 How can I get rid of any formatting information in the keyword?</A>
+<LI><A HREF="faq-4.html#ss4.8">4.8 In my index the word <EM>-foo</EM> appears before <EM>bar</EM>. What must I do?</A>
+<LI><A HREF="faq-4.html#ss4.9">4.9 I want to use letter ordering instead of word ordering in my index.</A>
+<LI><A HREF="faq-4.html#ss4.10">4.10 My document does not have page numbers, but a different scheme. What must I do?</A>
+<LI><A HREF="faq-4.html#ss4.11">4.11 I don't want to have ranges in my index. What can I do?</A>
+<LI><A HREF="faq-4.html#ss4.12">4.12 I want to markup ranges of different length differently. How do I accomplish this?</A>
+<LI><A HREF="faq-4.html#ss4.13">4.13 I need to suppress some of the markup tags. How can I do this?</A>
+<LI><A HREF="faq-4.html#ss4.14">4.14 Whats it all about those cross references?</A>
+<LI><A HREF="faq-4.html#ss4.15">4.15 The keyword mappings don't work as expected!</A>
+<LI><A HREF="faq-4.html#ss4.16">4.16 I'm totally confused by the markup scheme!</A>
+<LI><A HREF="faq-4.html#ss4.17">4.17 What editor should I use when writing xindy style files?</A>
+</UL>
+<HR>
+<A HREF="faq-1.html">Next</A>
+Previous
+Contents
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/index.gif b/Master/texmf-dist/doc/xindy/index.gif
new file mode 100644
index 00000000000..74f581c4b85
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/index.gif
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/manual-1.html b/Master/texmf-dist/doc/xindy/manual-1.html
new file mode 100644
index 00000000000..40fc1db4349
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-1.html
@@ -0,0 +1,42 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: About this Manual</TITLE>
+ <LINK HREF="manual-2.html" REL=next>
+
+ <LINK HREF="manual.html#toc1" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-2.html">Next</A>
+Previous
+<A HREF="manual.html#toc1">Contents</A>
+<HR>
+<H2><A NAME="s1">1. About this Manual</A></H2>
+
+<P>We assume that the reader is already familiar with the task of an
+index processor and has basic experience in using a markup-based
+document preparation systems such as TeX/LaTeX [1, 2],
+the roff-family, or SGML-based systems (e.g. its instance HTML).
+<P>This document is structured as follows. The second part gives an
+overview on the index model that is used by our system and we define
+general concepts and terms. The third part contains a list of all
+index style commands, their syntax, and a description of their
+purpose. The reader should at least have read the first part of the
+manual to understand the basic terminology to be able to use the
+command reference. The fourth
+part describes the different processing phases the system runs
+through.
+<P>Invocation of <SF>xindy</SF> is not explained here. Please refer to the
+manual pages of the commands <CODE>xindy</CODE>, <CODE>texindy</CODE>,
+<CODE>makeindex4</CODE>, and to the 2nd edition of the LaTeX Companion. The
+<SF>xindy</SF> Web Site has more documentation, too.
+<P>
+<P>
+<P>
+<HR>
+<A HREF="manual-2.html">Next</A>
+Previous
+<A HREF="manual.html#toc1">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-2.html b/Master/texmf-dist/doc/xindy/manual-2.html
new file mode 100644
index 00000000000..c3a7a87be77
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-2.html
@@ -0,0 +1,302 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: How the Index Processor Works</TITLE>
+ <LINK HREF="manual-3.html" REL=next>
+ <LINK HREF="manual-1.html" REL=previous>
+ <LINK HREF="manual.html#toc2" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-3.html">Next</A>
+<A HREF="manual-1.html">Previous</A>
+<A HREF="manual.html#toc2">Contents</A>
+<HR>
+<H2><A NAME="how-works"></A> <A NAME="s2">2. How the Index Processor Works</A></H2>
+
+<P>
+<P>
+<H2><A NAME="ss2.1">2.1 Data Flow</A>
+</H2>
+
+<P>Usually document preparation systems produce some form data that
+describe the <EM>index entries</EM> and the <EM>locations</EM> they point to.
+This data is called the <EM>raw index</EM> since it consists of raw data
+which contains structured information about the entries of the index.
+The raw index is fed into the index processor and is processed
+according to a specification called the <EM>index style</EM>. This is a
+user-definable description how the index is to be processed, what
+sort rules for the keywords should be used, which kind of locations
+may appear, and finally, what tags should be emitted when writing the
+index into the output file. The result is sometimes fed back into the
+document preparation system, as it is in the case of TeX, or used
+otherwise. The following figure illustrates this embedding into the
+document preparation process.
+<P>
+<FIGURE>
+<EPS FILE="dataflow.eps">
+<IMG SRC="dataflow.gif">
+</FIGURE>
+<P>The <SF>xindy</SF> system is oriented on book-like indexes in a form that
+is described later in detail. The format of the input data is fixed
+and a small tool that converts some system dependent raw index in a
+form suitable for <SF>xindy</SF> should not be a big hurdle. The user is
+normally not involved in the correct format suitable for <SF>xindy</SF>
+and some tools will make this work invisible to him.
+<P>In contrast, the output of the <SF>xindy</SF> system is highly
+configurable and can produce a variety of different markups.
+Additionally, the way <SF>xindy</SF> processes the index data can be
+parametrized and controlled in many ways and gives the user a powerful
+framework for describing complex indexes. The user can tell <SF>xindy</SF>
+how it should produce an output according to his wishes or simply use
+some of the predefined styles that come with the distribution.
+<P>
+<P>
+<P>
+<P>
+<H2><A NAME="general-concepts"></A> <A NAME="ss2.2">2.2 General Concepts and Terms</A>
+</H2>
+
+<P>In the following sections we introduce some terms that are necessary
+to understand the way <SF>xindy</SF> works.
+<P>The development of <SF>xindy</SF> started with the devlopment of a model
+of a <EM>book-like</EM> index. This rather vague term will now be fleshed
+out by giving a semi-formal description of the model. If the structure
+of an index conforms to this model it can be processed by <SF>xindy</SF>.
+We first present a diagram that describes the structure of a processed
+index. It is a hierarchical recursive data structure which we will
+describe now.
+<P>
+<FIGURE>
+<EPS FILE="index.eps">
+<IMG SRC="index.gif">
+</FIGURE>
+<P>Boxed objects contain elements from the raw index such as the keywords
+or the location reference layers. We start from the root of the
+diagram and explain the different elements.
+<P>
+<P>
+<P>
+<DL>
+<P>
+<DT><B>index</B><DD><P>An index consists of a list of <SF>letter-groups</SF>.
+<P>
+<P>
+<A NAME="def letter-group"></A> <DT><B>letter-group</B><DD><P>The letter groups serve as containers for
+<SF>indexentries</SF>. The letter groups are intended to group all
+index entries sharing a common <SF>keyword</SF> prefix, allowing the
+assignment of a specific markup for each group. For example, indexes
+are often organized in a way that new index entries beginning with a
+new letter are separated by a specific markup. The following example
+illustrates this style.
+<P>
+<PRE>
+ B
+ bread 25, 27
+ butter 26
+
+ M
+ marmalade 19
+ milk 21
+</PRE>
+<P>Here we have two letter groups for the letters `B' and `M' because the
+keywords `bread' and `butter' share the same prefix `b' and
+`marmalade' and `milk' share the prefix `m'. <SF>xindy</SF> can be advised
+to define arbitrary letter groups with a particular markup for each of
+them. See command <CODE>define-letter-group</CODE> for further details.
+<P>
+<P>
+<DT><B>indexentry</B><DD><P>An index entry consists of three components: the
+<SF>keyword</SF> and optionally the list of <SF>location-class-groups</SF> and
+the sub-<SF>indexentries</SF>. An example:
+<P>
+<PRE>
+ bread 25-30
+ brown 26
+ white 27
+</PRE>
+<P>This index entry consists of the keyword `bread', the
+location class list `25-30' and the sub-entries `brown 26' and `white
+27'. The sub-entries themselves are complete index entries as well,
+forming a recursive data structure.
+<P>
+<P>
+<DT><B>keyword</B><DD><P>The keyword is the identifier of an index entry. It
+consists of a list of strings being the <EM>key</EM> if the index entry. In
+our model the keyword constists of a list of strings, since indexes
+are often organized hierarchically with different layers. In the
+example
+<P>
+<PRE>
+ bread 25-30
+ bread, brown 26
+ bread, white 27
+</PRE>
+<P>we have keywords `bread', `bread, brown' and `bread, white'.
+<P>A keyword is actually separated into four different keys. The
+<SF>main-key</SF> is the key that is specified from the author who indexes
+a document. The <SF>merge-key</SF> is derived from the main key with the
+so-called <EM>merge mapping</EM>. This mapping is accomplished with a set
+of rewrite rules. The <SF>sort-key</SF> is derived from the merge key with
+another set of rewrite rules called the <EM>sort mapping</EM>. The
+<SF>print-key</SF> can be specified by the user explicitely or, if it is
+ommited, equals the main key. The rewrite rules consist of string
+substitutions that also include regular expression features.
+<P>The following figure describes this:
+<P>
+<FIGURE>
+<EPS FILE="mappings.eps">
+<IMG SRC="mappings.gif">
+</FIGURE>
+<P>
+<P>The <SF>merge-key</SF> is necessary to define the equality of
+index entry keys. See command <CODE>merge-rule</CODE> for further details about
+defining the merge mapping.
+<P>The <SF>sort-key</SF> is necessary to define a total order on the
+keywords. Since we need a scheme that is independent from any specific
+character set such as ASCII or ISO-Latin, we must be able to define
+completely new alphabets. The index entries are then sorted according
+to the ISO-Latin alphabet. See the command <CODE>sort-rule</CODE> for an
+explanation how these mapping can be specified.
+<P>The <SF>print-key</SF> is used for the final markup and contains the
+string that appears in the generated markup.
+<P>
+<P>
+<DT><B>location-class-group</B><DD><P>There exist two kinds of
+location class groups namely <SF>location-reference-groups</SF> and
+<SF>cross-reference-groups</SF>.
+<P>
+<DT><B>location-reference-group</B><DD><P>consists of a list of
+<SF>attribute-groups</SF>.
+<P>
+<P>
+<DT><B>attribute-groups</B><DD><P>Each <SF>location-reference-group</SF> consists of
+a list of <SF>attribute-groups</SF>. Attribute groups are defined by a set
+of <SF>attributes</SF>. In the markup phase, all location references are
+sorted according to the group number their attributes belong to.
+Additionally all location references of a particular attribute group
+appear together in the index.
+<P>See command <CODE>define-attribute-groups</CODE> for further information about
+the handling of attribute-groups.
+<P>An attribute group consists of a list of <SF>location-references</SF>
+and/or <SF>ranges</SF>.
+<P>
+<P>
+<A NAME="def locref-class"></A> <DT><B>location-reference-class, location-reference, location</B><DD><P>Each
+index entry of an index references at least one <SF>location</SF> in the
+document. A <SF>location</SF> is a logical or physical part of a document,
+such as a single page, a section or subsection, etc. The symbolic name
+of a location is called a <SF>location-reference</SF>. The
+location reference is always represented as a string (a sequence of
+characters). Each location reference is associated a special tag
+called <SF>attribute</SF>. The following examples may give you an idea how
+location references could look like.
+<P>
+<BLOCKQUOTE>
+<CODE>"25" </CODE> represents a page number.
+</BLOCKQUOTE>
+<P>
+<BLOCKQUOTE>
+<CODE>"Chapter-3"</CODE> represents the third chapter of a document.
+</BLOCKQUOTE>
+<P>
+<BLOCKQUOTE>
+<CODE>"A-I" </CODE> represents the first page, written in uppercase roman
+numerals of the appendix `A', separated by a hyphen.
+</BLOCKQUOTE>
+<P>
+<BLOCKQUOTE>
+<CODE>"2.3.4" </CODE> represents the sub-sub-section 2.3.4 of a document.
+</BLOCKQUOTE>
+<P>As we can see, the location references are often composed
+hierarchically of smaller entities, such as numbers or names. All
+location references that belong to the same class form a
+<SF>location-class</SF>. A location class is composed of <SF>alphabets</SF>
+and <SF>separators</SF>. See command <CODE>define-location-class</CODE> for a
+description how classes can be defined.
+<P>
+<P>
+<DT><B>alphabet, separator</B><DD><P>As we have seen in the previous section,
+location classes consist of alphabets and separators. xindy has the
+following built-in set of basic alphabets:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+&lt;tag/&lt;tt/arabic-numbers// contains all non-negative numbers beginning
+with zero: 0, 1, 2, ....
+
+&lt;tag/&lt;tt/roman-numerals-uppercase// the roman numerals I, II, III,
+(IIII/IV), V, ... It recognizes the old and new roman numeral system.
+
+&lt;tag/&lt;tt/roman-numerals-lowercase// the same for the lowercase roman
+numerals.
+
+&lt;tag/&lt;tt/ALPHA// the US-ASCII alphabet (uppercase letters).
+
+&lt;tag/&lt;tt/alpha// the US-ASCII alphabet (lowercase letters).
+
+&lt;tag/&lt;tt/digits// the digits 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9 in this
+order.
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The user is free to define new alphabets as he wishes. See the
+commands <CODE>define-alphabet</CODE> and <CODE>define-enumeration</CODE> for further
+details.
+<P>A complete location class can be defined by composing alphabets and
+separators. The location class of the example <CODE>"A-I"</CODE> can be
+defined as follows
+<P>
+<PRE>
+ (define-location-class "appendix"
+ (ALPHA "-" roman-numerals-uppercase))
+</PRE>
+<P>This is a list that completely describes all possible instances of
+this location class. Other valid members are <CODE>A-II</CODE>, <CODE>B-VI</CODE>,
+etc. Location classes are defined with the command
+<CODE>define-location-class</CODE>.
+<P><SF>xindy</SF> reads the incoming strings representing location references
+and tries to match them against a previously defined location class.
+There exist no predefined location classes.
+<P>
+<DT><B>range</B><DD><P>A <SF>range</SF> is a pair of <SF>location-references</SF>. A
+sequence of location references following one another is transformed
+into an range if the length of the sequence exceeds a certain
+user-definable limit. For example, the location references 11, 12, 13
+and&nbsp;14 may be transformed into the range 11--14. See command
+<CODE>define-location-class</CODE> for further details.
+<P>
+<P>
+<DT><B>cross-reference-group</B><DD><P>Container for all
+<SF>cross-references</SF> of a particular <SF>cross-reference-class</SF>.
+<P>
+<P>
+<A NAME="def crossref-class"></A> <DT><B>cross-reference-class, cross-reference</B><DD><P>A <SF>cross-reference</SF> is
+an unstructured reference. <SF>Cross-reference-classes</SF> are used to
+define different classes of cross references. All elements of a
+cross reference class appear together in the index. A cross reference
+consists of a list of strings.
+<P>
+<P>
+<DT><B>attributes</B><DD><P>Each location reference contains a so-called
+<SF>attribute</SF>. Attributes may be used to give a location reference a
+different meaning that may influence the processing and markup of this
+reference. Sometimes location references pointing to semantically
+different locations such as a definition or a usage of a term are
+tagged differently. They often appear in <EM>italics</EM> or <B>boldface</B>
+indicating this difference. An attribute may now be used to express
+this difference. Since <SF>xindy</SF> needs to know the possible
+attributes before the index entries are read in, the command
+<CODE>define-attributes</CODE> must be used to define a set of attributes and
+how they interact.
+<P>
+</DL>
+<P>
+<P>
+<P>
+<P>
+<HR>
+<A HREF="manual-3.html">Next</A>
+<A HREF="manual-1.html">Previous</A>
+<A HREF="manual.html#toc2">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-3.html b/Master/texmf-dist/doc/xindy/manual-3.html
new file mode 100644
index 00000000000..3520de7f1ea
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-3.html
@@ -0,0 +1,1160 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: Command List</TITLE>
+ <LINK HREF="manual-4.html" REL=next>
+ <LINK HREF="manual-2.html" REL=previous>
+ <LINK HREF="manual.html#toc3" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-4.html">Next</A>
+<A HREF="manual-2.html">Previous</A>
+<A HREF="manual.html#toc3">Contents</A>
+<HR>
+<H2><A NAME="s3">3. Command List</A></H2>
+
+<P>Here is the complete list of <SF>xindy</SF>'s commands that may be used in
+the index style. The symbol <CODE>name</CODE> always refers to a string. We
+separate the commands into the <EM>processing</EM> and
+<EM>markup</EM> commands. The commands are listed in alphabetical order.
+<P>The parenthesis `<CODE>[</CODE>' and `<CODE>]</CODE>' denote optional parts of the
+syntax and `<CODE>{</CODE>' and `<CODE>}</CODE>' denote the grouping of elements. A
+vertical bar indicates alternatives. However, the enclosing round
+braces <EM>are</EM> part of the syntax and must be supplied.
+<P>
+<P>
+<H2><A NAME="ss3.1">3.1 Processing Commands</A>
+</H2>
+
+<P>Here follows the list of processing commands.
+<P>
+<A NAME="define-alphabet"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-alphabet name string-list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> to be the alphabet consisting of all elements of the
+<CODE>string-list</CODE>. Examples:
+<P>
+<PRE>
+ (define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))
+</PRE>
+<P>defines an alphabet consisting of exactly three symbols. For the
+successor relationship holds: <CODE>succ("An")="Example"</CODE> and
+<CODE>succ("Example")="Alphabet"</CODE>. The built-in alphabet <CODE>digits</CODE> is
+defined as follows:
+<P>
+<PRE>
+ (define-alphabet "digits"
+ ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="define-attributes"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-attributes attribute-list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines all attributes the raw index may contain. Parameter
+<CODE>attribute-list</CODE> is a list of list of strings. The nesting level
+must not be more than&nbsp;2. So <CODE>(..(..)..)</CODE> is allowed, whereas
+<CODE>(..(..(..)..)..)</CODE> is not.
+<P>The list has two kinds of elements: strings and list of strings. A
+single string is treated as if it were a single element list. So the
+lists <CODE>("definition")</CODE> and <CODE>( ("definition") )</CODE> are equivalent.
+All elements forming a list are a so-called <EM>attribute group</EM>. The
+members of a group are written to the output file before any member
+of the following groups are written.
+<P>Examples of valid attributes lists are:
+<P><CODE>("definition" "usage")</CODE> defines two attribute groups. The first
+one contains all references with the attribute <CODE>definition</CODE> and the
+second one all with the attribute <CODE>usage</CODE>.
+<P><CODE>(("definition" "important") "usage")</CODE> defines two attribute
+groups. The first one contains all references with the attributes
+<CODE>definition</CODE> or <CODE>important</CODE> and the second one all with the
+attribute <CODE>usage</CODE>. In the attribute group <CODE>("definition"
+"important")</CODE> the attribute <CODE>definition</CODE> overrides <CODE>important</CODE>.
+<P>
+<P>
+<P>
+<A NAME="define-crossref-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-crossref-class name [:unverified])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> to be a class of cross references. We distinguish
+two types of cross reference classes. <EM>Verified</EM> cross reference
+classes can be checked for dangling references. If for instance a
+cross reference points to the non-existent keyword `foo' a warning is
+issued and the user is advised to correct the invalid cross reference.
+This is the default. If for some reasons this mechanism must be
+deactivated the switch <CODE>:unverified</CODE> can be used to suppress this
+behaviour.
+<P>
+<P>
+<A NAME="define-letter-group"></A>
+<A NAME="define-letter-groups"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-letter-group name [:before lgname] [:after lgname]
+ [:prefixes list-of-prefixes])
+
+(define-letter-groups list-of-letter-groups)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command defines a letter group with name <CODE>name</CODE>, which must be
+a string value, grouping all index entries that have a <EM>sort key</EM>
+beginning with the prefix <CODE>name</CODE>. The command
+<P>
+<PRE>
+ (define-letter-group "a")
+</PRE>
+<P>is equivalent to the command
+<P>
+<PRE>
+ (define-letter-group "a" :prefixes ("a"))
+</PRE>
+<P>Using the latter form one can associate more than one prefix with a
+given letter group. Also further prefixes can be added to an already
+existing letter group by simply defining the same letter group again.
+This results not in a redefinition but in adding more prefixes to the
+currently defined prefixes.
+<P>Example:
+<P>
+<PRE>
+ (define-letter-group "a")
+</PRE>
+<P>defines a letter group containing all index entries beginning with the
+string <CODE>"a"</CODE>.
+<P>
+<PRE>
+ (define-letter-group "c" :after "a")
+</PRE>
+<P>defines a letter group containing all index entries beginning with the
+string <CODE>"c"</CODE>. The letter group appears behind the letter group "a"
+<P>
+<PRE>
+ (define-letter-group "b" :after "a" :before "c")
+</PRE>
+<P>inserts letter group "b" between letter group "a" and "c". This allows
+incremental definition of letter groups by extending already defined
+ones.
+<P>The arguments <CODE>:after</CODE> and <CODE>:before</CODE> define a partial order on
+the letter groups. <SF>xindy</SF> tries to convert this partial order into
+a total one. If this is impossible due to circular definitions, an
+error is reported. If more than one possible total ordering can
+result, it is left open which one is used, so one should always define
+a complete total order.
+<P>The command <CODE>define-letter-groups</CODE> (with an `s' at the end) is
+simply an abbreviation for a sequence of
+<CODE>define-letter-group</CODE> definitions where the elements are ordered in
+the ordering given by the list. Example:
+<P>
+<PRE>
+ (define-letter-groups ("a" "b" "c")
+</PRE>
+<P>equals the definitions
+<P>
+<PRE>
+ (define-letter-group "a")
+ (define-letter-group "b" :after "a")
+ (define-letter-group "c" :after "b")
+</PRE>
+<P>See also commands <CODE>markup-letter-group-list</CODE> and
+<CODE>markup-letter-group</CODE> for further information.
+<P>
+<P>
+<P>
+<A NAME="define-location-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class name layer-list
+ [:min-range-length num]
+ [:hierdepth depth]
+ [:var])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines <CODE>name</CODE> to be a location class consisting of the given list
+of layers. A list of layers consists of names of basetypes and/or
+strings representing separators. Separators must follow the
+keyword argument <CODE>:sep</CODE>. If the keyword <CODE>:min-range-length</CODE> is
+specified we define the <EM>minimum range length</EM> to be used when
+building ranges. The argument <CODE>num</CODE> must be a positive integer
+number or the keyword <CODE>none</CODE> in which case the building of ranges
+is disallowed. If the switch <CODE>:var</CODE> is specified the declared class
+is of type <EM>variable</EM>, i.e. it is a <EM>var-location-class</EM>. Since
+building of ranges is currently only allowed for standard classes
+<CODE>:var</CODE> and <CODE>:min-range-length</CODE> must not be used together. The
+keyword argument <CODE>:hierdepth</CODE> can be used to declare that the
+location references have to be tagged in a hierarchical form. Its
+argument <CODE>depth</CODE> must be an integer number indicating the number of
+layers the hierarchy does contain. See command
+<CODE>markup-locref-list</CODE> for more information. Examples:
+<P>
+<PRE>
+ (define-location-class "page-numbers" ("arabic-numbers")
+ :minimum-range-length 3)
+</PRE>
+<P>Defines the location class <CODE>page-numbers</CODE> consisting of one layer
+which is the alphabet <CODE>arabic-numbers</CODE>. Since the minimum
+range length is set to 3 the location references 2, 3 and 4 don't form
+a range because the range length is only 2. But the references 6, 7,
+8, and 9 are enough to form a range. Some example instances of this
+class are <CODE>0</CODE>, <CODE>1</CODE>, ... <CODE>2313</CODE>, etc.
+<P>
+<PRE>
+ (define-location-class "sections" :var
+ ("arabic-numbers" :sep "."
+ "arabic-numbers" :sep "."
+ "arabic-numbers"))
+</PRE>
+<P>defines a variable location class. Valid instances are <CODE>1</CODE>,
+<CODE>1.1</CODE>, <CODE>1.2</CODE>, <CODE>2</CODE>, <CODE>2.4.5</CODE>, but none of <CODE>2-3</CODE> (wrong
+separator), <CODE>1.2.3.4</CODE> (more than 3 layers), <CODE>2.3.iv</CODE> (roman
+number instead of arabic one).
+<P>
+<P>
+<P>
+<A NAME="define-location-class-order"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class-order list)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the order in which the location classes are written to the
+output file. The parameter <CODE>list</CODE> is a list of names of
+location classes. Examples:
+<P>
+<PRE>
+ (define-location-class-order
+ ("page-numbers" "sections" "xrefs"))
+</PRE>
+<P>tells the system that the page numbers should appear before the
+section numbers and that the cross references should appear at the
+end. If this command is omitted, the declaration order of the
+location classes in the index style is implicitly used as the output
+order. In the case that a location class does not appear in the list,
+the output may behave unexpectedly, so one should always enumerate all
+used location classes when using this command.
+<P>
+<P>
+<P>
+<A NAME="define-rule-set"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-rule-set name
+ [ :inherit-from ("rule-set" "rule-set-2") ]
+ :rules (&lt;rule>...) )
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A complete specification of a multi-phase sorting process for a
+language requires that some rules have to appear in several subsequent
+sorting phases. Rule sets can be used to define a set of rules that
+can be instantiated in an arbitrary sorting phase. Basically, they
+offer means to separate the definition of sorting rules from their
+instantiation, hence, acting as a wrapper for calls to <CODE>sort-rule</CODE>.
+They do not add new functionality that is not already present with
+<CODE>sort-rule</CODE>.
+<P>A rule can be of the form:
+<P>
+<PRE>
+ &lt;rule> ::= ("pattern" "replacement"
+ [:string|:bregexp|:egegexp] [:again])
+</PRE>
+<P>The following incomplete example defines a new rule set of name
+<CODE>isolatin1-tolower</CODE> that inherits definitions from rule set
+<CODE>latin-tolower</CODE>, overriding or adding the sort rules in the list of
+<CODE>:rules</CODE>.
+<P>
+<PRE>
+ (define-rule-set "isolatin1-tolower"
+
+ :inherit-from ("latin-tolower")
+
+ :rules (("À" "à" :string :again)
+ ("Á" "á" :string :again)
+ ("Â" "â" :string :again)
+ ("Ã" "ã" :string :again)
+ ("Ä" "ä" :string :again)
+ ("Å" "å" :string :again)
+ ("Æ" "æ" :string :again)
+ ...
+ )
+ ...)
+</PRE>
+<P>Rule sets can be instantiated with the command <CODE>use-rule-set</CODE>. For
+further descriptions on the sorting model refer to the command
+<CODE>sort-rule</CODE>.
+<P>
+<P>
+<A NAME="define-sort-rule-orientations"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-sort-rule-orientations (orientations...))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the order for the different sorting phases. The currently
+implemented <EM>orientations</EM> are <CODE>forward</CODE> and <CODE>backward</CODE>. This
+command must precede all <CODE>sort-rule</CODE> commands in an index style. It
+defines the orientations and implicitly sets the maximum number of
+sorting phases performed.
+<P>For further descriptions on the sorting model refer to the command
+<CODE>sort-rule</CODE>.
+<P>
+<P>
+<P>
+<A NAME="merge-rule"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-rule pattern replacement [:again]
+ [:bregexp | :eregexp | :string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines a keyword mapping rule that can be used to generate the
+<EM>merge key</EM> from the <EM>main key</EM> of an index entry. This mapping
+is necessary to map all keywords that are differently written but
+belong to the same keyword to the same canonical keyword.
+<P>The parameter <CODE>pattern</CODE> can be a POSIX-compliant regular expression
+or an ordinary string. The implementation uses the GNU Rx regular
+expression library which implements the POSIX regular expressions.
+Regular expressions (REs) can be specified as <EM>basic regular
+expressions</EM> (BREs) or <EM>extended regular expressions</EM> (EREs). You
+can use the switch <CODE>:bregexp</CODE> to force the interpretation of the
+pattern as a BRE, or <CODE>:eregexp</CODE> to interpret it as an ERE. If you
+want <SF>xindy</SF> to interpret the pattern literally, use the switch
+<CODE>:string</CODE>. If none of these switches is selected, <SF>xindy</SF> uses
+an auto-detection mechanism to decide, if the pattern is a regular
+expression or not. If it recognizes the pattern as a RE, it interprets
+it as an ERE by default.
+<P>The parameter <CODE>replacement</CODE> must be
+a string possibly containing the special characters <CODE>&amp;</CODE>
+(substitutes for the complete match) and <CODE>\1</CODE>,...,<CODE>\9</CODE>
+(substituting for the <EM>n</EM>-th submatch. Examples:
+<P>
+<PRE>
+ (merge-rule "A" "a")
+</PRE>
+
+replaces each occurrence of the uppercase letter `<CODE>A</CODE>' with its
+lowercase counterpart.
+<P>
+<PRE>
+ (merge-rule "\~"([AEOUaeou])" "\1")
+</PRE>
+
+transforms the TeX umlaut-letters into their stripped counterparts,
+such that `<CODE>\"A</CODE>' is treated as an `<CODE>A</CODE>' afterwards.
+<P>The following sequences have a special meaning:
+<P>`<CODE>~n</CODE>' : End of line symbol (<EM>linefeed</EM>).
+<P>`<CODE>~b</CODE>' : The ISO-Latin character with the lowest ordinal number.
+<P>`<CODE>~e</CODE>' : The ISO-Latin character with the highest ordinal number.
+<P>`<CODE>~~</CODE>' : The tilde character.
+<P>`<CODE>~"</CODE>' : The double quote character.
+<P>Tilde characters and double quotes have to be quoted themselves with a
+tilde character. The special characters `<CODE>~b</CODE>' and
+`<CODE>~e</CODE>' allow the definition of arbitrary sorting orders by
+rules. In connection with an additional character every position in
+the alphabet can be described. E.g. `<CODE>m~e</CODE>' is
+lexicographically placed between `<CODE>m</CODE>' and `<CODE>n</CODE>'.
+<P>Due to efficiency, rules that just exchange characters or substitute
+constant character sequences are not treated as regular expressions.
+Therefore, instead of using the rule
+<P>
+<PRE>
+ (merge-rule "[A-Z]" "&amp;x")
+</PRE>
+<P>it is more efficient (though less comfortable) to use
+<P>
+<PRE>
+ (merge-rule "A" "Ax")
+ (merge-rule "B" "Bx")
+ ...
+ (merge-rule "Z" "Zx")
+</PRE>
+<P>Usually rules are applied in order of their definition. Rules with a
+special prefix precede those that begin with a class of characters, so
+that the search pattern `<CODE>alpha</CODE>' is checked before `<CODE>.*</CODE>', but
+`<CODE>auto</CODE>' and `<CODE>a.*</CODE>' are checked in order of their definition.
+<P>The first rule from a style file that matches the input is
+applied and the process restarts behind the substituted text. If no
+rule could be applied, the actual character is copied from the input
+and the process continues with the next character.
+<P>Sometimes it is necessary to apply rules anew to the result of a
+transformation. By specifying the keyword argument <CODE>:again</CODE> in the
+merge rule the rule is marked as <EM>mutable</EM>, which means that after
+using this rule the transformation process shall restart at the same
+place. E.g. the rule
+<P>
+<PRE>
+ (merge-rule "\$(.*)\$" "\1" :again)
+</PRE>
+<P>deletes <EM>all</EM> surrounding `<CODE>$</CODE>' symbols from the input.
+<P>See also command <CODE>sort-rule</CODE>.
+<P>
+<P>
+<A NAME="merge-to"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(merge-to attr-from attr-to [:drop])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A <EM>merge rule</EM> says that the attribute <CODE>attr-from</CODE> can be used
+to build ranges in <CODE>attr-to</CODE>. Both attributes must name valid
+attribute names. The switch <CODE>:drop</CODE> indicates, that the original
+location reference with attribute <CODE>attr-from</CODE> has to be dropped
+(removed), if a successful range was built with location references in
+attribute <CODE>attr-to</CODE>. A detailed description is given in the section
+about processing phases.
+<P>
+<P>
+<P>
+<A NAME="require"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(require filename)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command allows to load more index style modules. The module is
+searched in the directories defined in the search path. The file is
+read in and processing of the current file continues. The argument
+<CODE>filename</CODE> must be a string. This allows to decompose the
+index style into several modules that can be included into the topmost
+index style file. Example:
+<P>
+<PRE>
+ (require "french/alphabet.xdy")
+ (require "french/sort-rules.xdy")
+ (require "tex/locations.xdy")
+ (require "tex/markup.xdy")
+</PRE>
+<P>Submodules can load other submodules as well. If a file is required
+that was already loaded, the <CODE>require</CODE> command is simply ignored
+and processing continues without including this file twice. See also
+command <CODE>searchpath</CODE>.
+<P>
+<P>
+<P>
+<A NAME="searchpath"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(searchpath {path-string | path-list})
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command adds the given paths to the list of paths, <SF>xindy</SF>
+searches for index style files. The argument <CODE>path-string</CODE> must be
+a colon-separated string of directory names. If this path ends with a
+colon the default search path is added to the end of the path list.
+Example:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ (searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>adds the specified directories to the search path. Since the last path
+ends with a colon, the built-in search path is added at the end.
+Specifying
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ (searchpath ("."
+ "/usr/local/lib/xindy"
+ "/usr/local/lib/xindy/english"
+ :default))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>yields exactly the same result as the example above. Here
+<CODE>path-list</CODE> must be a list of strings and/or the keyword(s)
+<CODE>:default</CODE> and <CODE>:last</CODE>. The keyword <CODE>:default</CODE> signifies that
+the default pathnames are to be inserted at the specified position in
+the list. The keyword <CODE>:last</CODE> allows to insert the currently active
+paths at the indicated position. Since this allows to insert the
+built-in paths at any position and incrementally adding new paths to
+the search path, this version of the command ist more flexible than
+the first version.
+<P>
+<P>
+<A NAME="sort-rule"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule pattern replacement [:run level] [:again])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines a keyword mapping rule that can be used to generate the
+<EM>sort key</EM> of an index entry from the <EM>merge key</EM>. This key is
+used to sort the index entries lexicographically after they have been
+merged using the merge key.
+<P>The argument <CODE>:run</CODE> indicates that this rule is only in effect
+a the specified <EM>level</EM> (default is level 0). For a detailed
+discussion on the definition of sort rules for different layers refer
+to the documentation about the new sorting scheme
+(<CODE>new-sort-rules</CODE>) that comes with this distribution.
+<P>See command <CODE>merge-rule</CODE> for more information about keyword
+rules.
+<P>
+<P>
+<P>
+<A NAME="use-rule-set"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(use-rule-set [:run phase]
+ [:rule-set ( &lt;rule-set>... ))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command instantiates the gives rule sets to be in effect at
+sorting phase <CODE>phase</CODE>. The order of the rule sets given with
+argument <CODE>:rule-set</CODE> is significant. Rule set entries of rule set
+appearing at the beginning of the list override entries in rule sets
+at the end of the list.
+<P>The following example declares that in phase 0 the rule sets
+<CODE>din5007</CODE> and <CODE>isolatin1-tolower</CODE> should be active, whereas in
+phase 2 the other rule sets have to be applied.
+<P>
+<PRE>
+ (use-rule-set :run 0
+ :rule-set ("din5007" "isolatin1-tolower"))
+
+ (use-rule-set :run 1
+ :rule-set ("resolve-umlauts"
+ "resolve-sharp-s"
+ "isolatin1-tolower"
+ ))
+</PRE>
+<P>For a discussion on rule sets refer to command <CODE>define-rule-set</CODE>.
+<P>
+<P>
+<P>
+<H2><A NAME="ss3.2">3.2 Markup Commands</A>
+</H2>
+
+<P>
+<P>The following commands can be used to define the markup of the index.
+They don't have any influence on the indexing process. Since the
+markup scheme is characterized by the concept of <EM>environments</EM>,
+the syntax and naming scheme of all commands follows a simple
+structure.
+<P>The commands can be separated into <EM>environment</EM> and
+<EM>list-environment</EM> commands. All commands of the first group
+support the keyword arguments <CODE>:open</CODE> and <CODE>:close</CODE>, whereas the
+second group additionally supports the keyword argument <CODE>:sep</CODE>. If
+one of these keyword arguments is missing, the default markup tag is
+<EM>always</EM> the empty tag. The <CODE>:open</CODE> tag is always printed before
+the object itself and the <CODE>:close</CODE> tag is always printed after the
+object has been printed. If a list is printed the <CODE>:sep</CODE>tag is
+printed between two elements of the list but not before the first
+element, or after the last one. All commands dealing with a list have
+the suffix `<CODE>-list</CODE>' as part of their command name.
+<P>Since the number of commands and the heavy usage of <EM>default</EM> and
+<EM>specialized</EM> tags makes the markup somehow complex (but very
+powerful) we have added a mechanism to trace the markup tags
+<SF>xindy</SF> omits during its markup phase with the command
+<CODE>markup-trace</CODE>.
+<P>Here follows the list of markup commands in alphabetical order with
+some of the commands grouped together.
+<P>
+<P>
+<A NAME="markup-attribute-group"></A>
+<A NAME="markup-attribute-group-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-attribute-group-list [:open string] [:close string]
+ [:sep string])
+
+(markup-attribute-group [:open string] [:close string]
+ [:group group-num])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Location class groups consist of lists of attribute groups. The markup
+of this list can be defined with the command
+<CODE>markup-attribute-group-list</CODE>.
+<P>To allow different markup for different attribute groups the command
+<CODE>markup-attribute-group</CODE> can be specialized on the group number
+with the keyword argument <CODE>:group</CODE> which must be an integer number.
+E.g., given are the groups <CODE>("definition" "theorem")</CODE> and
+<CODE>("default")</CODE> with group numbers 0 and 1, then
+<P>
+<PRE>
+ (markup-attribute-group :open "&lt;group0>" :close "&lt;/group0>"
+ :group 0)
+
+ (markup-attribute-group :open "&lt;group1>" :close "&lt;/group1>"
+ :group 1)
+</PRE>
+<P>can be used to assign different markup for both groups in a SGML-based
+language.
+<P>
+<P>
+<A NAME="markup-crossref-layer"></A>
+<A NAME="markup-crossref-layer-list"></A>
+<A NAME="markup-crossref-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-crossref-list [:open string] [:close string]
+ [:sep string]
+ [:class crossref-class])
+
+(markup-crossref-layer-list [:open string] [:close string]
+ [:sep string]
+ [:class crossref-class])
+
+(markup-crossref-layer [:open string] [:close string]
+ [:class crossref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A crossref class group contains cross references of the same class.
+The separator between the classes is defined with the
+<CODE>(markup-locclass-list :sep)</CODE>-parameter. A list of cross references
+can be tagged with the command <CODE>markup-crossref-list</CODE> that
+specializes on the <CODE>:class</CODE> argument.
+<P>Each cross reference is determined by a list of layers indicating
+the target of the cross reference. To define a suitable markup for
+such a list the command <CODE>markup-crossref-layer-list</CODE> can be used.
+<P>Each layer of a cross reference can be assigned two tags that
+specialize on the class of the reference, like all other commands.
+<P>A suitable markup for a cross reference class <CODE>see</CODE> within LaTeX2e
+could look like that:
+<P>
+<PRE>
+ (markup-crossref-list :class "see" :open "\emph{see} "
+ :sep "; ")
+ (markup-crossref-layer-list :class "see" :sep ",")
+ (markup-crossref-layer :class "see"
+ :open "\textbf{" :close "}")
+</PRE>
+<P>An example output could look like
+<P>
+<BLOCKQUOTE>
+... <EM>see</EM> <B>house</B>; <B>garden</B>,<B>winter</B>; <B>greenhouse</B>
+</BLOCKQUOTE>
+<P>
+<P>
+<A NAME="markup-index"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-index [:open string] [:close string]
+ [ :flat | :tree | :hierdepth depth ])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Defines the markup tags that enclose the whole index via the
+<CODE>:open</CODE> and <CODE>:close</CODE> parameters. Examples:
+<P>
+<PRE>
+ (markup-index :open "Here comes the index~n"
+ :close "That's all folks!~n")
+</PRE>
+<P>defines that the <CODE>:open</CODE> string is printed before the rest of the
+index and the <CODE>:close</CODE> string appears after the index is printed.
+<P>Additionally one can specify the form of the generated index. It is
+possible to produce flat indexes by specifying the switch <CODE>:flat</CODE>,
+to generate a tree with the <CODE>:tree</CODE> switch or any kind of mixture
+between both by specifying the depth up to which trees shall be built
+with the parameter <CODE>:hierdepth</CODE>. Its argument <CODE>depth</CODE> is the
+number of layers that can be formed into a tree. Therefore <CODE>:flat</CODE>
+is an abbrevation of <CODE>:hierdepth 0</CODE> and <CODE>:tree</CODE> is an
+abbrevation of <CODE>:hierdepth max-depth</CODE>, with <CODE>max-depth</CODE> being
+the maximum number of layers a keyword has. An example: the keywords
+<P>
+<PRE>
+ ("tree" "binary" "AVL")
+ ("tree" "binary" "natural")
+</PRE>
+<P>can be transformed in the following ways:
+<P>A flat index (<CODE>:flat</CODE> or <CODE>:hierdepth 0</CODE>)
+<P>
+<PRE>
+ tree binary AVL
+ tree binary natural
+</PRE>
+<P>with <CODE>:hierdepth 1</CODE>
+<P>
+<PRE>
+ tree
+ binary AVL
+ binary natural
+</PRE>
+<P>and a tree (<CODE>:tree</CODE> or <CODE>:hierdepth</CODE> &gt; 1)
+<P>
+<PRE>
+ tree
+ binary
+ AVL
+ natural
+</PRE>
+<P>Most often one will create tree-like indexes or ones that are flat.
+<P>
+<P>
+<A NAME="markup-indexentry-list"></A>
+<A NAME="markup-indexentry"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-indexentry-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-indexentry [:open string] [:close string]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Letter groups consists of a list of index entries. The command
+<CODE>markup-indexentry-list</CODE> defines the markup of these lists. The
+markup can be specialized on the depth if the index is hierarchically
+organized. The command
+<P>
+<PRE>
+ (markup-indexentry-list :open "\begin{IdxentList}"
+ :close "\end{IdxentList}"
+ :sep "~n")
+</PRE>
+<P>defines that the index entries of all layers are wrapped into the
+given markup tags. If additionally
+<P>
+<PRE>
+ (markup-indexentry-list :open "\begin{IdxentListII}"
+ :close "\end{IdxentListII}"
+ :sep "~n"
+ :depth 2)
+</PRE>
+<P>is defined, all index entry lists of all layers (except layer 2) are
+tagged according to the first specification, and the index entry list
+within depth 2 are tagged according to the second rule.
+<P>The command <CODE>markup-indexentry</CODE> defines the markup of an index entry
+at a given depth. Since index entries may also contain subentries and
+the markup for subentries may be different in different layers, the
+optional keyword argument <CODE>:depth</CODE> can be used to assign different
+markup for different layers. If depth is ommited the default markup
+for all possible depths is defined. The top-most index entries have
+depth 0.
+<P>
+<PRE>
+ (markup-indexentry :open "\begin{Indexentry}"
+ :close "\end{Indexentry}")
+</PRE>
+<P>defines that the index entries of all layers are wrapped into the
+given markup tags. If additionally
+<P>
+<PRE>
+ (markup-indexentry :open "\begin{IndexentryII}"
+ :close "\end{IndexentryII}"
+ :depth 2)
+</PRE>
+<P>is defined, all index entries of all layers (except layer 2) are tagged
+according to the first specification, and the index entries with depth
+2 are tagged according to the second rule.
+<P>
+<P>
+<A NAME="markup-keyword-list"></A>
+<A NAME="markup-keyword"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-keyword-list [:open string] [:close string]
+ [:sep string] [:depth integer])
+
+(markup-keyword [:open string] [:close string]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<P>The print key of an index entry consists of a list of strings. The
+markup of this list can be defined with the command
+<CODE>markup-keyword-list</CODE>. The keyword argument <CODE>:depth</CODE> may be
+specified to define the markup of the list at a particular depth.
+<P>The keyword of an index entry consists of a list of strings. Each of
+these components is tagged with the strings defined with the command
+<CODE>markup-keyword</CODE>. Since we maybe need different markup for
+different layers, the optional keyword argument can be used to
+specialize this markup for some depth.
+<P>
+<P>
+<A NAME="markup-letter-group-list"></A>
+<A NAME="markup-letter-group"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-letter-group-list [:open string] [:close string]
+ [:sep string])
+
+(markup-letter-group [:open string] [:close string] [:group group-name]
+ [:open-head string] [:close-head string]
+ [:upcase | :downcase | :capitalize])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The first command defines the markup of the letter group with name
+<CODE>group-name</CODE>. Since the markup of letter groups often contains the
+name of the letter group as a part of it, the other keyword arguments
+allow an additional markup for this group name. If one of the
+parameters <CODE>:open-head</CODE> and <CODE>:close-head</CODE> is specified
+additional markup is added as can be described as follows:
+<P>
+<PRE>
+ &lt;OPEN>
+ IF (:open-head OR :close-head)
+ &lt;OPEN-HEAD>
+ transformer-of(&lt;GROUP-NAME>)
+ &lt;CLOSE-HEAD>
+ FI
+ &lt;INDEXENTRIES...>
+ &lt;CLOSE>
+</PRE>
+<P>Here, <CODE>transformer-of</CODE> is a function that possibly transforms the
+string representing the group name into another string. The
+transformers we currently support can be specified with the switches
+<CODE>:upcase</CODE>, <CODE>:downcase</CODE> and <CODE>:capitalize</CODE> which result in the
+corresponding string conversions. If none of them is specified no
+transformation is done at all.
+<P>The command <CODE>markup-letter-group</CODE> defines the markup of the list of
+letter groups.
+<P>
+<P>
+<A NAME="markup-locclass-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locclass-list [:open string] [:close string]
+ [:sep string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Each index entry contains a list of location class groups. This markup
+command can be used to define the markup of this list.
+<P>
+<P>
+<A NAME="markup-locref"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref [:open string] [:close string]
+ [:class locref-class]
+ [:attr attribute]
+ [:depth integer])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The markup tags of a location reference can be specialized on the
+three arguments <CODE>:class</CODE>, <CODE>:attr</CODE> and additionally, if
+sub-references are used, <CODE>:depth</CODE>. Most often one will only use a
+tag depending on the attribute. For example, all location references
+with the attribute <CODE>definition</CODE> should appear in a font series like
+bold, emphasizing the importance of this location reference; those
+with the attribute <CODE>default</CODE> in font shape italic. The markup in
+this case would not specialize on the depth or any particular class. A
+valid definition, suitable for a usage within HTML, could look like
+this.
+<P>
+<PRE>
+ (markup-locref :open "&lt;B>" :close "&lt;/B>" :attr "definition")
+ (markup-locref :open "&lt;I>" :close "&lt;/I>" :attr "default")
+</PRE>
+<P>
+<P>
+<A NAME="markup-locref-class"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref-class [:open string] [:close string]
+ [:class locref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>All location references of a particular location reference class can
+be wrapped into the tags defined by this command. It specializes on
+the keyword argument <CODE>:class</CODE>.
+<P>
+<P>
+<A NAME="markup-locref-layer-list"></A>
+<A NAME="markup-locref-layer"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref-layer [:open string] [:close string]
+ [:depth integer] [:layer integer]
+ [:class locref-class])
+
+(markup-locref-layer-list [:open string] [:close string]
+ [:sep string]
+ [:depth integer]
+ [:class locref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A location reference contains a list of location reference layers. The
+second markup command can be used to markup this list. It specializes
+on the class of the location references and the depth (if
+sub-references are used).
+<P>The first command allows to tag the elements of a layer list
+differently. The first element of this list can is specialisable with
+<CODE>:layer 0</CODE>, the next element with <CODE>:layer 1</CODE>, etc. See the next
+example for an example.
+<P>
+<P>
+<A NAME="markup-locref-list"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-locref-list [:open string] [:close string] [:sep string]
+ [:depth integer] [:class locref-class])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>An attribute group contains a list of location references and/or
+ranges. Additionally a layered location reference itself may contain
+sub-references that are stored as a list of location references. We
+specialize the markup for these lists on the location class they
+belong to with the keyword argument <CODE>:class</CODE>, and on <CODE>:depth</CODE>
+that specializes on the different subentry levels when using
+location references with sub-references.
+<P>Given is a list of location references that have the class description
+<P>
+<PRE>
+ (define-location-class "Appendix"
+ ("ALPHA" :sep "-" "arabic-numbers")
+ :hierdepth 2)
+</PRE>
+<P>This location class has instances like <CODE>A-1</CODE>, <CODE>B-5</CODE>, etc. The
+keyword argument <CODE>:hierdepth 2</CODE> informs <SF>xindy</SF> to markup these
+location references in a hierarchical form. With the commands
+<P>
+<PRE>
+ (markup-locref-list :sep "; "
+ :depth 0 :class "Appendix")
+ (markup-locref-list :open " " :sep ","
+ :depth 1 :class "Appendix")
+ (markup-locref-layer :open "{\bf " :close "}" :layer 0
+ :depth 0 :class "Appendix")
+</PRE>
+<P>we obtain a markup sequence for some example data that could look like
+<P>
+<PRE>
+ {\bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="markup-range"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-range [:open string] [:close string] [:sep string]
+ [:class locref-class]
+ [:length num] [:ignore-end])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>A range consists of two location references. Markup can be specified
+with the <CODE>:open</CODE> and <CODE>:close</CODE> arguments and one separator given
+by the argument <CODE>:sep</CODE>.
+<P>Since both location references are tagged with markup defined by the
+command <CODE>markup-locref</CODE> a specialization on attributes or depth is
+not necessary. Specialization is allowed on the class they belong to,
+because the separator between two location refences may be different
+for each location class. Argument <CODE>:length</CODE> can be used to define
+different markup for different lengths. In conjunction with
+<CODE>:length</CODE> is may be useful not to print the second location
+reference at all. For example, one wishes to markup ranges of length 1
+in the form <EM>Xf.</EM> instead of <EM>X--Y</EM>. This can be accomplished
+with the switch <CODE>:ignore-end</CODE>.
+<P>The markup tags for a range <EM>(X,Y)</EM> can be described as follows:
+<P>
+<PRE>
+ &lt;OPEN>
+ Markup of location reference X
+ &lt;SEP>
+ IF (not :ignore-end)
+ Markup of location reference Y
+ FI
+ &lt;CLOSE>
+</PRE>
+<P>
+<P>The following tags can be used to define a range of page numbers
+(given in a location class <CODE>page-numbers</CODE>) without considering the
+open and close parameters:
+<P>
+<PRE>
+ (markup-range :sep "-" :class "page-numbers")
+</PRE>
+<P>Location ranges then appear separated by a hyphen in a form like this:
+<P>
+<PRE>
+ ..., 5-8, 19-23, ...
+</PRE>
+<P>
+<P>
+<A NAME="markup-trace"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-trace [:on] [:open string] [:close string])
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This command can be used to activate the tracing of all
+markup commands <SF>xindy</SF> executes. The switch <CODE>:on</CODE> activates the
+trace. If <CODE>:on</CODE> is omitted, the command line flag <CODE>-t</CODE> can be
+used as well. All tags which are emitted but not yet defined
+explicitly by the user are tagged with a symbolic notation indicating
+the commands that must be used to define this tag. The defaults for
+the keyword argument <CODE>:open</CODE> is `<CODE>&lt;</CODE>' and for <CODE>:close</CODE> is
+`<CODE>></CODE>'. The beginning of an example output could look like:
+<P>
+<PRE>
+ &lt;INDEX:OPEN>
+ &lt;LETTER-GROUP-LIST:OPEN>
+ &lt;LETTER-GROUP:OPEN ["a"]>
+ &lt;INDEXENTRY-LIST:OPEN [0]>
+ &lt;INDEXENTRY:OPEN [0]>
+ &lt;KEYWORD-LIST:OPEN [0]>
+ &lt;KEYWORD:OPEN [0]>
+ ...
+</PRE>
+<P>We use a simple indentation scheme to make the structure of the tags
+visible. The symbolic tag <CODE>&lt;LETTER-GROUP:OPEN ["a"]></CODE> for example
+indicates that the tag that can be specified with the command
+<P>
+<PRE>
+ (markup-letter-group :open "XXX" :group "a" ... )
+</PRE>
+<P>is emitted at this point in the markup process. By incrementally
+adding markup commands to the index, more and more tags can be defined
+until the whole markup is defined. This general mechanism should allow
+everyone understand the markup process. The best is to start with a
+small index, define the complete markup and afterwards process the
+whole index. Additionally one can enclose the symbolic tags into an
+environment that is neutral to the document preparation system, such
+as a comment. For TeX this could be
+<P>
+<PRE>
+ (markup-trace :open "%%" :close "~n")
+</PRE>
+<P>or a definition in the TeX document like
+<P>
+<PRE>
+ \def\ignore#1{}
+</PRE>
+<P>combined with the command
+<P>
+<PRE>
+ (markup-trace :open "\ignore{" :close "}")
+</PRE>
+<P>
+<P>
+<P>
+<A NAME="raw-index"></A> <H2><A NAME="ss3.3">3.3 Raw Index Interface</A>
+</H2>
+
+<P>
+<P>This section can be skipped if the reader is not interested in
+adapting <SF>xindy</SF> to a new document preparation system.
+<P>The raw index is the file that represents the index that is to be
+processed. Since many different document preparation systems may use
+different forms of index representations, their output must be
+transformed in a form readable by <SF>xindy</SF>. We also could have
+written an configurable parser performing this task, but usually a
+tool written with some text processing tools such as <CODE>perl</CODE>,
+<CODE>sed</CODE> or <CODE>awk</CODE> can achieve the same task as well. Therefore,
+adapting <SF>xindy</SF> to a completely different system can mostly be
+done by writing an appropriate raw index filter.
+<P>The format of the raw index interface of <SF>xindy</SF> is defined as
+follows:
+<P>
+<A NAME="indexentry"></A>
+<BLOCKQUOTE><CODE>
+<PRE>
+(indexentry { :key string-list [:print string-list]
+ | :tkey list-of-layers }
+ [:attr string]
+ { :locref string [:open-range | :close-range]
+ | :xref string-list } )
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The pseudo variable <EM>string</EM> is a sequence of characters
+surrounded by double quotes, e.g.
+<P>
+<PRE>
+ "Hi, it's me" "one" "a string with two \"double quotes\""
+</PRE>
+<P>are three examples of valid strings. If you need to include a
+double quote as a literal character, you must quote it itself with a
+backslash as shown in the third example. A <EM>string list</EM> is simply
+a list of strings separated by whitespaces and surrounded by round
+braces. An example of a string list is
+<P>
+<PRE>
+ ("This" "is" "a" "list" "of" "strings")
+</PRE>
+<P>So far about the syntax. The semantics of the different elements are
+described here.
+<P>
+<P>
+<DL>
+<P>
+<DT><B><CODE>:key</CODE></B><DD><P>The argument <EM>string list</EM> defines the keyword of
+the index entry. It must be a list of strings, since the keyword may
+consist of different layers such as <CODE>("heap" "fibonacci")</CODE>.
+<P>
+<DT><B><CODE>:print</CODE></B><DD><P>The optional <EM>print key</EM> defines the way the
+keyword has to be printed in the markup phase.
+<P>
+<DT><B><CODE>:tkey</CODE></B><DD><P>Another possibility to define the keys of an
+index entry is with the <CODE>:tkey</CODE> keyword argument. It can be used
+instead of the <CODE>:key</CODE> and <CODE>:print</CODE> arguments. Instead of
+specifying separately the key and the corresponding print key, we
+define the keyword by its layers. Each layer consist of a list of one
+or two strings. The first string will be interpreted as the main key,
+whereas the second one will become the print key. If the print key is
+ommited, the main key is taken instead. So the definition
+<P>
+<PRE>
+ :tkey (("This") ("is") ("a") ("bang" "BANG !!!"))
+</PRE>
+<P>is equivalent to
+<P>
+<PRE>
+ :key ("This" "is" "a" "bang")
+ :print ("This" "is" "a" "BANG !!!")
+</PRE>
+<P>
+<P>
+<DT><B><CODE>:locref</CODE></B><DD><P>The reference an index entry describes can be a
+<EM>location reference</EM> or a <EM>cross reference</EM>. The switch
+<CODE>:locref</CODE> describes a location reference. Its optional arguments
+are <CODE>:open-range</CODE> and <CODE>:close-range</CODE>. The <EM>string</EM> that must
+be supplied must somehow encode the location reference. It might look
+like the string <CODE>"25"</CODE> representing the page number 25, or
+<CODE>"Appendix-I"</CODE> representing the first appendix numbered in
+uppercase roman numerals.
+<P>
+<DT><B><CODE>:open-range</CODE>,<CODE>:close-range</CODE></B><DD><P>These are switches that do not
+take any arguments. They describe the beginning and ending of a
+<EM>range</EM>, starting or ending from the location reference that is
+given by the argument <CODE>:locref</CODE>. If they are supplied, the
+location reference may have influence on the way ranges are build.
+<P>
+<DT><B><CODE>:xref</CODE></B><DD><P>These arguments choose the second alternative. The
+argument <EM>string list</EM> of parameter <CODE>:xref</CODE> describes where the
+index entry should point to.
+<P>
+<DT><B><CODE>:attr</CODE></B><DD><P>This parameter may be used to tag a location reference
+with a certain attribute or it names the class of a cross reference.
+It may also used to associate different markup for different
+attributes in the markup phase. If this parameter is omitted or is the
+empty string, the indexentry is declared to have the attribute
+<CODE>default</CODE>.
+<P>
+</DL>
+<P>Some examples:
+<P>
+<PRE>
+ (indexentry :key ("airplane") :locref "25" :attr "default")
+</PRE>
+<P>defines an index entry with the key `airplane' indexed on page '25'.
+This index entry has the attribute <CODE>default</CODE>.
+<P>
+<PRE>
+ (indexentry :key ("house") :xref ("building") :attr "see")
+</PRE>
+<P>defines a cross reference with the key 'house' pointing to the term
+'building'. This cross reference belongs to the cross reference class
+<CODE>see</CODE>.
+<P>
+<PRE>
+ (indexentry :key ("house") :xref ("building") :open-range)
+</PRE>
+<P>is an invalid specification, since <CODE>:open-range</CODE> mustn't be used
+together with cross references.
+<P>
+<P>
+<P>
+<HR>
+<A HREF="manual-4.html">Next</A>
+<A HREF="manual-2.html">Previous</A>
+<A HREF="manual.html#toc3">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-4.html b/Master/texmf-dist/doc/xindy/manual-4.html
new file mode 100644
index 00000000000..6d39d7ba240
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-4.html
@@ -0,0 +1,230 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: Processing Phases</TITLE>
+ <LINK HREF="manual-5.html" REL=next>
+ <LINK HREF="manual-3.html" REL=previous>
+ <LINK HREF="manual.html#toc4" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-5.html">Next</A>
+<A HREF="manual-3.html">Previous</A>
+<A HREF="manual.html#toc4">Contents</A>
+<HR>
+<H2><A NAME="startup-phase"></A> <A NAME="s4">4. Processing Phases</A></H2>
+
+<H2><A NAME="ss4.1">4.1 The Startup Phase</A>
+</H2>
+
+<P>After the system is started, <SF>xindy</SF> reads in the index style that
+is passed as a command line argument. Each <CODE>require</CODE> command is
+executed and the internal data structures representing the index style
+are built up. The index style must completely be read in before the
+raw index can be read.
+<P>
+<P>
+<A NAME="processing-phase"></A> <H2><A NAME="ss4.2">4.2 The Processing Phase</A>
+</H2>
+
+<P>The processing phase starts with reading the complete raw index. The
+name of the raw index file must be passed via the command line. All
+index entries are read in and pre-processed. All attributes and
+cross reference classes are checked if they are already known to the
+system. All strings representing location references are matched
+against all known location classes. Appropriate warnings are issued,
+if errors are encountered.
+<P>After the raw index has completely been read in, the
+location references of each index entry are merged, separated and
+sorted and the building of ranges takes place. This phase is the most
+complex one and we will describe it in detail.
+<P>
+<OL>
+<LI> All location references are separated according to the class
+they belong to. These groups are called <EM>location class groups</EM>.
+Possible groups are all defined location and crossref classes. See
+the commands <CODE>define-location-class</CODE> and
+<CODE>define-crossref-class</CODE> for a description how these classes can
+be defined.
+
+The classes are sorted according to an order that can be defined with
+the command <CODE>define-location-class-order</CODE>.
+</LI>
+<LI> The further processing of each location class group is
+different for the location classes and the crossref classes.
+
+<UL>
+<LI> Cross references are sorted lexicographically based on
+the ISO-Latin alphabet.
+
+<A NAME="sort-merge-locrefs"></A> </LI>
+<LI> To illustrate the processing of location references we assume
+the following list:
+
+<BLOCKQUOTE>
+ <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>13</B>,
+<B>14</B>, <B>16</B>, 14, 16
+</BLOCKQUOTE>
+
+
+The location references in italics own the attribute `important,
+those with in boldface have attribute `definition', and all others
+are own the attribute `default'. Imagine, the attribute groups were
+defined with the commands
+
+<BLOCKQUOTE><CODE>
+<PRE>
+ (define-attribute-groups (("definition" "important")
+ ("default")))
+
+ (merge-to "definition" "default" :drop)
+
+</PRE>
+</CODE></BLOCKQUOTE>
+
+
+See commands <CODE>define-attributes</CODE> and <CODE>merge-to</CODE> for a
+detailed description.
+
+The substitution rules are applied. This means that
+location references <B>13</B> and <B>14</B> with attribute `important'
+are <EM>substituted</EM> by the location references <EM>13</EM> and <EM>14</EM>
+with attribute `definition'. Substitution means removing from the
+list of location references.
+
+Substitution occurs because the definition of the attribute groups
+implicitly defines <CODE>"definition"</CODE> <EM>substitutes</EM>
+<CODE>"important"</CODE>.
+
+The resulting list is now
+
+<BLOCKQUOTE>
+ <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, 14,
+16
+</BLOCKQUOTE>
+
+
+<A NAME="def merge-to"></A> The <CODE>merge-to</CODE> rules are applied.
+Their meaning is to make location references appear with another
+attribute as well, but only in the function of supporting the
+building of ranges. They disappear after the ranges are built. The
+location references that cause new location refererences to be
+added are called <EM>parents</EM>, whereas the new ones are called
+<EM>childs</EM>. The example rule results in the adding of all
+refernces with attribute `definition' to the attribute `default'
+which results in the list
+
+<BLOCKQUOTE>
+ <EM>13</EM>, <EM>14</EM>, <EM>15</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, (13),
+14, (15), 16, (18)
+</BLOCKQUOTE>
+
+
+The childs are put in parenthesis since they may only be used to
+build up ranges.
+
+For each attribute we now try to build ranges. Since the switch
+<CODE>:drop</CODE> was specified we must start with the attribute
+`default', because a successful merging of location references may
+result in dropping the parents. This results in the range `13--16'.
+The childs
+(13) and (15) were used in the building of ranges, so their parents
+<EM>13</EM> and <EM>15</EM> have to be removed from the list of
+location references. This step would be omitted if the switch
+<CODE>:drop</CODE> were not specified. After unsucessfully trying to build
+more ranges and dropping the location references <EM>13</EM>, <EM>15</EM>
+and (18)--which was only meant to build ranges--we obtain the list
+
+<BLOCKQUOTE>
+<EM>14</EM>, <EM>18</EM>, <B>12</B>, <B>16</B>, 13--16
+</BLOCKQUOTE>
+
+
+Finally the attributes are brought into the right order. In our
+example the location references of the first attribute group are
+merged and sorted lexicographically resulting in two attribute groups
+
+<BLOCKQUOTE>
+(<B>12</B>, <EM>14</EM>, <B>16</B>, <EM>18</EM>) (13--16)
+</BLOCKQUOTE>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+</LI>
+</UL>
+
+</LI>
+</OL>
+<P>After all index entries have been processed the letter groups are
+formed and the index entries and location references are transformed
+into tree like structures as defined in the index style.
+<P>
+<P>
+<P>
+<A NAME="markup-phase"></A> <H2><A NAME="ss4.3">4.3 The Markup Phase</A>
+</H2>
+
+<P>After the index has completely been processed, the markup phase
+traverses the tree-like structure of the index. Each step triggers the
+appropriate markup events resulting in the emitting of markup tags.
+<P>
+<P>
+<P>
+<HR>
+<A HREF="manual-5.html">Next</A>
+<A HREF="manual-3.html">Previous</A>
+<A HREF="manual.html#toc4">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-5.html b/Master/texmf-dist/doc/xindy/manual-5.html
new file mode 100644
index 00000000000..072920545aa
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-5.html
@@ -0,0 +1,63 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: Index</TITLE>
+ <LINK HREF="manual-6.html" REL=next>
+ <LINK HREF="manual-4.html" REL=previous>
+ <LINK HREF="manual.html#toc5" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="manual-6.html">Next</A>
+<A HREF="manual-4.html">Previous</A>
+<A HREF="manual.html#toc5">Contents</A>
+<HR>
+<H2><A NAME="INDEX"></A> <A NAME="s5">5. Index</A></H2>
+
+<P>
+<P><B>List of Commands</B>
+<P>
+<A HREF="manual-3.html#define-attributes">define-attributes</A><BR>
+<A HREF="manual-3.html#define-alphabet">define-alphabet</A><BR>
+<A HREF="manual-3.html#define-crossref-class">define-crossref-class</A><BR>
+<A HREF="manual-3.html#define-letter-group">define-letter-group</A><BR>
+<A HREF="manual-3.html#define-letter-groups">define-letter-groups</A><BR>
+<A HREF="manual-3.html#define-location-class">define-location-class</A><BR>
+<A HREF="manual-3.html#define-location-class-order">define-location-class-order</A><BR>
+<A HREF="manual-3.html#define-rule-set">define-rule-set</A><BR>
+<A HREF="manual-3.html#define-sort-rule-orientations">define-sort-rule-orientations</A><BR>
+<A HREF="manual-3.html#indexentry">indexentry</A><BR>
+<A HREF="manual-3.html#markup-attribute-group">markup-attribute-group</A><BR>
+<A HREF="manual-3.html#markup-attribute-group-list">markup-attribute-group-list</A><BR>
+<A HREF="manual-3.html#markup-crossref-layer">markup-crossref-layer</A><BR>
+<A HREF="manual-3.html#markup-crossref-layer-list">markup-crossref-layer-list</A><BR>
+<A HREF="manual-3.html#markup-crossref-layer">markup-crossref-layer</A><BR>
+<A HREF="manual-3.html#markup-index">markup-index</A><BR>
+<A HREF="manual-3.html#markup-indexentry">markup-indexentry</A><BR>
+<A HREF="manual-3.html#markup-indexentry-list">markup-indexentry-list</A><BR>
+<A HREF="manual-3.html#markup-keyword">markup-keyword</A><BR>
+<A HREF="manual-3.html#markup-keyword-list">markup-keyword-list</A><BR>
+<A HREF="manual-3.html#markup-letter-group">markup-letter-group</A><BR>
+<A HREF="manual-3.html#markup-letter-group-list">markup-letter-group-list</A><BR>
+<A HREF="manual-3.html#markup-locclass-list">markup-locclass-list</A><BR>
+<A HREF="manual-3.html#markup-locref">markup-locref</A><BR>
+<A HREF="manual-3.html#markup-locref-class">markup-locref-class</A><BR>
+<A HREF="manual-3.html#markup-locref-layer">markup-locref-layer</A><BR>
+<A HREF="manual-3.html#markup-locref-layer-list">markup-locref-layer-list</A><BR>
+<A HREF="manual-3.html#markup-locref-list">markup-locref-list</A><BR>
+<A HREF="manual-3.html#markup-range">markup-range</A><BR>
+<A HREF="manual-3.html#markup-trace">markup-trace</A><BR>
+<A HREF="manual-3.html#merge-rule">merge-rule</A><BR>
+<A HREF="manual-3.html#merge-to">merge-to</A><BR>
+<A HREF="manual-3.html#require">require</A><BR>
+<A HREF="manual-3.html#searchpath">searchpath</A><BR>
+<A HREF="manual-3.html#sort-rule">sort-rule</A><BR>
+<A HREF="manual-3.html#use-rule-set">use-rule-set</A><P>
+<P>
+<P>
+<HR>
+<A HREF="manual-6.html">Next</A>
+<A HREF="manual-4.html">Previous</A>
+<A HREF="manual.html#toc5">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-6.html b/Master/texmf-dist/doc/xindy/manual-6.html
new file mode 100644
index 00000000000..dfbf33ccc91
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-6.html
@@ -0,0 +1,53 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: References</TITLE>
+ <LINK HREF="manual-5.html" REL=previous>
+ <LINK HREF="manual.html#toc6" REL=contents>
+</HEAD>
+<BODY>
+Next
+<A HREF="manual-5.html">Previous</A>
+<A HREF="manual.html#toc6">Contents</A>
+<HR>
+<H2><A NAME="s6">6. References</A></H2>
+
+<P>
+<P>The following books and papers were referenced in this document.
+<P>
+<OL>
+<LI> D. E. Knuth, <EM>The TeXbook</EM>, Addison-Wesley, 1984
+</LI>
+<LI> Leslie Lamport, LaTeX <EM>A Document Preparation System</EM>,
+Addison-Wesley, 1986
+</LI>
+<LI> Joachim Schrod, <EM>An International Version of MakeIndex</EM>,
+Cahiers GUTenberg, 10, p81-90, 1991
+</LI>
+<LI> Pehong Chen and Michael A. Harrison, <EM>Automating Index
+Preparation</EM>, TR-87/347, University of California Berkeley, 1987
+<A NAME="makeindex"></A>
+</LI>
+<LI> Roger Kehr, <SF>xindy</SF>, <EM>Ein Flexibles Indexierungssystem</EM>,
+Studienarbeit FB Informatik, TH-Darmstadt, November 1995.
+</LI>
+<LI> Joachim Schrod and Gabor Herr, <EM>MakeIndex Version 3.0</EM>,
+Technical University Darmstadt, 1991
+</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 <SF>xindy</SF>
+homepage.
+</LI>
+<LI> Roger Kehr, <SF>xindy</SF> -- <EM>A Flexible Indexing System</EM>,
+Proceedings of the EuroTeX'98, St. Malo, France, March 1998
+</LI>
+</OL>
+<P>
+<HR>
+Next
+<A HREF="manual-5.html">Previous</A>
+<A HREF="manual.html#toc6">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual-7.html b/Master/texmf-dist/doc/xindy/manual-7.html
new file mode 100644
index 00000000000..c1c26ed507a
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual-7.html
@@ -0,0 +1,53 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual: References</TITLE>
+ <LINK HREF="manual-6.html" REL=previous>
+ <LINK HREF="manual.html#toc7" REL=contents>
+</HEAD>
+<BODY>
+Next
+<A HREF="manual-6.html">Previous</A>
+<A HREF="manual.html#toc7">Contents</A>
+<HR>
+<H2><A NAME="s7">7. References</A></H2>
+
+<P>
+<P>The following books and papers were referenced in this document.
+<P>
+<OL>
+<LI> D. E. Knuth, <EM>The TeXbook</EM>, Addison-Wesley, 1984
+</LI>
+<LI> Leslie Lamport, LaTeX <EM>A Document Preparation System</EM>,
+Addison-Wesley, 1986
+</LI>
+<LI> Joachim Schrod, <EM>An International Version of MakeIndex</EM>,
+Cahiers GUTenberg, 10, p81-90, 1991
+</LI>
+<LI> Pehong Chen and Michael A. Harrison, <EM>Automating Index
+Preparation</EM>, TR-87/347, University of California Berkeley, 1987
+<A NAME="makeindex"></A>
+</LI>
+<LI> Roger Kehr, <SF>xindy</SF>, <EM>Ein Flexibles Indexierungssystem</EM>,
+Studienarbeit FB Informatik, TH-Darmstadt, November 1995.
+</LI>
+<LI> Joachim Schrod and Gabor Herr, <EM>MakeIndex Version 3.0</EM>,
+Technical University Darmstadt, 1991
+</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 <SF>xindy</SF>
+homepage.
+</LI>
+<LI> Roger Kehr, <SF>xindy</SF> -- <EM>A Flexible Indexing System</EM>,
+Proceedings of the EuroTeX'98, St. Malo, France, March 1998
+</LI>
+</OL>
+<P>
+<HR>
+Next
+<A HREF="manual-6.html">Previous</A>
+<A HREF="manual.html#toc7">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/manual.html b/Master/texmf-dist/doc/xindy/manual.html
new file mode 100644
index 00000000000..344b0e19cab
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/manual.html
@@ -0,0 +1,73 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>xindy Manual</TITLE>
+ <LINK HREF="manual-1.html" REL=next>
+
+
+</HEAD>
+<BODY>
+<A HREF="manual-1.html">Next</A>
+Previous
+Contents
+<HR>
+<H1><SF>xindy</SF> Manual</H1>
+
+<H2>Roger Kehr</H2>
+<H3>Computer Science Department, Technical University of Darmstadt</H3>
+ and
+<H2>Joachim Schrod</H2>
+<H3>Joachim Schrod Net &amp; Publication Consultance GmbH</H3>
+$Revision: 1.19 $, $Date: 2004/05/24 21:43:16 $,
+for xindy version 2.2
+<P><HR>
+<EM>This is the manual of the indexing system <SF>xindy</SF>. <SF>xindy</SF>
+is a powerful and flexible framework for generating indexes for many
+kinds of documents. This document describes the <SF>xindy</SF> processing
+model, terminology, and language, but not invocation and standard modules.
+The most up-to-date version can be obtained from the <SF>xindy</SF> Web Site at
+<A HREF="http://www.xindy.org/">http://www.xindy.org/</A>.</EM>
+<HR>
+<P>
+<A HREF="manual-5.html#INDEX">Index of all xindy commands</A><P>
+<P>
+<P>
+<P>
+<H2><A NAME="toc1">1.</A> <A HREF="manual-1.html">About this Manual</A></H2>
+
+<P>
+<H2><A NAME="toc2">2.</A> <A HREF="manual-2.html">How the Index Processor Works</A></H2>
+
+<UL>
+<LI><A HREF="manual-2.html#ss2.1">2.1 Data Flow</A>
+<LI><A HREF="manual-2.html#ss2.2">2.2 General Concepts and Terms</A>
+</UL>
+<P>
+<H2><A NAME="toc3">3.</A> <A HREF="manual-3.html">Command List</A></H2>
+
+<UL>
+<LI><A HREF="manual-3.html#ss3.1">3.1 Processing Commands</A>
+<LI><A HREF="manual-3.html#ss3.2">3.2 Markup Commands</A>
+<LI><A HREF="manual-3.html#ss3.3">3.3 Raw Index Interface</A>
+</UL>
+<P>
+<H2><A NAME="toc4">4.</A> <A HREF="manual-4.html">Processing Phases</A></H2>
+
+<UL>
+<LI><A HREF="manual-4.html#ss4.1">4.1 The Startup Phase</A>
+<LI><A HREF="manual-4.html#ss4.2">4.2 The Processing Phase</A>
+<LI><A HREF="manual-4.html#ss4.3">4.3 The Markup Phase</A>
+</UL>
+<P>
+<H2><A NAME="toc5">5.</A> <A HREF="manual-5.html">Index</A></H2>
+
+<P>
+<H2><A NAME="toc6">6.</A> <A HREF="manual-6.html">References</A></H2>
+
+<HR>
+<A HREF="manual-1.html">Next</A>
+Previous
+Contents
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/mappings.gif b/Master/texmf-dist/doc/xindy/mappings.gif
new file mode 100644
index 00000000000..be58722f4d9
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/mappings.gif
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial-1.html b/Master/texmf-dist/doc/xindy/style-tutorial-1.html
new file mode 100644
index 00000000000..890b1ecd8b9
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial-1.html
@@ -0,0 +1,92 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY Style File Tutorial: About xindy</TITLE>
+ <LINK HREF="style-tutorial-2.html" REL=next>
+
+ <LINK HREF="style-tutorial.html#toc1" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="style-tutorial-2.html">Next</A>
+Previous
+<A HREF="style-tutorial.html#toc1">Contents</A>
+<HR>
+<H2><A NAME="s1">1. About <SF>xindy</SF></A></H2>
+
+<P><SF>xindy</SF> means fle<B>x</B>ible <B>ind</B>exing s<B>y</B>stem. It is an
+indexing system that can be used to generate book-like indexes for
+arbitrary document preparation systems. This term includes systems
+such as TeX [1] and LaTeX [2], the Nroff-family
+or SGML-based systems (e.g. HTML) that process some kind of text and
+generate indexing information. It is not fixed to any specific system,
+but can be configured for a wide variety of purposes.
+<P>Authors sometimes wish to include an index into their document, but
+very often their document preparation systems aren't able to produce
+indexes on their own, or the capabilities of the built-in indexers are
+insufficient and produce ugly looking results. More often they use
+separate specialized tools for this purpose, sometimes called
+<EM>index processors</EM>.
+<P>In comparison to other index processors <SF>xindy</SF> has several
+powerful features that make it an ideal framework for describing and
+generating complex indexes. Its most interesting features are
+<P>
+<DL>
+<P>
+<DT><B>Internationality</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 even be
+processed by many index processors let alone 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 language specific rules. One example of such a rule would
+be
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule "ä" "ae")
+</PRE>
+</CODE></BLOCKQUOTE>
+<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 on can express the complete rules of a specific language.
+<P>
+<DT><B>User Definable Location Types</B><DD><P>Locations are the entities an
+index entry points to. Often used locations are <EM>page numbers</EM>,
+<EM>section numbers</EM>, etc. <SF>xindy</SF> allows to define new kinds of
+types to be composed of basic entities like arabic numbers, roman
+numerals, letters, etc. which can be used to describe new index types.
+Examples of these entities can be books that have a page numbering
+scheme that starts from 1 for each new chapter resulting in page
+numbers of the form <EM>1-13, 2-15, 2-20</EM>, etc. This type of locations
+can often be found in computer manuals. A more complex structure is
+represented by the locations <EM>Psalm 46, 1-8</EM> and <EM>Genesis 1,
+31</EM>. Even the structure of bible verses can be described allowing
+<SF>xindy</SF> to correctly sort and process indexes for documents with a
+completely different structure.
+<P>
+<DT><B>Highly Configurable Markup</B><DD><P>Since a index processor is only one
+component in a document preparation system it ought to fit smoothly
+into the complete environment. Many text processing systems use the
+concept of <EM>environments</EM> that can be used to describe the markup
+of the text entities. Our approach is based on this concept which has
+proved to be expressive enough for most applications. As an example
+one can view systems such as TeX, SGML and its instance HTML, GNU
+Info, RTF and the Nroff-familiy of document formatters. The markup of
+an index can be defined for all of these systems in a very comfortable
+though extremly powerful way.
+<P>
+</DL>
+<P>
+<P>
+<P>
+<HR>
+<A HREF="style-tutorial-2.html">Next</A>
+Previous
+<A HREF="style-tutorial.html#toc1">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial-2.html b/Master/texmf-dist/doc/xindy/style-tutorial-2.html
new file mode 100644
index 00000000000..b5313e59d72
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial-2.html
@@ -0,0 +1,361 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY Style File Tutorial: A Basic Introduction</TITLE>
+ <LINK HREF="style-tutorial-3.html" REL=next>
+ <LINK HREF="style-tutorial-1.html" REL=previous>
+ <LINK HREF="style-tutorial.html#toc2" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="style-tutorial-3.html">Next</A>
+<A HREF="style-tutorial-1.html">Previous</A>
+<A HREF="style-tutorial.html#toc2">Contents</A>
+<HR>
+<H2><A NAME="s2">2. A Basic Introduction</A></H2>
+
+<P>This section incrementally introduces the most important aspects of
+the system. After reading this chapter you should be able to specify
+style files for
+about 80% of the commonly used indexes. The examples are demonstrated
+with a TeX markup so one can easily typeset the results <SF>xindy</SF>
+produces. You need LaTeX and the ISO-Latin enhancements that come
+with the <CODE>inputenc</CODE> package to run the following examples. Also the
+<SF>xindy</SF> system must already be installed.
+<P>
+But this tutorial doesn't reflect real life any more. The concepts are
+introduced below to explain them, but actual usage is probably
+different. In particular, you should not expect to specify sort rules
+by hand; usually one uses the language modules for that. Same way,
+xindy standard modules provide lots of markup functionality that you
+need for your documents, and can be used as a starting point.
+Nevertheless, let's continue with the explanation of <sf>xindy</sf>'s
+style file language.
+<P>
+<H2><A NAME="ss2.1">2.1 Running <SF>xindy</SF></A>
+</H2>
+
+<P>Create a new directory somewhere and copy some files from the
+distribution directory <CODE>doc/style-tutorial/</CODE> by typing
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+eg$ mkdir tutorial
+eg$ cd tutorial
+eg$ cp &lt;distrib-dir>/doc/style-tutorial/*.raw .
+eg$ cp &lt;distrib-dir>/doc/style-tutorial/*.tex .
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>with <CODE>distrib-dir</CODE> replaced by the actual location. Now create a
+file <CODE>style1.xdy</CODE> with the following content:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+;; This is a first example using `xindy'.
+
+(define-location-class "page-numbers" ("arabic-numbers"))
+(define-attributes (("definition" "usage")))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Now run <SF>xindy</SF> by typing
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+eg$ xindy -t ex1.xlg -M style1 -I xindy ex1.raw
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>You should see something like
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+Opening logfile "ex1.xlg" (done)
+Reading indexstyle...
+Loading module "style1.xdy"...
+Finished loading module "style1.xdy".
+Finished reading indexstyle.
+Finalizing indexstyle... (done)
+
+Reading raw-index "ex1.raw"...
+Finished reading raw-index.
+
+Processing index... [10%] [20%] [30%] [40%] [50%] [60%] [70%] [80%] [90%] [100%]
+Finished processing index.
+
+Writing markup... [10%] [20%] [30%] [40%] [50%] [60%] [70%] [80%] [90%] [100%]
+Markup written into file "ex1.ind".
+</PRE>
+</CODE></BLOCKQUOTE>
+<P><SF>xindy</SF> has now successfully compiled the index <CODE>ex1.raw</CODE> using
+your index style <CODE>style1.xdy</CODE>. The result is now stored in file
+<CODE>ex1.ind</CODE>. You can view this file but currently it only contains an
+unreadable mix of data.
+<P>But now let's come back to our index style. The syntax of the command
+is in a Lisp-like form with lots of braces, looking a little bit
+weird, but you'll soon get used to it. What is the meaning of the two
+commands we specified? The first command informed <SF>xindy</SF> that we
+like to process page numbers. We do this by defining a new
+<EM>location class</EM> named <CODE>page-numbers</CODE>. The page numbers consist
+of <CODE>arabic-numbers</CODE> as we might expect but this is not necessarily
+true---imagine your page numbers consisted of roman numerals instead.
+When reading the <EM>raw index</EM> contained in file <CODE>ex1.raw</CODE>
+<SF>xindy</SF> checks all locations if they match all known location
+classes. Since in our example the only known location class is the
+class of page numbers which are written using arabic digits, all
+locations will be checked if they are correct page numbers.
+<P>The second command tells <SF>xindy</SF> that we use two types of
+attributes for location references. Most often the locations in an
+index denote different meanings. For example, in mathematical texts
+one will distinguish the <EM>definition</EM> of a mathematical term from
+its <EM>usage</EM>. Sometimes these are typeset using different font
+shapes such as <EM>italic</EM> or font series such as <B>boldface</B>. Each
+location has an associated attribute which, if it is unspecified,
+defaults to the attribute <CODE>default</CODE>. With this command you have
+made these attributes known to the system, which makes it possible to
+assign different markup to these attributes later on.
+<P>
+<P>
+<H2><A NAME="ss2.2">2.2 Adding some Markup</A>
+</H2>
+
+<P>Until now you haven't seen something exciting, so its time to specify
+some markup. Add the following lines to our index style:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-index :open "~n\begin{theindex}~n"
+ :close "~n\end{theindex}~n"
+ :tree)
+
+(markup-locref :class "page-numbers" :attr "definition"
+ :open "{\bf " :close "}")
+
+(markup-locclass-list :open "\quad{}")
+(markup-locref-list :sep ", ")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Now run <SF>xindy</SF> again and afterwards LaTeX:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+eg$ xindy -t ex1.xlg -M style1 -I xindy ex1.raw
+eg$ latex ex1.tex
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>You can view <CODE>ex1.dvi</CODE> with your prefered viewer (maybe <CODE>xdvi</CODE>
+or something else) to get a first impression of your results. Maybe
+your are not satisfied (for sure you aren't), because it still looks
+very confusing. What did the above rules tell <SF>xindy</SF>? When you
+view the file <CODE>ex1.ind</CODE> which is the result <SF>xindy</SF> generates,
+you'll recognize some of the <EM>markup tags</EM> you specified. The
+following is an excerpt of this file:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\begin{theindex}
+ academia\quad{}{\bf 1}acafetado\quad{}{\bf 2}acalmar\quad{}{\bf 4}
+ açafrão\quad{}{\bf 3}indexflat\quad{}1hierarchical\quad{}2
+ veryhierarchical\quad{}3impressive\quad{}4saber\quad{}{\bf 7}
+ sabor\quad{}{\bf 8}sabão\quad{}{\bf 6}sábado\quad{}{\bf 5}
+\end{theindex}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>First of all you'll see that the file starts with the string
+<CODE>\begin{theindex}</CODE> and ends with <CODE>\end{theindex}</CODE>.
+Additionally some locations are correctly enclosed into a TeX macro
+that typesets them in shape boldface, whereas others aren't. The
+boldface ones are all those locations from the raw index that have the
+attribute <CODE>definition</CODE>.
+<P>The <CODE>:open</CODE> and <CODE>:close</CODE> keyword arguments each take a string as
+argument. The first one is written to the file when <EM>opening</EM> an
+enviroment, whereas the latter one <EM>closes</EM> an environment. What we
+have specified is the markup for the whole index (which is actually
+printed only once) and the markup for all locations of class
+<CODE>page-numbers</CODE> which own the attribute <CODE>definition</CODE>. Here we
+have cleanly separated the structured markup from the visual one,
+allowing an easy redefinition if we decide, for example, to markup the
+<CODE>definition</CODE>-locations in italics instead of boldface.
+<P>Some words on <EM>keyword arguments</EM> and <EM>switches</EM>. Keyword
+arguments such as <CODE>:open</CODE> or <CODE>:close</CODE> always take exactly one
+argument which must be positioned right after the keyword separated by
+a whitespace (a blank or a tab-stop). Switches don't take any
+arguments. For example, <CODE>:tree</CODE> in the command <CODE>markup-index</CODE> is
+a switch and thus it does not take an argument. We will use this
+terminology throughout the rest of this document.
+<P>The third command caused <SF>xindy</SF> to insert a horizontal space
+between the keyword and the locations (the TeX command
+<CODE>\quad{}</CODE> simply inserts a specific horizontal space). The last
+command caused <SF>xindy</SF> to separate all location references from
+each other with a comma followed by a blank, independently of any
+location class.
+<P>As you already may have observed, the tilde sign (<CODE>~</CODE>) serves
+as a <EM>quoting character</EM>.
+<P>We continue specifying markup to get a printable result by adding more
+markup:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-indexentry :open "~n \item " :depth 0)
+(markup-indexentry :open "~n \subitem " :depth 1)
+(markup-indexentry :open "~n \subsubitem " :depth 2)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This assigns different markup for the different hierarchy layers of
+the indexentries. Our index is hierarchically organized. It contains
+items which themselves contain more sub-items which also might contain
+sub-sub-items. Each layer is started by a different markup which is
+correctly assigned with the <CODE>:depth</CODE> keyword argument. The layers
+are numbered by their <EM>depth</EM> starting from zero.
+<P>Now run <SF>xindy</SF> and TeX again and enjoy your first index. It's
+easy, isn't it! The output <CODE>ex1.ind</CODE> looks like the following:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+\begin{theindex}
+
+ \item academia\quad{}{\bf 1}
+ \item acafetado\quad{}{\bf 2}
+ \item acalmar\quad{}{\bf 4}
+ \item açafrão\quad{}{\bf 3}
+ \item index
+ \subitem flat\quad{}1
+ \subitem hierarchical\quad{}2
+ \subitem very
+ \subsubitem hierarchical\quad{}3
+ \subsubitem impressive\quad{}4
+ \item saber\quad{}{\bf 7}
+ \item sabor\quad{}{\bf 8}
+ \item sabão\quad{}{\bf 6}
+ \item sábado\quad{}{\bf 5}
+
+\end{theindex}
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>Hmm, as you might have seen there are several problems that need
+further investigation. The index contains some Portuguese words that
+are printed correctly but should appear at other positions inside the
+index. For instance, the word <EM>sábado</EM> should appear before the
+word <EM>saber</EM> since <EM>á</EM> must be sorted as if it were simply an
+<EM>a</EM>. The reason why these words are not sorted correctly is
+simple---the accentuated letters have codes beyond position 128 in the
+ISO-Latin alphabet. Sorting based on these codes yields this incorrect
+order.
+<P>What to do? We can define for each of the words containing these
+special characters an explicit <EM>print key</EM>. The print key describes
+the printed representation of the keyword whereas the <EM>key</EM> or
+<EM>main key</EM> is used for sorting and merging. A very tedious task
+which is not a very clever solution since in a non-english language
+many many words contain these special cases. We follow the way
+<SF>xindy</SF> offers: <EM>keyword-mappings</EM>.
+<P>
+<H2><A NAME="ss2.3">2.3 Keyword Mappings</A>
+</H2>
+
+<P>What are keyword mappings for? A good question. I'll try to give some
+answers.
+<P>
+<UL>
+<LI> <EM>Merging of differently written words</EM>. Some text formatting
+systems allow different writings for the same word. For example, TeX
+can be used with ISO-Latin characters as well as with its own
+character sequences. If a document is composed from smaller ones
+possibly written by different authors using different forms of writing
+the index entries, the same terms may happen to be written differently
+and consequently we need a mechanism to identify them as equal.
+</LI>
+<LI> <EM>Specifying the sort order</EM>. As outlined in the previous
+section it is really difficult and error-prone to specify the sort key
+for each keyword explicitly. Sometimes the sort order is even
+different for the type of the document, as it happens in German, where
+two different types of sortings exist, one for everyday indexes and
+one for dictionaries. The sort order actually defines the position of
+arbitrary language-specific letters inside of an index.
+</LI>
+</UL>
+<P>A detailed elaboration of these ideas can be found in the paper <EM>An
+International Version of MakeIndex</EM> by Joachim Schrod [3].
+It describes the ideas that led to modifications on one of the
+ancestors of the <SF>xindy</SF> system: <CODE>makeindex</CODE> [4].
+<P>The keyword mappings are as follows. The <EM>merge key</EM> is generated
+from the <EM>main key</EM> with the so called <EM>merge mapping</EM>. The
+merge mapping can be specified with the command <CODE>merge-rule</CODE>. The
+<EM>sort key</EM> is derived from the merge key using the <EM>sort
+mapping</EM> specified with the <CODE>sort-rule</CODE> command. The following
+scheme shows this mapping process:
+<P>
+<FIGURE>
+<EPS FILE="mappings.eps">
+<IMG SRC="mappings.gif">
+</FIGURE>
+<P>
+<P>We will use this command now to define a suitable sort mapping that
+fits our needs:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(sort-rule "à" "a")
+(sort-rule "á" "a")
+(sort-rule "ã" "a")
+(sort-rule "è" "e")
+(sort-rule "é" "e")
+(sort-rule "ç" "c")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>These rules define mappings from a keyword to a <EM>normalized</EM>
+version. In the logfile <CODE>ex1.xlg</CODE> these transformations are logged so
+that one can see how these mappings are performed. In this example we
+do not need any <CODE>merge-rule</CODE> but we will see applications in
+further examples.
+<P>Running <SF>xindy</SF> and TeXing the result now places the indexentries
+at the right positions.
+<P>In reality, such sort rules tend to be much more complex, due to
+the idiosynchrasies of sorting natural languages. Sort rules for
+many languages are available as part of the xindy distribution, as
+so-called language modules. We specify the language with the option
+<code>-L</code>, e.g., in our example we could have used
+<BLOCKQUOTE><CODE>
+<PRE>
+eg$ xindy -t ex1.xlg -M style1 -L portuguese -I xindy ex1.raw
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>If we use one of the available language modules, sort rules in
+user-written xindy styles are ignored.
+<P>The result is now quite satisfying if the index entries weren't
+clumped together that much. We usually want the different index
+entries beginning with the same letter be optically separated from the
+ofhers. This improves readability and there must be a way to
+accomplish this---the <EM>letter groups</EM>.
+<P>
+<H2><A NAME="ss2.4">2.4 Letter Groups</A>
+</H2>
+
+<P>To group indexentries we must define what indexentries form a group.
+The clustering is done by matching the keywords' prefixes (taken from
+the <EM>sort key</EM>) with a user-defined table of prefixes and define
+appropriate markup that separates the groups from each other. Here it
+goes.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-letter-groups
+ ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m"
+ "n" "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z"))
+
+(markup-letter-group-list :sep "~n\indexspace")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This defines the given list of letter groups. When forming the letter
+groups, each letter group is checked if it matches a prefix of the
+indexentries' sort key. The longest match assigns the index entry to
+this letter group. If no match was possible the index entry is put into
+group <CODE>default</CODE>.
+<P>The result now looks much better than before. You have now learned the
+basic features that you need to specify everyday indexes. In the next
+chapter we'll continue to make you an expert in indexing.
+<P>
+<P>
+<HR>
+<A HREF="style-tutorial-3.html">Next</A>
+<A HREF="style-tutorial-1.html">Previous</A>
+<A HREF="style-tutorial.html#toc2">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial-3.html b/Master/texmf-dist/doc/xindy/style-tutorial-3.html
new file mode 100644
index 00000000000..5c598e54938
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial-3.html
@@ -0,0 +1,263 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY Style File Tutorial: Advanced Features</TITLE>
+ <LINK HREF="style-tutorial-4.html" REL=next>
+ <LINK HREF="style-tutorial-2.html" REL=previous>
+ <LINK HREF="style-tutorial.html#toc3" REL=contents>
+</HEAD>
+<BODY>
+<A HREF="style-tutorial-4.html">Next</A>
+<A HREF="style-tutorial-2.html">Previous</A>
+<A HREF="style-tutorial.html#toc3">Contents</A>
+<HR>
+<H2><A NAME="s3">3. Advanced Features</A></H2>
+
+<P>In the following sections you'll learn more about the features of
+<SF>xindy</SF>. We'll show you how you can define your own
+location classes, specify the letter groups in more detail and bring
+you close to more specfic markup features. After reading this chapter
+you should be able to master about 95% of the commonly used indexes.
+<P>
+<P>
+<H2><A NAME="ss3.1">3.1 Location Classes</A>
+</H2>
+
+<P>We continue using a more complex index. Copy the current style to a
+new file (now <CODE>style2.xdy</CODE>) and run <SF>xindy</SF> on the raw index
+<CODE>ex2.raw</CODE> by typing:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+eg$ cp style1.xdy style2.xdy
+eg$ xindy -t ex2.xlg -M style2 -I xindy ex2.raw
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>You should see some error messages indicating that something is
+unknown to <SF>xindy</SF>. What has happend? The messages should be
+similar to the following snapshot:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ ...
+WARNING:
+location-reference "B-5" did not match any location-class! (ignored)
+WARNING:
+location-reference "C-8" did not match any location-class! (ignored)
+WARNING:
+location-reference "iv" did not match any location-class! (ignored)
+WARNING:
+location-reference "ii" did not match any location-class! (ignored)
+ ...
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The index contains new, and therefore unknown, location classes. The
+first one has an appendix-like style, whereas the second one seems to
+be lowercase roman numerals. <SF>xindy</SF> reported, that it doesn't know
+these locations and therefore knows nothing about their internal
+structure. We make them known to the system by adding the following
+commands to the style file.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class "roman-pages" ("roman-numerals-lowercase"))
+(define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers"))
+(define-location-class-order ("roman-pages" "appendices"))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The first command tells <SF>xindy</SF> that there exist some page numbers
+that are written with roman lowercase letters. The second one defines
+the structure of the appendix locations. They consist of three
+elements, a capital letter, a separator---which is a hyphen in our
+case---and finally an arabic number. To be able to correctly
+distinguish separator strings from the names of the known
+<EM>basetypes</EM>, the argument <CODE>:sep</CODE> indicates, that the following
+is a separator. The last command simply says that the locations which
+are roman numerals shall appear before the appendix locations. So far
+we know three different basetypes. The built-in basetypes of
+<SF>xindy</SF> are:
+<P>
+<DL>
+<DT><B><CODE>arabic-numbers</CODE></B><DD><P>contains all non-negative numbers beginning
+with zero: 0, 1, 2, ....
+<P>
+<DT><B><CODE>roman-numerals-uppercase</CODE>, <CODE>roman-numerals-lowercase</CODE></B><DD><P>the
+roman numerals I, II, III, (IIII/IV), V, ... It contains the old and
+new roman numeral system. Two versions for uppercase and lowercase
+letters are supported.
+<P>
+<DT><B><CODE>ALPHA</CODE>, <CODE>alpha</CODE></B><DD><P>The US-ASCII alphabet letters (uppercase
+and lowercase letters).
+<P>
+<DT><B><CODE>digits</CODE></B><DD><P>the digits 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9 in this
+order.
+</DL>
+<P>`Fine,', you'll say, `but what if my basetypes are completely
+different?' You're right! But <SF>xindy</SF> offers you to define your own
+alphabets. For example, you can define a new alphabet by writing
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-alphabet "my-personal-alphabet" ("Hi" "ho" "here" "I" "go"))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This is a valid alphabet that consists of 5 <EM>letters</EM>. You can now
+define a location class
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class "my-personal-class"
+ ("my-personal-alphabet" :sep "-" "arabic-numbers"))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>to match all of the following locations: <EM>Hi-12, ho-2, here-709,
+I-9, go-42</EM>. <SF>xindy</SF> will recognize them and be able to sort them
+according to your specification which says that <EM>Hi</EM> comes before
+all others and <EM>here</EM> is exactly at the third position. So they
+will be sorted lexicographically, layer by layer, until it can decide
+which one is before or after the other. We have prepared a concrete
+example. Do you remember the example we gave when we spoke about
+indexing bible verses? This exactly matches the situation of such a
+self-defined alphabet which could look like the following definitions:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-alphabet "bible-chapters"
+ ("Genesis" "Exodus" "Leviticus" "Numbers" "Deuteronomy"
+ ... ))
+(define-location-class "bible-verses"
+ ("bible-chapters" :sep " " "arabic-numbers" :sep "," "arabic-numbers"))
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This description would match locations like <EM>Genesis 1,3</EM>,
+<EM>Exodus 7,8</EM>, etc.
+<P>Now run LaTeX on <CODE>ex2.tex</CODE> and view the results. It looks a
+little bit strange since <SF>xindy</SF> has automatically built ranges of
+successive locations. The first locations of the index entry <EM>roman</EM>
+actually denote the range <EM>ii</EM> until <EM>iv</EM>. <EM>Ranges</EM> consist
+of location references. To typeset them correctly you can specify
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(markup-range :sep "--")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>This indicates that location reference forming a range shall be
+separated by a hyphen. Running <SF>xindy</SF> and LaTeX again gives a
+better idea of how it should look like. Here is a part of the
+generated output.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ ...
+ \item appendices\quad{}A-1, A-7, A-11, B-3--B-5, C-1, C-8, C-12,
+ C-13, C-22, D-2, D-3, D-5, D-10
+ ...
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>
+<H2><A NAME="ss3.2">3.2 Hierarchical Location Classes</A>
+</H2>
+
+<P>Somehow a lot of space is wasted when looking at the first index entry.
+Modify the definition of the location class for appendices as follows
+and add the other commands as well:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-location-class "appendices"
+ ("ALPHA" :sep "-" "arabic-numbers")
+ :hierdepth 2)
+(markup-locref-list :sep "; " :depth 0 :class "appendices")
+(markup-locref-list :open "~~" :sep ", " :depth 1 :class "appendices")
+</PRE>
+</CODE></BLOCKQUOTE>
+<P><EM>Note: Since the tilde character serves as our quoting character it
+must be quoted itself in the above example.</EM> Run <SF>xindy</SF> and view
+the output stored in <CODE>ex2.ind</CODE>. The output looks similar to the
+following:
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ ...
+ \item appendices\quad{}A~1, 7, 11; B~3--5; C~1, 8, 12, 13, 22;
+ D~2, 3, 5, 10
+ ...
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>You can see that the location references of this class have been
+transformed into a hierarchical structure caused by the
+<CODE>:hierdepth</CODE> argument. Additionally we have specified markup for
+the layers of this class separately for the depths 0 and 1. The
+locations at depth 0 are separated by a `;' whereas the ones at depth
+1 are separated by a `,'.
+<P>Maybe you get an impression why we named <SF>xindy</SF> a <EM>flexible</EM>
+system.
+<P>
+<H2><A NAME="ss3.3">3.3 More about Letter Groups</A>
+</H2>
+
+<P>More problems arise when using languages with different letter
+schemes. Hungarian is an example. In Hungarian indexes the words
+beginning with the letters <EM>Cs, Ly, Ny</EM> and more are printed in a
+separate block. The words beginning with <EM>Ly</EM>, for example, appear
+behind the words beginning with an <EM>L</EM>. <SF>xindy</SF> allows to define
+this kind of letter groups as well. Add the following lines to the
+style file.
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+(define-letter-group "ly" :after "l" :before "m")
+(define-letter-group "ny" :after "n" :before "o")
+
+(markup-letter-group :open-head "~n {\bf " :close-head "}"
+ :capitalize)
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The result looks like the following:
+<P>
+<P>
+<BLOCKQUOTE><CODE>
+<PRE>
+ ...
+ {\bf Ly}
+ \item lyuk\quad{}1
+ \item lyukas\quad{}2
+
+ \indexspace
+
+ {\bf M}
+ \item maga\quad{}1
+ \item magyar\quad{}2
+
+ \indexspace
+
+ {\bf N}
+ \item nagy\quad{}1
+ \item nagyon\quad{}9
+ \item nègy\quad{}4
+
+ \indexspace
+
+ {\bf Ny}
+ \item nyelv\quad{}1
+ \item nyolc\quad{}8
+ ...
+</PRE>
+</CODE></BLOCKQUOTE>
+<P>The result describes what the purpose of the above commands is. It
+becomes prettier from step to step, doesn't it?
+<P>You have now learned most of the features of <SF>xindy</SF>. Go playing
+around a little bit. For a detailed description of all commands and
+all their arguments and switches you should reference the manual that
+comes with this distribution.
+<P>
+<P>
+<P>
+<HR>
+<A HREF="style-tutorial-4.html">Next</A>
+<A HREF="style-tutorial-2.html">Previous</A>
+<A HREF="style-tutorial.html#toc3">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial-4.html b/Master/texmf-dist/doc/xindy/style-tutorial-4.html
new file mode 100644
index 00000000000..f3ef19aa4c8
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial-4.html
@@ -0,0 +1,41 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY Style File Tutorial: References</TITLE>
+ <LINK HREF="style-tutorial-3.html" REL=previous>
+ <LINK HREF="style-tutorial.html#toc4" REL=contents>
+</HEAD>
+<BODY>
+Next
+<A HREF="style-tutorial-3.html">Previous</A>
+<A HREF="style-tutorial.html#toc4">Contents</A>
+<HR>
+<H2><A NAME="s4">4. References</A></H2>
+
+<P>
+<P>The following books and papers were referenced in this document.
+<P>
+<OL>
+<LI> D. E. Knuth, <EM>The TeXbook</EM>, Addison-Wesley, 1984
+</LI>
+<LI> Leslie Lamport, LaTeX <EM>A Document Preparation System</EM>,
+Addison-Wesley, 1986
+</LI>
+<LI> Joachim Schrod, <EM>An International Version of MakeIndex</EM>,
+Cahiers GUTenberg, 10, p81-90, 1991
+</LI>
+<LI> Pehong Chen and Michael A. Harrison, <EM>Automating Index
+Preparation</EM>, TR-87/347, University of California Berkeley, 1987
+<A NAME="makeindex"></A>
+</LI>
+<LI> Roger Kehr, <SF>xindy</SF>, <EM>Ein Flexibles Indexierungssystem</EM>,
+Studienarbeit FB Informatik, TH-Darmstadt, November 1995.</LI>
+</OL>
+<P>
+<HR>
+Next
+<A HREF="style-tutorial-3.html">Previous</A>
+<A HREF="style-tutorial.html#toc4">Contents</A>
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial.html b/Master/texmf-dist/doc/xindy/style-tutorial.html
new file mode 100644
index 00000000000..6c815ca30d6
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial.html
@@ -0,0 +1,66 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+ <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
+ <TITLE>XINDY Style File Tutorial</TITLE>
+ <LINK HREF="style-tutorial-1.html" REL=next>
+
+
+</HEAD>
+<BODY>
+<A HREF="style-tutorial-1.html">Next</A>
+Previous
+Contents
+<HR>
+<H1>XINDY Style File Tutorial</H1>
+
+<H2><SF>A Flexible Indexing System</SF></H2>
+<H2>Roger Kehr</H2>
+<H3>Computer Science Department, Technical University of Darmstadt</H3>
+ and
+<H2>Joachim Schrod</H2>
+<H3>Joachim Schrod Net &amp; Publication Consultance GmbH</H3>
+Tutorial, Edition March 1997 for xindy version 1.1
+<P><HR>
+<EM> This is a tutorial on writing style files for
+the <SF>xindy</SF> indexing system
+[5]. <SF>xindy</SF> is a general purpose index processor that
+can be configured for a variety of document preparation systems. We
+will demonstrate step by step the incremental specification of a
+complete index style. The examples are based on indexes that are
+delivered with the system so one can get acquainted with it
+practically.
+<p>
+<B>Caution:</B> This tutorial does not describe the complete style file
+language. In particular, description of rule sets, the multi-run
+approach, and standard modules are missing.</EM>
+<HR>
+<P>
+<H2><A NAME="toc1">1.</A> <A HREF="style-tutorial-1.html">About <SF>xindy</SF></A></H2>
+
+<P>
+<H2><A NAME="toc2">2.</A> <A HREF="style-tutorial-2.html">A Basic Introduction</A></H2>
+
+<UL>
+<LI><A HREF="style-tutorial-2.html#ss2.1">2.1 Running <SF>xindy</SF></A>
+<LI><A HREF="style-tutorial-2.html#ss2.2">2.2 Adding some Markup</A>
+<LI><A HREF="style-tutorial-2.html#ss2.3">2.3 Keyword Mappings</A>
+<LI><A HREF="style-tutorial-2.html#ss2.4">2.4 Letter Groups</A>
+</UL>
+<P>
+<H2><A NAME="toc3">3.</A> <A HREF="style-tutorial-3.html">Advanced Features</A></H2>
+
+<UL>
+<LI><A HREF="style-tutorial-3.html#ss3.1">3.1 Location Classes</A>
+<LI><A HREF="style-tutorial-3.html#ss3.2">3.2 Hierarchical Location Classes</A>
+<LI><A HREF="style-tutorial-3.html#ss3.3">3.3 More about Letter Groups</A>
+</UL>
+<P>
+<H2><A NAME="toc4">4.</A> <A HREF="style-tutorial-4.html">References</A></H2>
+
+<HR>
+<A HREF="style-tutorial-1.html">Next</A>
+Previous
+Contents
+</BODY>
+</HTML>
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw
new file mode 100644
index 00000000000..1f4585950a9
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw
@@ -0,0 +1,20 @@
+;; Example raw-index file.
+
+(indexentry :key ("sábado") :locref "5" :attr "definition")
+(indexentry :key ("sabão") :locref "6" :attr "definition")
+(indexentry :key ("saber") :locref "7" :attr "definition")
+(indexentry :key ("sabor") :locref "8" :attr "definition")
+
+(indexentry :key ("academia") :locref "1" :attr "definition")
+(indexentry :key ("acafetado") :locref "2" :attr "definition")
+(indexentry :key ("açafrão") :locref "3" :attr "definition")
+(indexentry :key ("acalmar") :locref "4" :attr "definition")
+
+(indexentry :key ("index" "flat") :locref "1" :attr "usage")
+(indexentry :key ("index" "hierarchical") :locref "2" :attr "usage")
+(indexentry :key ("index" "very" "hierarchical") :locref "3" :attr "usage")
+(indexentry :key ("index" "very" "impressive") :locref "4" :attr "usage")
+
+;(indexentry :key ("arts" "classic") :locref "10" :attr "usage")
+;(indexentry :key ("arts" "contemporary") :locref "11" :attr "usage")
+;(indexentry :key ("arts" "modern") :locref "12" :attr "usage")
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex
new file mode 100644
index 00000000000..839c0b9834c
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex
@@ -0,0 +1,16 @@
+%%
+%% An sample file for typesetting an index.
+%%
+
+\documentclass[12pt]{article}
+
+\usepackage[latin1]{inputenc}
+\usepackage{makeidx}
+
+\makeindex
+
+\begin{document}
+
+\printindex
+
+\end{document}
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw
new file mode 100644
index 00000000000..88b767aa60f
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw
@@ -0,0 +1,35 @@
+;; Example raw-index file.
+
+(indexentry :key ("appendices") :locref "A-1" :attr "usage")
+(indexentry :key ("appendices") :locref "A-7" :attr "usage")
+(indexentry :key ("appendices") :locref "A-11" :attr "usage")
+(indexentry :key ("appendices") :locref "B-3" :attr "usage")
+(indexentry :key ("appendices") :locref "B-4" :attr "usage")
+(indexentry :key ("appendices") :locref "B-5" :attr "usage")
+(indexentry :key ("appendices") :locref "C-8" :attr "usage")
+(indexentry :key ("appendices") :locref "C-12" :attr "usage")
+(indexentry :key ("appendices") :locref "C-13" :attr "usage")
+(indexentry :key ("appendices") :locref "C-22" :attr "usage")
+(indexentry :key ("appendices") :locref "C-1" :attr "usage")
+(indexentry :key ("appendices") :locref "D-2" :attr "usage")
+(indexentry :key ("appendices") :locref "D-3" :attr "usage")
+(indexentry :key ("appendices") :locref "D-5" :attr "usage")
+(indexentry :key ("appendices") :locref "D-10" :attr "usage")
+
+(indexentry :key ("roman") :locref "iv" :attr "usage")
+(indexentry :key ("roman") :locref "ii" :attr "usage")
+(indexentry :key ("roman") :locref "iii" :attr "usage")
+(indexentry :key ("roman") :locref "ix" :attr "usage")
+(indexentry :key ("roman") :locref "x" :attr "usage")
+(indexentry :key ("roman") :locref "mcmxcvi" :attr "usage")
+
+(indexentry :key ("lyuk") :locref "1" :attr "usage")
+(indexentry :key ("lyukas") :locref "2" :attr "usage")
+(indexentry :key ("maga") :locref "1" :attr "usage")
+(indexentry :key ("magyar") :locref "2" :attr "usage")
+(indexentry :key ("nagy") :locref "1" :attr "usage")
+(indexentry :key ("nagyon") :locref "9" :attr "usage")
+(indexentry :key ("negy") :locref "4" :attr "usage")
+(indexentry :key ("nyolc") :locref "8" :attr "usage")
+(indexentry :key ("nyelv") :locref "1" :attr "usage")
+
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex
new file mode 100644
index 00000000000..839c0b9834c
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex
@@ -0,0 +1,16 @@
+%%
+%% An sample file for typesetting an index.
+%%
+
+\documentclass[12pt]{article}
+
+\usepackage[latin1]{inputenc}
+\usepackage{makeidx}
+
+\makeindex
+
+\begin{document}
+
+\printindex
+
+\end{document}
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/index.tex b/Master/texmf-dist/doc/xindy/style-tutorial/index.tex
new file mode 100644
index 00000000000..839c0b9834c
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/index.tex
@@ -0,0 +1,16 @@
+%%
+%% An sample file for typesetting an index.
+%%
+
+\documentclass[12pt]{article}
+
+\usepackage[latin1]{inputenc}
+\usepackage{makeidx}
+
+\makeindex
+
+\begin{document}
+
+\printindex
+
+\end{document}
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy b/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy
new file mode 100644
index 00000000000..ee809f9aae8
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy
@@ -0,0 +1,55 @@
+;; This is a first example using `xindy'.
+
+(mapc #'(lambda (x)
+ (pushnew x *features*))
+ '(:STEP1 :STEP2 :STEP3 :STEP4 :STEP5))
+
+#+:STEP1
+(progn
+ (define-location-class "page-numbers" ("arabic-numbers"))
+ (define-attributes (("definition" "usage")))
+ )
+
+
+#+:STEP2
+(progn
+ (markup-index :open "~n\begin{theindex}~n"
+ :close "~n~n\end{theindex}~n"
+ :tree)
+
+ (markup-locref :class "page-numbers" :attr "definition"
+ :open "{\bf " :close "}")
+
+ (markup-locref-list :sep ", ")
+ (markup-locclass-list :open "\quad{}")
+ )
+
+#+:STEP3
+(progn
+ (markup-indexentry :open "~n \item " :depth 0)
+ (markup-indexentry :open "~n \subitem " :depth 1)
+ (markup-indexentry :open "~n \subsubitem " :depth 2)
+
+ (markup-range :class "page-numbers" :sep "--")
+ )
+
+#+:STEP4
+(progn
+ (sort-rule "à" "a")
+ (sort-rule "á" "a")
+ (sort-rule "ã" "a")
+ (sort-rule "è" "e")
+ (sort-rule "é" "e")
+ (sort-rule "ç" "c")
+
+ (sort-rule "\\texttt{\(.*\)}" "\1" :again :bregexp)
+ )
+
+#+:STEP5
+(progn
+ (define-letter-groups
+ ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m"
+ "n" "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z"))
+
+ (markup-letter-group-list :sep "~n~n \indexspace~n")
+ )
diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy b/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy
new file mode 100644
index 00000000000..e45e2f24482
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy
@@ -0,0 +1,80 @@
+;; This is another example using `xindy'.
+
+(mapc #'(lambda (x)
+ (pushnew x *features*))
+ '(:STEP1 :STEP2 :STEP3 :STEP4 :STEP5 :STEP6 :STEP7 :STEP8 :STEP9 :STEP10))
+
+#+:STEP1
+(progn
+ (define-location-class "page-numbers" ("arabic-numbers"))
+ (define-attributes (("definition" "usage")))
+ )
+
+
+#+:STEP2
+(progn
+ (markup-index :open "~n\begin{theindex}~n"
+ :close "~n~n\end{theindex}~n"
+ :tree)
+
+ (markup-locref :class "page-numbers" :attr "definition"
+ :open "{\bf " :close "}")
+
+ (markup-locref-list :sep ", ")
+ (markup-locclass-list :open "\quad{}")
+ )
+
+#+:STEP3
+(progn
+ (markup-indexentry :open "~n \item " :depth 0)
+ (markup-indexentry :open "~n \subitem " :depth 1)
+ (markup-indexentry :open "~n \subsubitem " :depth 2)
+ )
+
+#+:STEP4
+(progn
+ (sort-rule "à" "a")
+ (sort-rule "á" "a")
+ (sort-rule "ã" "a")
+ (sort-rule "è" "e")
+ (sort-rule "é" "e")
+ (sort-rule "ç" "c")
+
+ (sort-rule "\\texttt{(.*)}" "\1" :again :bregexp)
+ )
+
+#+:STEP5
+(progn
+ (define-letter-groups
+ ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m"
+ "n" "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z"))
+
+ (markup-letter-group-list :sep "~n~n \indexspace~n")
+ )
+
+#+:STEP6
+(progn
+ (define-location-class "roman-pages" ("roman-numbers-lowercase"))
+ #-:STEP8
+ (define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers"))
+ )
+
+#+:STEP7
+(markup-range :sep "--")
+
+#+:STEP8
+(progn
+ (define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers")
+ :hierdepth 2)
+ (markup-locref-list :sep "; " :depth 0 :class "appendices")
+ (markup-locref-list :open "~~" :sep ", " :depth 1 :class "appendices")
+ )
+
+#+:STEP9
+(progn
+ (define-letter-group "ly" :after "l" :before "m")
+ (define-letter-group "ny" :after "n" :before "o")
+
+ (markup-letter-group :open-head "~n {\bf " :close-head "}"
+ :capitalize)
+ )
diff --git a/Master/texmf-dist/doc/xindy/tex2xindy.pdf b/Master/texmf-dist/doc/xindy/tex2xindy.pdf
new file mode 100644
index 00000000000..65b834d225d
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/tex2xindy.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/texindy.pdf b/Master/texmf-dist/doc/xindy/texindy.pdf
new file mode 100644
index 00000000000..0d460cc060f
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/texindy.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/xindy/xindy.pdf b/Master/texmf-dist/doc/xindy/xindy.pdf
new file mode 100644
index 00000000000..f861491dfb8
--- /dev/null
+++ b/Master/texmf-dist/doc/xindy/xindy.pdf
Binary files differ