reorganize xindy-2.4 build system (part 1)

git-svn-id: svn://tug.org/texlive/trunk@21706 c570f23f-e606-0410-a88d-b1316a301751
author: Peter Breitenlohner <peb@mppmu.mpg.de> 2011-03-13 13:16:44 +0000
committer: Peter Breitenlohner <peb@mppmu.mpg.de> 2011-03-13 13:16:44 +0000
commit: a002c295ae6054a4cfb9825ddb6e0d4f27ecde73 (patch)
tree: 1addafb42ef483a7ceb41abed3e9c877f808ee00 /Build/source/utils/xindy/xindy-2.4/doc/style-tutorial-2.html
parent: 908bf11dbd760fe92209f9c1fe90502a44fa90fc (diff)
1 files changed, 361 insertions, 0 deletions
diff --git a/Build/source/utils/xindy/xindy-2.4/doc/style-tutorial-2.html b/Build/source/utils/xindy/xindy-2.4/doc/style-tutorial-2.html
new file mode 100644
index 00000000000..b5313e59d72
--- /dev/null
+++ b/Build/source/utils/xindy/xindy-2.4/doc/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>
author	Peter Breitenlohner <peb@mppmu.mpg.de>	2011-03-13 13:16:44 +0000
committer	Peter Breitenlohner <peb@mppmu.mpg.de>	2011-03-13 13:16:44 +0000
commit	a002c295ae6054a4cfb9825ddb6e0d4f27ecde73 (patch)
tree	1addafb42ef483a7ceb41abed3e9c877f808ee00 /Build/source/utils/xindy/xindy-2.4/doc/style-tutorial-2.html
parent	908bf11dbd760fe92209f9c1fe90502a44fa90fc (diff)