diff options
| author | Karl Berry <karl@freefriends.org> | 2013-04-07 18:26:53 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2013-04-07 18:26:53 +0000 |
| commit | b04c2e1a42573e9735547702356c7b9a769a6855 (patch) | |
| tree | c0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/xindy | |
| parent | fb0bf13304a356f197bfc1add17f98c07e96f17b (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')
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 Binary files differnew file mode 100644 index 00000000000..c827d872e7d --- /dev/null +++ b/Master/texmf-dist/doc/xindy/alphabets-doc.pdf diff --git a/Master/texmf-dist/doc/xindy/dataflow.gif b/Master/texmf-dist/doc/xindy/dataflow.gif Binary files differnew file mode 100644 index 00000000000..203b5521ba6 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/dataflow.gif 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 +À, Á, ñ. Other languages from northern Europe +have letters like Ä, Ø, æ or ß 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 "ä" "ae") +</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 +À, Á, ñ. Other languages from northern Europe +have letters like Ä, Ø, æ or ß 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 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> +<INDEX:OPEN> + <LETTER-GROUP-LIST:OPEN> + <LETTER-GROUP:OPEN ["a"]> + <INDEXENTRY-LIST:OPEN [0]> + <INDEXENTRY:OPEN [0]> + <KEYWORD-LIST:OPEN [0]> + <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 & 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 Binary files differnew file mode 100644 index 00000000000..74f581c4b85 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/index.gif 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> +<tag/<tt/arabic-numbers// contains all non-negative numbers beginning +with zero: 0, 1, 2, .... + +<tag/<tt/roman-numerals-uppercase// the roman numerals I, II, III, +(IIII/IV), V, ... It recognizes the old and new roman numeral system. + +<tag/<tt/roman-numerals-lowercase// the same for the lowercase roman +numerals. + +<tag/<tt/ALPHA// the US-ASCII alphabet (uppercase letters). + +<tag/<tt/alpha// the US-ASCII alphabet (lowercase letters). + +<tag/<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 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 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 (<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> + <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>&</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]" "&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 ( <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 "<group0>" :close "</group0>" + :group 0) + + (markup-attribute-group :open "<group1>" :close "</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> > 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> + <OPEN> + IF (:open-head OR :close-head) + <OPEN-HEAD> + transformer-of(<GROUP-NAME>) + <CLOSE-HEAD> + FI + <INDEXENTRIES...> + <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 "<B>" :close "</B>" :attr "definition") + (markup-locref :open "<I>" :close "</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> + <OPEN> + Markup of location reference X + <SEP> + IF (not :ignore-end) + Markup of location reference Y + FI + <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><</CODE>' and for <CODE>:close</CODE> is +`<CODE>></CODE>'. The beginning of an example output could look like: +<P> +<PRE> + <INDEX:OPEN> + <LETTER-GROUP-LIST:OPEN> + <LETTER-GROUP:OPEN ["a"]> + <INDEXENTRY-LIST:OPEN [0]> + <INDEXENTRY:OPEN [0]> + <KEYWORD-LIST:OPEN [0]> + <KEYWORD:OPEN [0]> + ... +</PRE> +<P>We use a simple indentation scheme to make the structure of the tags +visible. The symbolic tag <CODE><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 & 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 Binary files differnew file mode 100644 index 00000000000..be58722f4d9 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/mappings.gif 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 À, +Á, ñ. Other languages from northern Europe have letters +like Ä, Ø, æ or ß 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 <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> 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 & 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 Binary files differnew file mode 100644 index 00000000000..65b834d225d --- /dev/null +++ b/Master/texmf-dist/doc/xindy/tex2xindy.pdf diff --git a/Master/texmf-dist/doc/xindy/texindy.pdf b/Master/texmf-dist/doc/xindy/texindy.pdf Binary files differnew file mode 100644 index 00000000000..0d460cc060f --- /dev/null +++ b/Master/texmf-dist/doc/xindy/texindy.pdf diff --git a/Master/texmf-dist/doc/xindy/xindy.pdf b/Master/texmf-dist/doc/xindy/xindy.pdf Binary files differnew file mode 100644 index 00000000000..f861491dfb8 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/xindy.pdf |
