diff options
Diffstat (limited to 'Master/texmf/doc/xindy/style-tutorial-2.html')
| -rw-r--r-- | Master/texmf/doc/xindy/style-tutorial-2.html | 361 |
1 files changed, 0 insertions, 361 deletions
diff --git a/Master/texmf/doc/xindy/style-tutorial-2.html b/Master/texmf/doc/xindy/style-tutorial-2.html deleted file mode 100644 index b5313e59d72..00000000000 --- a/Master/texmf/doc/xindy/style-tutorial-2.html +++ /dev/null @@ -1,361 +0,0 @@ -<!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 <distrib-dir>/doc/style-tutorial/*.raw . -eg$ cp <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> |