1 files changed, 263 insertions, 0 deletions
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>