From b04c2e1a42573e9735547702356c7b9a769a6855 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 7 Apr 2013 18:26:53 +0000 Subject: texmf -> texmf-dist: doc git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/xindy/NEWS | 25 + Master/texmf-dist/doc/xindy/README | 14 + Master/texmf-dist/doc/xindy/README.distrib-source | 127 +++ Master/texmf-dist/doc/xindy/alphabets-doc.pdf | Bin 0 -> 380525 bytes Master/texmf-dist/doc/xindy/dataflow.gif | Bin 0 -> 1988 bytes Master/texmf-dist/doc/xindy/faq-1.html | 169 +++ Master/texmf-dist/doc/xindy/faq-2.html | 95 ++ Master/texmf-dist/doc/xindy/faq-3.html | 83 ++ Master/texmf-dist/doc/xindy/faq-4.html | 668 +++++++++++ Master/texmf-dist/doc/xindy/faq.html | 90 ++ Master/texmf-dist/doc/xindy/index.gif | Bin 0 -> 9066 bytes Master/texmf-dist/doc/xindy/manual-1.html | 42 + Master/texmf-dist/doc/xindy/manual-2.html | 302 +++++ Master/texmf-dist/doc/xindy/manual-3.html | 1160 ++++++++++++++++++++ Master/texmf-dist/doc/xindy/manual-4.html | 230 ++++ Master/texmf-dist/doc/xindy/manual-5.html | 63 ++ Master/texmf-dist/doc/xindy/manual-6.html | 53 + Master/texmf-dist/doc/xindy/manual-7.html | 53 + Master/texmf-dist/doc/xindy/manual.html | 73 ++ Master/texmf-dist/doc/xindy/mappings.gif | Bin 0 -> 878 bytes Master/texmf-dist/doc/xindy/style-tutorial-1.html | 92 ++ Master/texmf-dist/doc/xindy/style-tutorial-2.html | 361 ++++++ Master/texmf-dist/doc/xindy/style-tutorial-3.html | 263 +++++ Master/texmf-dist/doc/xindy/style-tutorial-4.html | 41 + Master/texmf-dist/doc/xindy/style-tutorial.html | 66 ++ Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw | 20 + Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex | 16 + Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw | 35 + Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex | 16 + .../texmf-dist/doc/xindy/style-tutorial/index.tex | 16 + .../texmf-dist/doc/xindy/style-tutorial/style1.xdy | 55 + .../texmf-dist/doc/xindy/style-tutorial/style2.xdy | 80 ++ Master/texmf-dist/doc/xindy/tex2xindy.pdf | Bin 0 -> 4825 bytes Master/texmf-dist/doc/xindy/texindy.pdf | Bin 0 -> 12313 bytes Master/texmf-dist/doc/xindy/xindy.pdf | Bin 0 -> 11444 bytes 35 files changed, 4308 insertions(+) create mode 100644 Master/texmf-dist/doc/xindy/NEWS create mode 100644 Master/texmf-dist/doc/xindy/README create mode 100644 Master/texmf-dist/doc/xindy/README.distrib-source create mode 100644 Master/texmf-dist/doc/xindy/alphabets-doc.pdf create mode 100644 Master/texmf-dist/doc/xindy/dataflow.gif create mode 100644 Master/texmf-dist/doc/xindy/faq-1.html create mode 100644 Master/texmf-dist/doc/xindy/faq-2.html create mode 100644 Master/texmf-dist/doc/xindy/faq-3.html create mode 100644 Master/texmf-dist/doc/xindy/faq-4.html create mode 100644 Master/texmf-dist/doc/xindy/faq.html create mode 100644 Master/texmf-dist/doc/xindy/index.gif create mode 100644 Master/texmf-dist/doc/xindy/manual-1.html create mode 100644 Master/texmf-dist/doc/xindy/manual-2.html create mode 100644 Master/texmf-dist/doc/xindy/manual-3.html create mode 100644 Master/texmf-dist/doc/xindy/manual-4.html create mode 100644 Master/texmf-dist/doc/xindy/manual-5.html create mode 100644 Master/texmf-dist/doc/xindy/manual-6.html create mode 100644 Master/texmf-dist/doc/xindy/manual-7.html create mode 100644 Master/texmf-dist/doc/xindy/manual.html create mode 100644 Master/texmf-dist/doc/xindy/mappings.gif create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial-1.html create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial-2.html create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial-3.html create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial-4.html create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial.html create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/index.tex create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy create mode 100644 Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy create mode 100644 Master/texmf-dist/doc/xindy/tex2xindy.pdf create mode 100644 Master/texmf-dist/doc/xindy/texindy.pdf create mode 100644 Master/texmf-dist/doc/xindy/xindy.pdf (limited to 'Master/texmf-dist/doc/xindy') 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- will +be created. Usual steps follow: + + $ cd xindy- + $ ./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-/. + +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-/COPYRIGHT +for the specific statement. + +The xindy run-time environment contains a xindy-specific CLISP-plugin +named ordrules, which is released under GPL version 2 or later. + +The xindy kernel modules and base styles are released under GPL +version 2 or later. diff --git a/Master/texmf-dist/doc/xindy/alphabets-doc.pdf b/Master/texmf-dist/doc/xindy/alphabets-doc.pdf new file mode 100644 index 00000000000..c827d872e7d Binary files /dev/null and b/Master/texmf-dist/doc/xindy/alphabets-doc.pdf differ diff --git a/Master/texmf-dist/doc/xindy/dataflow.gif b/Master/texmf-dist/doc/xindy/dataflow.gif new file mode 100644 index 00000000000..203b5521ba6 Binary files /dev/null and b/Master/texmf-dist/doc/xindy/dataflow.gif differ diff --git a/Master/texmf-dist/doc/xindy/faq-1.html b/Master/texmf-dist/doc/xindy/faq-1.html new file mode 100644 index 00000000000..31fcfba7abd --- /dev/null +++ b/Master/texmf-dist/doc/xindy/faq-1.html @@ -0,0 +1,169 @@ + + + + + XINDY FAQ: General Questions + + + + + +Next +Previous +Contents +
+

1. General Questions

+ +

1.1 Why a completely new indexing tool? makeindex works fine! +

+ +

+

With the International MakeIndex project, Joachim Schrod and +Gabor Herr have shown that adding extensions to +makeindex 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: +

+

    +
  1. Roger Kehr, xindy -- A Flexible Indexing System, +Proceedings of the EuroTeX'98, St. Malo, France, March 1998 +
  2. +
  3. Roger Kehr, xindy -- A Flexible Indexing System, +Technical Report No. 11/1997, Computer Science Department, Darmstadt +University of Technology, 1997. Also accessible from the xindy +homepage. +
  4. +
  5. Roger Kehr, xindy Ein Flexibles Indexierungssystem, +Studienarbeit FB Informatik, TH-Darmstadt, November 1995. +
  6. +
  7. Joachim Schrod, An International Version of MakeIndex, +Cahiers GUTenberg, 10, p81-90, 1991 +
  8. +
  9. Joachim Schrod and Gabor Herr, MakeIndex Version 3.0, +Technical University of Darmstadt, 1991 +
  10. +
+

+

+

+

1.2 I'm an old makeindex wizard. What does xindy offer that makeindex doesn't? +

+ +

+

Here are the most important differences between xindy and +makeindex: +

+

+

+

+

Internationalization

xindy 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 xindy-system can be configured +to process these alphabets by defining sort and +merge-rules that allow expressing of language specific rules. +One example of such a rule would be +

+

+(sort-rule "ä" "ae")
+
+

defining that a word containing the umlaut-a will be sorted as if it +contained the letters ae 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. +

+

Location classes.

makeindex 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 location-classes. Thus, +xindy initally does not know any location-class by default and +must be instructed to accept certain location-classes. A typical +declaration might look like: +

+

+
+(define-location-class "page-numbers" ("arabic-numbers"))
+
+
+

This declares that page numbers consist of the enumeration of the +arabic numbers. The arabic numbers are referred to as alphabets. +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. +

+

The concept of attributes.

With makeindex 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 +

+

+
+\index{xindy|bold}
+
+
+

the encapsulator is bold 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 xindy in favour of a more powerful scheme called +attributes. 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. +

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 xindy which can't be specified in the document processor anymore. +In fact, the makeindex-like markup is only a small subset of +xindys features. +

+

Cross references.

Cross-references were implemented in +makeindex with the encapsulation mechanism, which only served for +markup purposes. This has been completely separated in xindy. +Here we distinguish cleanly between attributes and cross references. +This makes it possible to implement checked cross references, +i.e. cross-refernces that can be checked if they point to an existing +index entry instead of somewhere ``behind-the-moon''. +

+

Less command-line options.

xindy 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 makeindex 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. +

+

Raw index parser.

The parser built into makeindex has +completely been separated from the core xindy system. xindy +understands a well-defined specification language for the raw index +that is completely different from makeindex, but in our opinion +more maintainable than the makeindex format. This requires a +separate filter that transforms arbitrary indexes to the xindy +format. An example filter is the program tex2xindy that comes +with this distribution. +

+

+

Summed up, some of the implicit assumptions made by makeindex +have been replaced and now burdend to the user. The reason is that +many of makeindex's assumptions were no longer valid in +multi-language environments or documents with arbitrary location +structures. This also characterizes xindy 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. +

+

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY FAQ: xindy Usage + + + + + +Next +Previous +Contents +
+

2. xindy Usage

+ +

2.1 I don't want to write style files. How can I proceed? +

+ +

+

You can use the wrapper program makeindex4. It tries to do it's +very best to make xindy behave as makeindex does. But if you +ever need to use some of the features of xindy you should learn +how to write an index style. Its easy! +

+

+

+

2.2 How do I use makeindex4? +

+ +

+

Process your document as usual. Then run makeindex4 on the index +file. It produces an index that should equal the one you would get +with an ordinary makeindex run. As far as you are satisfied with +the default behaviour of makeindex, makeindex4 will produce +comparable results. +

Some of the command-line options of makeindex are accepted by +makeindex4, others aren't. This may change in future releases, +but we recommend using plain xindy after a phase of +investigation, since one cannot use all of its features with +makeindex4. You will be informed about unsupported command-line +arguments when running makeindex4. +

If you have written special style files for makeindex they will +no longer work with makeindex4. Go ahead and write a new style +file for xindy. +

+

+

+

2.3 How works makeindex4? +

+ +

+

This job is now done automatically by makeindex4. It calls +tex2xindy to transform the raw-index into the format suitable for +xindy. tex2xindy emits some information about the attributes +(aka. encapsulators in makeindex) and the usage of +cross-references into a file, which has the extension `.sta'. The +makeindex4 program, written in perl, 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. +

Another problem is the automatic detection of cross-references. As +noted above, makeindex handles cross-references with its +encapsulation mechanism, a scheme which has been dropped in xindy +and replaced by a more powerful mechanism. To implement a simple +plug-in mechanism we have extended the syntax of the tex2xindy +filter to identify encapsulators of the form +

+

+
+\indexentry{...|encap{...}}{...}
+
+
+

as a cross-reference, whereas encapsulators of the form +

+

+
+\indexentry{...|encap}{...}
+
+
+

are treated as ordinary attributes. This is standard practice +defining cross-references in makeindex. Thus, tex2xindy +distinguishes these two forms of encapsulators as opposed to +makeindex and our plug-in makeindex4 generates the +appropriate definitions of the cross-reference classes as well. +

+

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY FAQ: xindy and LaTeX + + + + + +Next +Previous +Contents +
+

3. xindy and LaTeX

+ +

3.1 What is tex2xindy? +

+ +

+

tex2xindy is a filter that parses `.idx' or similar files +and converts the \indexentry macros into a form readable by +xindy. +

The parser of makeindex can be configured to recognize different +quoting characters, etc. (see the man-page for makeindex, section +input style specifiers for further details). We have tried to +extract the parser from makeindex but due to several probems we +have finally rewritten the parser using lex. Scanners written +with lex are usually fixed to a specific character set used in +the regular expressions. Our parser, tex2xindy is therefore not +configurable. If one uses a different configuration of the +makeindex input style specifiers, one can change the source +(tex2xindy.l) 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 tex2xindy in a form that +is easily maintainable. The input specifiers are stored symbolically +in the source. The definiton section looks like this: +

+

+
+KEYWORD  \\indexentry
+ENCAP    \|
+ACTUAL   @
+ESCAPE   \\
+LEVEL    !
+QUOTE    \"
+ROPEN    \(
+RCLOSE   \)
+ARGOPEN  \{
+ARGCLOSE \}
+
+
+

These definitions are essentially the input style specifiers as can be +found in the man-page of makeindex. Changing this section +according to your needs and recompiling tex2xindy should be an +easy task. Maybe we will include more pre-defined parsers in future +releases if necessary. +

+

+

+

3.2 What LaTeX-package should I use in conjunction with xindy? +

+ +

+

We strongly recommend using the LaTeX2e-package index 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. +

Another option is to use the xindy.sty from Andreas Schlechte +that comes with the xindy distribution. Take a look at the +contrib directory that should contain a version. +

+

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY FAQ: Style Files + + + + +Next +Previous +Contents +
+

4. Style Files

+ +

4.1 Eventually, I decided to write my first index style. How can I start? +

+ +

+

Congratulations! You have made a good decision, indeed. +

For a first impression, how a style file can be written from scratch +reference the tutorial 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. +

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 makeindex-like index. You can find it in the subdirectory +markup/tex of the module library. Starting from this template +you can remove or add commands as necessary. +

Additionally, consult the library of predefined index style +modules 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. +

Maybe some of the examples coming with the test-suite are good +examples of how unusual index style files can be written. +

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. +

+

+

4.2 How to write my first index style? +

+ +

+

Copy the file tex/makeidx.xdy 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. +

+

+

+

4.3 How works the actual key feature of makeindex with xindy? +

+ +

+

The treatment of the actual key (usually denoted with @, the +at-sign) has changed with xindy. Specifying index entries with a +specific markup can be done in makeindex with the actual key. The +makeindex-3 system and xindy offer the merge- and +sort-rules to transform a key into different representations, +limiting the need to specify an actual key. For example they support a +style of writing +

+

+
+\index{\bf{VIP}}
+
+
+

which can be transformed with a rule like +

+

+
+(merge-rule "\bf{\(.*\)}" "\1" :again :bregexp)
+
+
+

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. +

The makeindex behaviour, that the two keywords +

+

+
+\index{VIP}
+\index{VIP@\bf{VIP}}
+
+
+

are seen as two distinct index entries, can be simulated using the +following definition: +

+

+
+(merge-rule "\bf{\(.*\)}" "\1~e" :again :bregexp)
+
+
+

This rule tells xindy to remove the boldface macro for merging +and sorting purposes but defines the replacement to include the +special character ~e, which is the last character in the +alphabet (ISO-Latin in our case). This makes xindy treat them as +different keywords and positions the boldface keyword right behind the +one without any markup. Thus we receive the following mapping: +

+

+
+Keyword:    Merged and sorted as:   Appears in the index as:
+VIP              VIP                     VIP
+\bf{VIP}         VIP~e                   \bf{VIP}
+
+
+

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 makeindex way of defining keywords. +

+

+

+

4.4 I want to process an index for my native language. What must I do? +

+ +

+

What makes makeindex 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. +

Two problems must be solved when processing indexes with a new +languages: +

+

    +
  1. The sort ordering of the indexed terms must be specified +in an appropriate manner. This problem can be solved using the +so-called keyword mappings. +
  2. +
  3. The letter groups that partition the indexed terms into +separate sections must be specified.
  4. +
+

The xindy system can be configured to process these alphabets by +defining sort and merge rules that allow expressing language +specific rules. +

The keyword mappings are as follows: The merge key is generated +from the main key with the so called merge mapping. The +merge mapping can be specified with the command merge-rule. The +sort key is derived from the merge key using the sort +mapping specified with the sort-rule command. The following +scheme shows this mapping process: +

+

+ + +
+

+

The index style commands accomplishing this task are +sort-rule and merge-rule. One example of such a rule would +be +

+

+
+(sort-rule "ä" "ae")
+
+
+

defining that a word containing the umlaut-a will be sorted as if it +contained the letters ae 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. +

An example of how an appropriate mapping for some of the Roman +languages could look like is: +

+

+
+(sort-rule "à" "a")
+(sort-rule "á" "a")
+(sort-rule "ã" "a")
+(sort-rule "è" "e")
+(sort-rule "é" "e")
+(sort-rule "ç" "c")
+
+
+

This makes the accented letters be sorted as their unaccented +counterparts, yielding the desired sort ordering. +

Sometimes it is necessary to specify keyword mappings that tell the +system to put something behind something else. For instance, we'd +like to map the character ö behind the letter o. No problem +if you use the special characters ~b and ~e which +are called the beginning and ending 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. +

+

+
+(sort-rule "ö" "o~e")
+
+
+

Now the ö is directly positioned after the o but before +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 +

+

+
+(merge-rule "[-$()]" "")
+
+
+

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. +

+

+

+

4.5 In my index the capitalized words appear after the lowercase words. Why? +

+ +

+

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 +

+

+
+(require "lang/latin/caseisrt.xdy")
+
+
+

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. +

+

+

+

4.6 In my index there are no letter groups, yet! +

+ +

+

Letter groups for latin based alphabets can be defined with the command +

+

+
+(require "lang/latin/letgroup.xdy")
+
+
+

If your language needs additional letter groups you can insert them +into the previously defined letter group with inserting definitions of +the following form: +

+

+
+(define-letter-group "ly" :after "l" :before "m")
+(define-letter-group "ny" :after "n" :before "o")
+
+
+

This adds two more letter groups to the latin alphabet. Group ly +is inserted between l and m, and ny is inserted between +n and o. This is how two additional letters of the Hungarian +alphabet can be inserted. +

+

+

+

4.7 How can I get rid of any formatting information in the keyword? +

+ +

+

Assume you have index entries containing arbitrary formatting +information. For example you write your index entries in TeX in the +following form: +

+

+
+\index{\bf{In boldface please}}
+
+
+

To avoid specifying for each index entry the print key separately as +can be done with the following command +

+

+
+\index{In boldface please@\bf{In boldface please}}
+
+
+

you can instead define a rule doing this task for you: +

+

+
+(merge-rule "\\bf *{(.*)}" "\1" :eregexp :again)
+
+
+

This extended regular expression matches all strings that are +surrounded by this formatting command and in the merge phase the +formatting command is simply stripped off. Thus, you don't need to +write an explicit print key anymore. +

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 +

+

+
+index
+{\tt index}
+
+
+

you must be warned that a rule like +

+

+
+(merge-rule "{\\tt *(.*)}" "\1" :eregexp :again)
+
+
+

is probably not correct. In this case the above strings are both +mapped into the string index 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 +

+

+
+(merge-rule "{\\tt *(.*)}" "\1~e" :eregexp :again)
+
+
+

With the additional meta character ~e the substitution of the +second key word is placed after the first one making them +different index entries. If the second keyword should appear first, +use ~b instead. +

+

+

+

+

4.8 In my index the word -foo appears before bar. What must I do? +

+ +

+

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. +

+

+
+  green
+     -eyed  12
+     card   15
+
+
+

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: +

+

+
+  (sort-rule "-" "")
+
+
+

This makes `-eyed' be sorted as `eyed' thus making it appear +after `card' as desired. +

+

+

+

+

4.9 I want to use letter ordering instead of word ordering in my index. +

+ +

+

According to the Chicago Manual of Style there exist two +different schemes of sorting word lists. In word ordering +a blank precedes any letter in the alphabet, whereas in letter +ordering it does not count at all. The following example borrowed +from the makeindex man-page illustrates the difference: +

+

+
+ Word Order:         Letter Order:
+  sea lion            seal
+  seal                sea lion
+
+
+

By default, xindy uses word ordering. To use letter ordering +include the appropriate module with the following command: +

+

+
+(require "ord/letorder.xdy")
+
+
+

It actually defines the following command: +

+

+
+(sort-rule " " "")
+
+
+

This simply removes all blanks from the keyword resulting in the +desired behaviour. +

+

+

+

+

4.10 My document does not have page numbers, but a different scheme. What must I do? +

+ +

+

The ability to deal with user-definable location structures is one of +the most important new features of xindy. Many documents have a +document structure that is not based on page numbers. Typical examples +are manuals or appendices that come with a +chapter/page-per-chapter 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 +location classes. +

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 xindy. +Addtionally, one can define more alphabets in the index style with a +command like +

+

+  (define-alphabet "weekdays"
+         ("mon" "tue" "wed" "thu" "fri" "sat" "sun"))
+
+

Based on alphabets one can now compose a location class as follows: +

+

+  (define-location-class "weekday-hours"
+         ("weekday" :sep ":" "arabic-numbers"))
+
+

This class description indicates that all location refernces matching +this template are viewed as correct instances of this class. Here +:sep makes the dot serving as a separation string separation +the alphabets from each other. Example instances of this class are: +

+

+mon:23, thu:45, sun:17
+
+

For more detailed information consult the description of the command +define-location-class in the reference manual. +

+

+

+

4.11 I don't want to have ranges in my index. What can I do? +

+ +

+

By default, xindy joins three successive location references into a +range. Ranges are used as an abbrevation for a long sequence of +location references. For exmaple the sequence +

+

+12, 13, 14, 15, 16
+
+

would be shorter represented as +

+

+12-16
+
+

If you don't want to have ranges, simply define your location class in +the form +

+

+  (define-location-class ... :min-range-length none)
+
+

The argument :min-range-length none avoids forming of ranges. +Arbitrary numbers instead of none define the minimum length of a +sequence of location references that are needed to form a range. +xindys default value is 2. +

+

+

+

4.12 I want to markup ranges of different length differently. How do I accomplish this? +

+ +

+

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 `X--Y'. +

Assume we want to do this for the location class pagenums we can +specify the markup as follows: +

+

+
+(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 "--")
+
+
+

The first command indicates that a range (X,Y) of length 1 should +be printed in the form Xf., a range of length 2 as Xff. and +all others in the form X--Y. The switch :ignore-end causes +the end of range location reference Y to be suppressed in the +resulting output. +

+

+

4.13 I need to suppress some of the markup tags. How can I do this? +

+ +

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 +

+

+
+\def\ignore#1{}
+
+
+

If you additionally define markup like this +

+

+
+(markup-index :open "\ignore{" :close "}")
+
+
+

you can throw away the complete index if you like, which would be a +real pity! +

+

+

+

4.14 Whats it all about those cross references? +

+ +

+

Cross references are references pointing to an item in the index +itself. Typical examples are: +

+

+foo-bar see baz +
+

With makeindex cross references could be specified with the +encapsulation mechanism. This has completely been removed in xindy +and we have made cross references real first-class objects. +

In xindy 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. +

@begin-comment +One very interesting feature is the ability to check the validity +of cross-references. +@end-comment +

tex2xindy recognises all index entries of the form +

+

+  \index{...|\macro{where}}
+
+

as cross references. Here macro stands for an arbitrary macro +name and where is interpreted as the target keyword of the cross +references. +

If you want to use these cross references with xindy; add the +following line to your style file. +

+

+  (define-crossref-class "macro")
+
+

Additionally, you can assign specific markup to cross references using +the markup-crossref-commands. +

+

+

+

4.15 The keyword mappings don't work as expected! +

+ +

+

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. +

When running xindy you can turn on this feature with the command +line option `-L'. 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 `-l' +a trace of the mappings is recorded in the log-file. A sample output +looks like the following: +

+

+
+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'.
+
+
+

This trace shows that initially two regular expression mappings have +been added to the rule set. The second section shows how the keyword +`\"A\"a' 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. +

+

+

+

4.16 I'm totally confused by the markup scheme! +

+ +

+

A very important feature is the ability to trace all markup tags +xindy emits in the markup phase. Simply use the command line +switch -t or insert the command +

+

+
+(markup-trace :on)
+
+
+

into the index style. This informs xindy to emit additional +pseudo markup that can be used to understand and debug the +markup phase. An example output might look like the following: +

+

+
+<INDEX:OPEN>
+  <LETTER-GROUP-LIST:OPEN>
+    <LETTER-GROUP:OPEN ["a"]>
+      <INDEXENTRY-LIST:OPEN [0]>
+        <INDEXENTRY:OPEN [0]>
+          <KEYWORD-LIST:OPEN [0]>
+            <KEYWORD:OPEN [0]>
+ ...
+
+
+

The symbolic tags directly lead one to the command that is responsible +for the definition of that markup tag. For example, the tag +LETTER-GROUP-LIST:OPEN indicates that the command +markup-letter-group-list 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. +

+

+

+

4.17 What editor should I use when writing xindy style files? +

+ +

+

Use Emacs or XEmacs. Turn on the Lisp-mode with +

+

+
+M-x lisp-mode
+
+
+

and you can properly indent commands using M-q. To enter this +mode automatically add the following lines to the end of the style +file: +

+

+
+^L
+;; Local Variables:
+;; mode: lisp
+;; End:
+
+
+

The ^L (Control-L) can be entered with C-q C-l. +

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY FAQ + + + + + +Next +Previous +Contents +
+

XINDY FAQ

+ +

Or: xindy by Topic

+

Roger Kehr

+

Computer Science Department, Technical University of Darmstadt

+ and +

Joachim Schrod

+

Joachim Schrod Net & Publication Consultance GmbH

+$Revision: 1.2 $, $Date: 2004/05/24 21:43:16 $, for xindy version 2.2 +


+ The xindy 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 xindy by Topic +manual. The most up-to-date version of this FAQ can be obtained from +the xindy homepage at +http://www.xindy.org/doc/faq.html. +

+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 make-rules 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. +


+

+

1. General Questions

+ + +

+

2. xindy Usage

+ + +

+

3. xindy and LaTeX

+ + +

+

4. Style Files

+ + +
+Next +Previous +Contents + + diff --git a/Master/texmf-dist/doc/xindy/index.gif b/Master/texmf-dist/doc/xindy/index.gif new file mode 100644 index 00000000000..74f581c4b85 Binary files /dev/null and b/Master/texmf-dist/doc/xindy/index.gif differ diff --git a/Master/texmf-dist/doc/xindy/manual-1.html b/Master/texmf-dist/doc/xindy/manual-1.html new file mode 100644 index 00000000000..40fc1db4349 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/manual-1.html @@ -0,0 +1,42 @@ + + + + + xindy Manual: About this Manual + + + + + +Next +Previous +Contents +
+

1. About this Manual

+ +

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). +

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. +

Invocation of xindy is not explained here. Please refer to the +manual pages of the commands xindy, texindy, +makeindex4, and to the 2nd edition of the LaTeX Companion. The +xindy Web Site has more documentation, too. +

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: How the Index Processor Works + + + + + +Next +Previous +Contents +
+

2. How the Index Processor Works

+ +

+

+

2.1 Data Flow +

+ +

Usually document preparation systems produce some form data that +describe the index entries and the locations they point to. +This data is called the raw index 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 index style. 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. +

+

+ + +
+

The xindy 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 xindy should not be a big hurdle. The user is +normally not involved in the correct format suitable for xindy +and some tools will make this work invisible to him. +

In contrast, the output of the xindy system is highly +configurable and can produce a variety of different markups. +Additionally, the way xindy 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 xindy +how it should produce an output according to his wishes or simply use +some of the predefined styles that come with the distribution. +

+

+

+

+

2.2 General Concepts and Terms +

+ +

In the following sections we introduce some terms that are necessary +to understand the way xindy works. +

The development of xindy started with the devlopment of a model +of a book-like 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 xindy. +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. +

+

+ + +
+

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. +

+

+

+

+

+

index

An index consists of a list of letter-groups. +

+

+

letter-group

The letter groups serve as containers for +indexentries. The letter groups are intended to group all +index entries sharing a common keyword 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. +

+

+  B
+    bread      25, 27
+    butter     26
+
+  M
+    marmalade  19
+    milk       21
+
+

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'. xindy can be advised +to define arbitrary letter groups with a particular markup for each of +them. See command define-letter-group for further details. +

+

+

indexentry

An index entry consists of three components: the +keyword and optionally the list of location-class-groups and +the sub-indexentries. An example: +

+

+  bread   25-30
+     brown   26
+     white   27
+
+

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. +

+

+

keyword

The keyword is the identifier of an index entry. It +consists of a list of strings being the key 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 +

+

+  bread         25-30
+  bread, brown     26
+  bread, white     27
+
+

we have keywords `bread', `bread, brown' and `bread, white'. +

A keyword is actually separated into four different keys. The +main-key is the key that is specified from the author who indexes +a document. The merge-key is derived from the main key with the +so-called merge mapping. This mapping is accomplished with a set +of rewrite rules. The sort-key is derived from the merge key with +another set of rewrite rules called the sort mapping. The +print-key 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. +

The following figure describes this: +

+

+ + +
+

+

The merge-key is necessary to define the equality of +index entry keys. See command merge-rule for further details about +defining the merge mapping. +

The sort-key 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 sort-rule for an +explanation how these mapping can be specified. +

The print-key is used for the final markup and contains the +string that appears in the generated markup. +

+

+

location-class-group

There exist two kinds of +location class groups namely location-reference-groups and +cross-reference-groups. +

+

location-reference-group

consists of a list of +attribute-groups. +

+

+

attribute-groups

Each location-reference-group consists of +a list of attribute-groups. Attribute groups are defined by a set +of attributes. 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. +

See command define-attribute-groups for further information about +the handling of attribute-groups. +

An attribute group consists of a list of location-references +and/or ranges. +

+

+

location-reference-class, location-reference, location

Each +index entry of an index references at least one location in the +document. A location 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 location-reference. The +location reference is always represented as a string (a sequence of +characters). Each location reference is associated a special tag +called attribute. The following examples may give you an idea how +location references could look like. +

+

+"25" represents a page number. +
+

+

+"Chapter-3" represents the third chapter of a document. +
+

+

+"A-I" represents the first page, written in uppercase roman +numerals of the appendix `A', separated by a hyphen. +
+

+

+"2.3.4" represents the sub-sub-section 2.3.4 of a document. +
+

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 +location-class. A location class is composed of alphabets +and separators. See command define-location-class for a +description how classes can be defined. +

+

+

alphabet, separator

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: +

+

+
+<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.
+
+
+

The user is free to define new alphabets as he wishes. See the +commands define-alphabet and define-enumeration for further +details. +

A complete location class can be defined by composing alphabets and +separators. The location class of the example "A-I" can be +defined as follows +

+

+  (define-location-class "appendix"
+                         (ALPHA "-" roman-numerals-uppercase))
+
+

This is a list that completely describes all possible instances of +this location class. Other valid members are A-II, B-VI, +etc. Location classes are defined with the command +define-location-class. +

xindy reads the incoming strings representing location references +and tries to match them against a previously defined location class. +There exist no predefined location classes. +

+

range

A range is a pair of location-references. 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 +define-location-class for further details. +

+

+

cross-reference-group

Container for all +cross-references of a particular cross-reference-class. +

+

+

cross-reference-class, cross-reference

A cross-reference is +an unstructured reference. Cross-reference-classes 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. +

+

+

attributes

Each location reference contains a so-called +attribute. 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 italics or boldface +indicating this difference. An attribute may now be used to express +this difference. Since xindy needs to know the possible +attributes before the index entries are read in, the command +define-attributes must be used to define a set of attributes and +how they interact. +

+

+

+

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: Command List + + + + + +Next +Previous +Contents +
+

3. Command List

+ +

Here is the complete list of xindy's commands that may be used in +the index style. The symbol name always refers to a string. We +separate the commands into the processing and +markup commands. The commands are listed in alphabetical order. +

The parenthesis `[' and `]' denote optional parts of the +syntax and `{' and `}' denote the grouping of elements. A +vertical bar indicates alternatives. However, the enclosing round +braces are part of the syntax and must be supplied. +

+

+

3.1 Processing Commands +

+ +

Here follows the list of processing commands. +

+ +

+
+(define-alphabet name string-list)
+
+
+

Defines name to be the alphabet consisting of all elements of the +string-list. Examples: +

+

+  (define-alphabet "example-alphabet" ("An" "Example" "Alphabet"))
+
+

defines an alphabet consisting of exactly three symbols. For the +successor relationship holds: succ("An")="Example" and +succ("Example")="Alphabet". The built-in alphabet digits is +defined as follows: +

+

+  (define-alphabet "digits"
+                   ("0" "1" "2" "3" "4" "5" "6" "7" "8" "9"))
+
+

+

+

+ +

+
+(define-attributes attribute-list)
+
+
+

Defines all attributes the raw index may contain. Parameter +attribute-list is a list of list of strings. The nesting level +must not be more than 2. So (..(..)..) is allowed, whereas +(..(..(..)..)..) is not. +

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 ("definition") and ( ("definition") ) are equivalent. +All elements forming a list are a so-called attribute group. The +members of a group are written to the output file before any member +of the following groups are written. +

Examples of valid attributes lists are: +

("definition" "usage") defines two attribute groups. The first +one contains all references with the attribute definition and the +second one all with the attribute usage. +

(("definition" "important") "usage") defines two attribute +groups. The first one contains all references with the attributes +definition or important and the second one all with the +attribute usage. In the attribute group ("definition" +"important") the attribute definition overrides important. +

+

+

+ +

+
+(define-crossref-class name [:unverified])
+
+
+

Defines name to be a class of cross references. We distinguish +two types of cross reference classes. Verified 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 :unverified can be used to suppress this +behaviour. +

+

+ + +

+
+(define-letter-group name [:before lgname] [:after lgname]
+                          [:prefixes list-of-prefixes])
+
+(define-letter-groups list-of-letter-groups)
+
+
+

This command defines a letter group with name name, which must be +a string value, grouping all index entries that have a sort key +beginning with the prefix name. The command +

+

+  (define-letter-group "a")
+
+

is equivalent to the command +

+

+  (define-letter-group "a" :prefixes ("a"))
+
+

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. +

Example: +

+

+  (define-letter-group "a")
+
+

defines a letter group containing all index entries beginning with the +string "a". +

+

+  (define-letter-group "c" :after "a")
+
+

defines a letter group containing all index entries beginning with the +string "c". The letter group appears behind the letter group "a" +

+

+  (define-letter-group "b" :after "a" :before "c")
+
+

inserts letter group "b" between letter group "a" and "c". This allows +incremental definition of letter groups by extending already defined +ones. +

The arguments :after and :before define a partial order on +the letter groups. xindy 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. +

The command define-letter-groups (with an `s' at the end) is +simply an abbreviation for a sequence of +define-letter-group definitions where the elements are ordered in +the ordering given by the list. Example: +

+

+  (define-letter-groups ("a" "b" "c")
+
+

equals the definitions +

+

+  (define-letter-group "a")
+  (define-letter-group "b" :after "a")
+  (define-letter-group "c" :after "b")
+
+

See also commands markup-letter-group-list and +markup-letter-group for further information. +

+

+

+ +

+
+(define-location-class name layer-list
+                       [:min-range-length num]
+                       [:hierdepth depth]
+                       [:var])
+
+
+

Defines name 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 :sep. If the keyword :min-range-length is +specified we define the minimum range length to be used when +building ranges. The argument num must be a positive integer +number or the keyword none in which case the building of ranges +is disallowed. If the switch :var is specified the declared class +is of type variable, i.e. it is a var-location-class. Since +building of ranges is currently only allowed for standard classes +:var and :min-range-length must not be used together. The +keyword argument :hierdepth can be used to declare that the +location references have to be tagged in a hierarchical form. Its +argument depth must be an integer number indicating the number of +layers the hierarchy does contain. See command +markup-locref-list for more information. Examples: +

+

+  (define-location-class "page-numbers" ("arabic-numbers")
+                         :minimum-range-length 3)
+
+

Defines the location class page-numbers consisting of one layer +which is the alphabet arabic-numbers. 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 0, 1, ... 2313, etc. +

+

+  (define-location-class "sections" :var
+     ("arabic-numbers" :sep "."
+      "arabic-numbers" :sep "."
+      "arabic-numbers"))
+
+

defines a variable location class. Valid instances are 1, +1.1, 1.2, 2, 2.4.5, but none of 2-3 (wrong +separator), 1.2.3.4 (more than 3 layers), 2.3.iv (roman +number instead of arabic one). +

+

+

+ +

+
+(define-location-class-order list)
+
+
+

Defines the order in which the location classes are written to the +output file. The parameter list is a list of names of +location classes. Examples: +

+

+  (define-location-class-order
+      ("page-numbers" "sections" "xrefs"))
+
+

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. +

+

+

+ +

+
+(define-rule-set name
+        [ :inherit-from ("rule-set" "rule-set-2") ]
+        :rules (<rule>...) )
+
+
+

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 sort-rule. +They do not add new functionality that is not already present with +sort-rule. +

A rule can be of the form: +

+

+  <rule> ::= ("pattern" "replacement"
+              [:string|:bregexp|:egegexp] [:again])
+
+

The following incomplete example defines a new rule set of name +isolatin1-tolower that inherits definitions from rule set +latin-tolower, overriding or adding the sort rules in the list of +:rules. +

+

+   (define-rule-set "isolatin1-tolower"
+
+     :inherit-from ("latin-tolower")
+
+     :rules (("À" "à" :string :again)
+             ("Á" "á" :string :again)
+             ("Â" "â" :string :again)
+             ("Ã" "ã" :string :again)
+             ("Ä" "ä" :string :again)
+             ("Å" "å" :string :again)
+             ("Æ" "æ" :string :again)
+          ...
+            )
+   ...)
+
+

Rule sets can be instantiated with the command use-rule-set. For +further descriptions on the sorting model refer to the command +sort-rule. +

+

+ +

+
+(define-sort-rule-orientations (orientations...))
+
+
+

Defines the order for the different sorting phases. The currently +implemented orientations are forward and backward. This +command must precede all sort-rule commands in an index style. It +defines the orientations and implicitly sets the maximum number of +sorting phases performed. +

For further descriptions on the sorting model refer to the command +sort-rule. +

+

+

+ +

+
+(merge-rule pattern replacement [:again]
+                                [:bregexp | :eregexp | :string])
+
+
+

Defines a keyword mapping rule that can be used to generate the +merge key from the main key 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. +

The parameter pattern 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 basic regular +expressions (BREs) or extended regular expressions (EREs). You +can use the switch :bregexp to force the interpretation of the +pattern as a BRE, or :eregexp to interpret it as an ERE. If you +want xindy to interpret the pattern literally, use the switch +:string. If none of these switches is selected, xindy 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. +

The parameter replacement must be +a string possibly containing the special characters & +(substitutes for the complete match) and \1,...,\9 +(substituting for the n-th submatch. Examples: +

+

+  (merge-rule "A" "a")
+
+ +replaces each occurrence of the uppercase letter `A' with its +lowercase counterpart. +

+

+  (merge-rule "\~"([AEOUaeou])" "\1")
+
+ +transforms the TeX umlaut-letters into their stripped counterparts, +such that `\"A' is treated as an `A' afterwards. +

The following sequences have a special meaning: +

`~n' : End of line symbol (linefeed). +

`~b' : The ISO-Latin character with the lowest ordinal number. +

`~e' : The ISO-Latin character with the highest ordinal number. +

`~~' : The tilde character. +

`~"' : The double quote character. +

Tilde characters and double quotes have to be quoted themselves with a +tilde character. The special characters `~b' and +`~e' 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. `m~e' is +lexicographically placed between `m' and `n'. +

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 +

+

+  (merge-rule "[A-Z]" "&x")
+
+

it is more efficient (though less comfortable) to use +

+

+  (merge-rule "A" "Ax")
+  (merge-rule "B" "Bx")
+  ...
+  (merge-rule "Z" "Zx")
+
+

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 `alpha' is checked before `.*', but +`auto' and `a.*' are checked in order of their definition. +

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. +

Sometimes it is necessary to apply rules anew to the result of a +transformation. By specifying the keyword argument :again in the +merge rule the rule is marked as mutable, which means that after +using this rule the transformation process shall restart at the same +place. E.g. the rule +

+

+  (merge-rule "\$(.*)\$" "\1" :again)
+
+

deletes all surrounding `$' symbols from the input. +

See also command sort-rule. +

+

+ +

+
+(merge-to attr-from attr-to [:drop])
+
+
+

A merge rule says that the attribute attr-from can be used +to build ranges in attr-to. Both attributes must name valid +attribute names. The switch :drop indicates, that the original +location reference with attribute attr-from has to be dropped +(removed), if a successful range was built with location references in +attribute attr-to. A detailed description is given in the section +about processing phases. +

+

+

+ +

+
+(require filename)
+
+
+

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 +filename 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: +

+

+  (require "french/alphabet.xdy")
+  (require "french/sort-rules.xdy")
+  (require "tex/locations.xdy")
+  (require "tex/markup.xdy")
+
+

Submodules can load other submodules as well. If a file is required +that was already loaded, the require command is simply ignored +and processing continues without including this file twice. See also +command searchpath. +

+

+

+ +

+
+(searchpath {path-string | path-list})
+
+
+

This command adds the given paths to the list of paths, xindy +searches for index style files. The argument path-string 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: +

+

+
+  (searchpath ".:/usr/local/lib/xindy:/usr/local/lib/xindy/english:")
+
+
+

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 +

+

+
+  (searchpath ("."
+               "/usr/local/lib/xindy"
+               "/usr/local/lib/xindy/english"
+               :default))
+
+
+

yields exactly the same result as the example above. Here +path-list must be a list of strings and/or the keyword(s) +:default and :last. The keyword :default signifies that +the default pathnames are to be inserted at the specified position in +the list. The keyword :last 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. +

+

+ +

+
+(sort-rule pattern replacement [:run level] [:again])
+
+
+

Defines a keyword mapping rule that can be used to generate the +sort key of an index entry from the merge key. This key is +used to sort the index entries lexicographically after they have been +merged using the merge key. +

The argument :run indicates that this rule is only in effect +a the specified level (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 +(new-sort-rules) that comes with this distribution. +

See command merge-rule for more information about keyword +rules. +

+

+

+ +

+
+(use-rule-set [:run phase]
+              [:rule-set ( <rule-set>... ))
+
+
+

This command instantiates the gives rule sets to be in effect at +sorting phase phase. The order of the rule sets given with +argument :rule-set 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. +

The following example declares that in phase 0 the rule sets +din5007 and isolatin1-tolower should be active, whereas in +phase 2 the other rule sets have to be applied. +

+

+  (use-rule-set :run 0
+                :rule-set ("din5007" "isolatin1-tolower"))
+
+  (use-rule-set :run 1
+                :rule-set ("resolve-umlauts"
+                           "resolve-sharp-s"
+                           "isolatin1-tolower"
+                           ))
+
+

For a discussion on rule sets refer to command define-rule-set. +

+

+

+

3.2 Markup Commands +

+ +

+

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 environments, +the syntax and naming scheme of all commands follows a simple +structure. +

The commands can be separated into environment and +list-environment commands. All commands of the first group +support the keyword arguments :open and :close, whereas the +second group additionally supports the keyword argument :sep. If +one of these keyword arguments is missing, the default markup tag is +always the empty tag. The :open tag is always printed before +the object itself and the :close tag is always printed after the +object has been printed. If a list is printed the :septag 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 `-list' as part of their command name. +

Since the number of commands and the heavy usage of default and +specialized tags makes the markup somehow complex (but very +powerful) we have added a mechanism to trace the markup tags +xindy omits during its markup phase with the command +markup-trace. +

Here follows the list of markup commands in alphabetical order with +some of the commands grouped together. +

+

+ + +

+
+(markup-attribute-group-list [:open string] [:close string]
+                             [:sep string])
+
+(markup-attribute-group      [:open string] [:close string]
+                             [:group group-num])
+
+
+

Location class groups consist of lists of attribute groups. The markup +of this list can be defined with the command +markup-attribute-group-list. +

To allow different markup for different attribute groups the command +markup-attribute-group can be specialized on the group number +with the keyword argument :group which must be an integer number. +E.g., given are the groups ("definition" "theorem") and +("default") with group numbers 0 and 1, then +

+

+  (markup-attribute-group :open "<group0>" :close "</group0>"
+                          :group 0)
+
+  (markup-attribute-group :open "<group1>" :close "</group1>"
+                          :group 1)
+
+

can be used to assign different markup for both groups in a SGML-based +language. +

+

+ + + +

+
+(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])
+
+
+

A crossref class group contains cross references of the same class. +The separator between the classes is defined with the +(markup-locclass-list :sep)-parameter. A list of cross references +can be tagged with the command markup-crossref-list that +specializes on the :class argument. +

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 markup-crossref-layer-list can be used. +

Each layer of a cross reference can be assigned two tags that +specialize on the class of the reference, like all other commands. +

A suitable markup for a cross reference class see within LaTeX2e +could look like that: +

+

+  (markup-crossref-list :class "see" :open "\emph{see} "
+                                     :sep  "; ")
+  (markup-crossref-layer-list :class "see" :sep ",")
+  (markup-crossref-layer :class "see"
+                                     :open "\textbf{" :close "}")
+
+

An example output could look like +

+

+... see house; garden,winter; greenhouse +
+

+

+ +

+
+(markup-index [:open string] [:close string]
+              [ :flat | :tree | :hierdepth depth ])
+
+
+

Defines the markup tags that enclose the whole index via the +:open and :close parameters. Examples: +

+

+  (markup-index :open  "Here comes the index~n"
+                :close "That's all folks!~n")
+
+

defines that the :open string is printed before the rest of the +index and the :close string appears after the index is printed. +

Additionally one can specify the form of the generated index. It is +possible to produce flat indexes by specifying the switch :flat, +to generate a tree with the :tree switch or any kind of mixture +between both by specifying the depth up to which trees shall be built +with the parameter :hierdepth. Its argument depth is the +number of layers that can be formed into a tree. Therefore :flat +is an abbrevation of :hierdepth 0 and :tree is an +abbrevation of :hierdepth max-depth, with max-depth being +the maximum number of layers a keyword has. An example: the keywords +

+

+  ("tree" "binary" "AVL")
+  ("tree" "binary" "natural")
+
+

can be transformed in the following ways: +

A flat index (:flat or :hierdepth 0) +

+

+  tree binary AVL
+  tree binary natural
+
+

with :hierdepth 1 +

+

+  tree
+     binary  AVL
+     binary  natural
+
+

and a tree (:tree or :hierdepth > 1) +

+

+  tree
+     binary
+        AVL
+        natural
+
+

Most often one will create tree-like indexes or ones that are flat. +

+

+ + +

+
+(markup-indexentry-list [:open string] [:close string]
+                        [:sep string]  [:depth integer])
+
+(markup-indexentry      [:open string] [:close string]
+                        [:depth integer])
+
+
+

Letter groups consists of a list of index entries. The command +markup-indexentry-list defines the markup of these lists. The +markup can be specialized on the depth if the index is hierarchically +organized. The command +

+

+  (markup-indexentry-list :open  "\begin{IdxentList}"
+                          :close "\end{IdxentList}"
+                          :sep   "~n")
+
+

defines that the index entries of all layers are wrapped into the +given markup tags. If additionally +

+

+  (markup-indexentry-list :open  "\begin{IdxentListII}"
+                          :close "\end{IdxentListII}"
+                          :sep   "~n"
+                          :depth 2)
+
+

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. +

The command markup-indexentry 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 :depth 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. +

+

+  (markup-indexentry :open  "\begin{Indexentry}"
+                     :close "\end{Indexentry}")
+
+

defines that the index entries of all layers are wrapped into the +given markup tags. If additionally +

+

+  (markup-indexentry :open  "\begin{IndexentryII}"
+                     :close "\end{IndexentryII}"
+                     :depth 2)
+
+

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. +

+

+ + +

+
+(markup-keyword-list [:open string] [:close string]
+                     [:sep string] [:depth integer])
+
+(markup-keyword      [:open string] [:close string]
+                     [:depth integer])
+
+
+

+

The print key of an index entry consists of a list of strings. The +markup of this list can be defined with the command +markup-keyword-list. The keyword argument :depth may be +specified to define the markup of the list at a particular depth. +

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 +markup-keyword. Since we maybe need different markup for +different layers, the optional keyword argument can be used to +specialize this markup for some depth. +

+

+ + +

+
+(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])
+
+
+

The first command defines the markup of the letter group with name +group-name. 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 :open-head and :close-head is specified +additional markup is added as can be described as follows: +

+

+  <OPEN>
+     IF (:open-head OR :close-head)
+       <OPEN-HEAD>
+         transformer-of(<GROUP-NAME>)
+       <CLOSE-HEAD>
+     FI
+     <INDEXENTRIES...>
+  <CLOSE>
+
+

Here, transformer-of 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 +:upcase, :downcase and :capitalize which result in the +corresponding string conversions. If none of them is specified no +transformation is done at all. +

The command markup-letter-group defines the markup of the list of +letter groups. +

+

+ +

+
+(markup-locclass-list [:open string] [:close string]
+                      [:sep string])
+
+
+

Each index entry contains a list of location class groups. This markup +command can be used to define the markup of this list. +

+

+ +

+
+(markup-locref [:open string] [:close string]
+               [:class locref-class]
+               [:attr  attribute]
+               [:depth integer])
+
+
+

The markup tags of a location reference can be specialized on the +three arguments :class, :attr and additionally, if +sub-references are used, :depth. Most often one will only use a +tag depending on the attribute. For example, all location references +with the attribute definition should appear in a font series like +bold, emphasizing the importance of this location reference; those +with the attribute default 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. +

+

+  (markup-locref :open "<B>" :close "</B>" :attr "definition")
+  (markup-locref :open "<I>" :close "</I>" :attr "default")
+
+

+

+ +

+
+(markup-locref-class [:open string] [:close string]
+                     [:class locref-class])
+
+
+

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 :class. +

+

+ + +

+
+(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])
+
+
+

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). +

The first command allows to tag the elements of a layer list +differently. The first element of this list can is specialisable with +:layer 0, the next element with :layer 1, etc. See the next +example for an example. +

+

+ +

+
+(markup-locref-list [:open string] [:close string] [:sep string]
+                    [:depth integer] [:class locref-class])
+
+
+

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 :class, and on :depth +that specializes on the different subentry levels when using +location references with sub-references. +

Given is a list of location references that have the class description +

+

+  (define-location-class "Appendix"
+                         ("ALPHA" :sep "-" "arabic-numbers")
+                         :hierdepth 2)
+
+

This location class has instances like A-1, B-5, etc. The +keyword argument :hierdepth 2 informs xindy to markup these +location references in a hierarchical form. With the commands +

+

+  (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")
+
+

we obtain a markup sequence for some example data that could look like +

+

+  {\bf A} 1,2,5; {\bf B} 5,6,9; {\bf D} 1,5,8; ...
+
+

+

+

+ +

+
+(markup-range [:open string] [:close string] [:sep string]
+              [:class locref-class]
+              [:length num] [:ignore-end])
+
+
+

A range consists of two location references. Markup can be specified +with the :open and :close arguments and one separator given +by the argument :sep. +

Since both location references are tagged with markup defined by the +command markup-locref 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 :length can be used to define +different markup for different lengths. In conjunction with +:length 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 Xf. instead of X--Y. This can be accomplished +with the switch :ignore-end. +

The markup tags for a range (X,Y) can be described as follows: +

+

+  <OPEN>
+    Markup of location reference X
+  <SEP>
+    IF (not :ignore-end)
+       Markup of location reference Y
+    FI
+  <CLOSE>
+
+

+

The following tags can be used to define a range of page numbers +(given in a location class page-numbers) without considering the +open and close parameters: +

+

+  (markup-range :sep "-" :class "page-numbers")
+
+

Location ranges then appear separated by a hyphen in a form like this: +

+

+   ..., 5-8, 19-23, ...
+
+

+

+ +

+
+(markup-trace [:on] [:open string] [:close string])
+
+
+

This command can be used to activate the tracing of all +markup commands xindy executes. The switch :on activates the +trace. If :on is omitted, the command line flag -t 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 :open is `<' and for :close is +`>'. The beginning of an example output could look like: +

+

+  <INDEX:OPEN>
+    <LETTER-GROUP-LIST:OPEN>
+      <LETTER-GROUP:OPEN ["a"]>
+        <INDEXENTRY-LIST:OPEN [0]>
+          <INDEXENTRY:OPEN [0]>
+            <KEYWORD-LIST:OPEN [0]>
+              <KEYWORD:OPEN [0]>
+   ...
+
+

We use a simple indentation scheme to make the structure of the tags +visible. The symbolic tag <LETTER-GROUP:OPEN ["a"]> for example +indicates that the tag that can be specified with the command +

+

+  (markup-letter-group :open "XXX" :group "a" ... )
+
+

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 +

+

+  (markup-trace :open "%%" :close "~n")
+
+

or a definition in the TeX document like +

+

+  \def\ignore#1{}
+
+

combined with the command +

+

+  (markup-trace :open "\ignore{" :close "}")
+
+

+

+

+

3.3 Raw Index Interface +

+ +

+

This section can be skipped if the reader is not interested in +adapting xindy to a new document preparation system. +

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 xindy. We also could have +written an configurable parser performing this task, but usually a +tool written with some text processing tools such as perl, +sed or awk can achieve the same task as well. Therefore, +adapting xindy to a completely different system can mostly be +done by writing an appropriate raw index filter. +

The format of the raw index interface of xindy is defined as +follows: +

+ +

+
+(indexentry { :key string-list [:print string-list]
+            | :tkey list-of-layers }
+            [:attr string]
+            { :locref string  [:open-range | :close-range]
+            | :xref string-list } )
+
+
+

The pseudo variable string is a sequence of characters +surrounded by double quotes, e.g. +

+

+  "Hi, it's me"  "one"  "a string with two \"double quotes\""
+
+

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 string list is simply +a list of strings separated by whitespaces and surrounded by round +braces. An example of a string list is +

+

+  ("This" "is" "a" "list" "of" "strings")
+
+

So far about the syntax. The semantics of the different elements are +described here. +

+

+

+

+

:key

The argument string list defines the keyword of +the index entry. It must be a list of strings, since the keyword may +consist of different layers such as ("heap" "fibonacci"). +

+

:print

The optional print key defines the way the +keyword has to be printed in the markup phase. +

+

:tkey

Another possibility to define the keys of an +index entry is with the :tkey keyword argument. It can be used +instead of the :key and :print 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 +

+

+  :tkey (("This") ("is") ("a") ("bang" "BANG !!!"))
+
+

is equivalent to +

+

+  :key   ("This" "is" "a" "bang")
+  :print ("This" "is" "a" "BANG !!!")
+
+

+

+

:locref

The reference an index entry describes can be a +location reference or a cross reference. The switch +:locref describes a location reference. Its optional arguments +are :open-range and :close-range. The string that must +be supplied must somehow encode the location reference. It might look +like the string "25" representing the page number 25, or +"Appendix-I" representing the first appendix numbered in +uppercase roman numerals. +

+

:open-range,:close-range

These are switches that do not +take any arguments. They describe the beginning and ending of a +range, starting or ending from the location reference that is +given by the argument :locref. If they are supplied, the +location reference may have influence on the way ranges are build. +

+

:xref

These arguments choose the second alternative. The +argument string list of parameter :xref describes where the +index entry should point to. +

+

:attr

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 +default. +

+

+

Some examples: +

+

+  (indexentry :key ("airplane") :locref "25" :attr "default")
+
+

defines an index entry with the key `airplane' indexed on page '25'. +This index entry has the attribute default. +

+

+  (indexentry :key ("house") :xref ("building") :attr "see")
+
+

defines a cross reference with the key 'house' pointing to the term +'building'. This cross reference belongs to the cross reference class +see. +

+

+  (indexentry :key ("house") :xref ("building") :open-range)
+
+

is an invalid specification, since :open-range mustn't be used +together with cross references. +

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: Processing Phases + + + + + +Next +Previous +Contents +
+

4. Processing Phases

+ +

4.1 The Startup Phase +

+ +

After the system is started, xindy reads in the index style that +is passed as a command line argument. Each require 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. +

+

+

4.2 The Processing Phase +

+ +

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. +

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. +

+

    +
  1. All location references are separated according to the class +they belong to. These groups are called location class groups. +Possible groups are all defined location and crossref classes. See +the commands define-location-class and +define-crossref-class for a description how these classes can +be defined. + +The classes are sorted according to an order that can be defined with +the command define-location-class-order. +
  2. +
  3. The further processing of each location class group is +different for the location classes and the crossref classes. + +
      +
    • Cross references are sorted lexicographically based on +the ISO-Latin alphabet. + +
    • +
    • To illustrate the processing of location references we assume +the following list: + +
      + 13, 14, 15, 18, 12, 13, +14, 16, 14, 16 +
      + + +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 + +
      +
      +   (define-attribute-groups (("definition" "important")
      +                             ("default")))
      +
      +   (merge-to "definition" "default" :drop)
      +   
      +
      +
      + + +See commands define-attributes and merge-to for a +detailed description. + +The substitution rules are applied. This means that +location references 13 and 14 with attribute `important' +are substituted by the location references 13 and 14 +with attribute `definition'. Substitution means removing from the +list of location references. + +Substitution occurs because the definition of the attribute groups +implicitly defines "definition" substitutes +"important". + +The resulting list is now + +
      + 13, 14, 15, 18, 12, 16, 14, +16 +
      + + + The merge-to 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 parents, whereas the new ones are called +childs. The example rule results in the adding of all +refernces with attribute `definition' to the attribute `default' +which results in the list + +
      + 13, 14, 15, 18, 12, 16, (13), +14, (15), 16, (18) +
      + + +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 +:drop 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 +13 and 15 have to be removed from the list of +location references. This step would be omitted if the switch +:drop were not specified. After unsucessfully trying to build +more ranges and dropping the location references 13, 15 +and (18)--which was only meant to build ranges--we obtain the list + +
      +14, 18, 12, 16, 13--16 +
      + + +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 + +
      +(12, 14, 16, 18) (13--16) +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    • +
    + +
  4. +
+

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. +

+

+

+

4.3 The Markup Phase +

+ +

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. +

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: Index + + + + + +Next +Previous +Contents +
+

5. Index

+ +

+

List of Commands +

+define-attributes
+define-alphabet
+define-crossref-class
+define-letter-group
+define-letter-groups
+define-location-class
+define-location-class-order
+define-rule-set
+define-sort-rule-orientations
+indexentry
+markup-attribute-group
+markup-attribute-group-list
+markup-crossref-layer
+markup-crossref-layer-list
+markup-crossref-layer
+markup-index
+markup-indexentry
+markup-indexentry-list
+markup-keyword
+markup-keyword-list
+markup-letter-group
+markup-letter-group-list
+markup-locclass-list
+markup-locref
+markup-locref-class
+markup-locref-layer
+markup-locref-layer-list
+markup-locref-list
+markup-range
+markup-trace
+merge-rule
+merge-to
+require
+searchpath
+sort-rule
+use-rule-set

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: References + + + + +Next +Previous +Contents +
+

6. References

+ +

+

The following books and papers were referenced in this document. +

+

    +
  1. D. E. Knuth, The TeXbook, Addison-Wesley, 1984 +
  2. +
  3. Leslie Lamport, LaTeX A Document Preparation System, +Addison-Wesley, 1986 +
  4. +
  5. Joachim Schrod, An International Version of MakeIndex, +Cahiers GUTenberg, 10, p81-90, 1991 +
  6. +
  7. Pehong Chen and Michael A. Harrison, Automating Index +Preparation, TR-87/347, University of California Berkeley, 1987 + +
  8. +
  9. Roger Kehr, xindy, Ein Flexibles Indexierungssystem, +Studienarbeit FB Informatik, TH-Darmstadt, November 1995. +
  10. +
  11. Joachim Schrod and Gabor Herr, MakeIndex Version 3.0, +Technical University Darmstadt, 1991 +
  12. +
  13. Roger Kehr, xindy -- A Flexible Indexing System, +Technical Report No. 11/1997, Computer Science Department, Darmstadt +University of Technology, 1997. Also accessible from the xindy +homepage. +
  14. +
  15. Roger Kehr, xindy -- A Flexible Indexing System, +Proceedings of the EuroTeX'98, St. Malo, France, March 1998 +
  16. +
+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual: References + + + + +Next +Previous +Contents +
+

7. References

+ +

+

The following books and papers were referenced in this document. +

+

    +
  1. D. E. Knuth, The TeXbook, Addison-Wesley, 1984 +
  2. +
  3. Leslie Lamport, LaTeX A Document Preparation System, +Addison-Wesley, 1986 +
  4. +
  5. Joachim Schrod, An International Version of MakeIndex, +Cahiers GUTenberg, 10, p81-90, 1991 +
  6. +
  7. Pehong Chen and Michael A. Harrison, Automating Index +Preparation, TR-87/347, University of California Berkeley, 1987 + +
  8. +
  9. Roger Kehr, xindy, Ein Flexibles Indexierungssystem, +Studienarbeit FB Informatik, TH-Darmstadt, November 1995. +
  10. +
  11. Joachim Schrod and Gabor Herr, MakeIndex Version 3.0, +Technical University Darmstadt, 1991 +
  12. +
  13. Roger Kehr, xindy -- A Flexible Indexing System, +Technical Report No. 11/1997, Computer Science Department, Darmstadt +University of Technology, 1997. Also accessible from the xindy +homepage. +
  14. +
  15. Roger Kehr, xindy -- A Flexible Indexing System, +Proceedings of the EuroTeX'98, St. Malo, France, March 1998 +
  16. +
+

+


+Next +Previous +Contents + + 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 @@ + + + + + xindy Manual + + + + + +Next +Previous +Contents +
+

xindy Manual

+ +

Roger Kehr

+

Computer Science Department, Technical University of Darmstadt

+ and +

Joachim Schrod

+

Joachim Schrod Net & Publication Consultance GmbH

+$Revision: 1.19 $, $Date: 2004/05/24 21:43:16 $, +for xindy version 2.2 +


+This is the manual of the indexing system xindy. xindy +is a powerful and flexible framework for generating indexes for many +kinds of documents. This document describes the xindy processing +model, terminology, and language, but not invocation and standard modules. +The most up-to-date version can be obtained from the xindy Web Site at +http://www.xindy.org/. +
+

+Index of all xindy commands

+

+

+

+

1. About this Manual

+ +

+

2. How the Index Processor Works

+ + +

+

3. Command List

+ + +

+

4. Processing Phases

+ + +

+

5. Index

+ +

+

6. References

+ +
+Next +Previous +Contents + + diff --git a/Master/texmf-dist/doc/xindy/mappings.gif b/Master/texmf-dist/doc/xindy/mappings.gif new file mode 100644 index 00000000000..be58722f4d9 Binary files /dev/null and b/Master/texmf-dist/doc/xindy/mappings.gif differ diff --git a/Master/texmf-dist/doc/xindy/style-tutorial-1.html b/Master/texmf-dist/doc/xindy/style-tutorial-1.html new file mode 100644 index 00000000000..890b1ecd8b9 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial-1.html @@ -0,0 +1,92 @@ + + + + + XINDY Style File Tutorial: About xindy + + + + + +Next +Previous +Contents +
+

1. About xindy

+ +

xindy means flexible indexing system. 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. +

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 +index processors. +

In comparison to other index processors xindy has several +powerful features that make it an ideal framework for describing and +generating complex indexes. Its most interesting features are +

+

+

+

Internationality

xindy 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 xindy system can be configured to process +these alphabets by defining sort and merge rules that allow +expressing language specific rules. One example of such a rule would +be +

+

+
+(sort-rule "ä" "ae")
+
+
+

defining that a word containing the umlaut-a will be sorted as if it +contained the letters ae 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. +

+

User Definable Location Types

Locations are the entities an +index entry points to. Often used locations are page numbers, +section numbers, etc. xindy 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 1-13, 2-15, 2-20, etc. This type of locations +can often be found in computer manuals. A more complex structure is +represented by the locations Psalm 46, 1-8 and Genesis 1, +31. Even the structure of bible verses can be described allowing +xindy to correctly sort and process indexes for documents with a +completely different structure. +

+

Highly Configurable Markup

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 environments 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. +

+

+

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY Style File Tutorial: A Basic Introduction + + + + + +Next +Previous +Contents +
+

2. A Basic Introduction

+ +

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 xindy +produces. You need LaTeX and the ISO-Latin enhancements that come +with the inputenc package to run the following examples. Also the +xindy system must already be installed. +

+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 xindy's +style file language. +

+

2.1 Running xindy +

+ +

Create a new directory somewhere and copy some files from the +distribution directory doc/style-tutorial/ by typing +

+

+
+eg$ mkdir tutorial
+eg$ cd tutorial
+eg$ cp <distrib-dir>/doc/style-tutorial/*.raw .
+eg$ cp <distrib-dir>/doc/style-tutorial/*.tex .
+
+
+

with distrib-dir replaced by the actual location. Now create a +file style1.xdy with the following content: +

+

+
+;; This is a first example using `xindy'.
+
+(define-location-class "page-numbers" ("arabic-numbers"))
+(define-attributes (("definition" "usage")))
+
+
+

Now run xindy by typing +

+

+
+eg$ xindy -t ex1.xlg -M style1 -I xindy ex1.raw
+
+
+

You should see something like +

+

+
+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".
+
+
+

xindy has now successfully compiled the index ex1.raw using +your index style style1.xdy. The result is now stored in file +ex1.ind. You can view this file but currently it only contains an +unreadable mix of data. +

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 xindy that we +like to process page numbers. We do this by defining a new +location class named page-numbers. The page numbers consist +of arabic-numbers as we might expect but this is not necessarily +true---imagine your page numbers consisted of roman numerals instead. +When reading the raw index contained in file ex1.raw +xindy 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. +

The second command tells xindy 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 definition of a mathematical term from +its usage. Sometimes these are typeset using different font +shapes such as italic or font series such as boldface. Each +location has an associated attribute which, if it is unspecified, +defaults to the attribute default. 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. +

+

+

2.2 Adding some Markup +

+ +

Until now you haven't seen something exciting, so its time to specify +some markup. Add the following lines to our index style: +

+

+
+(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 ", ")
+
+
+

Now run xindy again and afterwards LaTeX: +

+

+
+eg$ xindy -t ex1.xlg -M style1 -I xindy ex1.raw
+eg$ latex ex1.tex
+
+
+

You can view ex1.dvi with your prefered viewer (maybe xdvi +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 xindy? When you +view the file ex1.ind which is the result xindy generates, +you'll recognize some of the markup tags you specified. The +following is an excerpt of this file: +

+

+
+\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}
+
+
+

First of all you'll see that the file starts with the string +\begin{theindex} and ends with \end{theindex}. +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 definition. +

The :open and :close keyword arguments each take a string as +argument. The first one is written to the file when opening an +enviroment, whereas the latter one closes 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 +page-numbers which own the attribute definition. Here we +have cleanly separated the structured markup from the visual one, +allowing an easy redefinition if we decide, for example, to markup the +definition-locations in italics instead of boldface. +

Some words on keyword arguments and switches. Keyword +arguments such as :open or :close 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, :tree in the command markup-index is +a switch and thus it does not take an argument. We will use this +terminology throughout the rest of this document. +

The third command caused xindy to insert a horizontal space +between the keyword and the locations (the TeX command +\quad{} simply inserts a specific horizontal space). The last +command caused xindy to separate all location references from +each other with a comma followed by a blank, independently of any +location class. +

As you already may have observed, the tilde sign (~) serves +as a quoting character. +

We continue specifying markup to get a printable result by adding more +markup: +

+

+
+(markup-indexentry :open "~n  \item "           :depth 0)
+(markup-indexentry :open "~n    \subitem "      :depth 1)
+(markup-indexentry :open "~n      \subsubitem " :depth 2)
+
+
+

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 :depth keyword argument. The layers +are numbered by their depth starting from zero. +

Now run xindy and TeX again and enjoy your first index. It's +easy, isn't it! The output ex1.ind looks like the following: +

+

+
+\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}
+
+
+

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 sábado should appear before the +word saber since á must be sorted as if it were simply an +a. 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. +

What to do? We can define for each of the words containing these +special characters an explicit print key. The print key describes +the printed representation of the keyword whereas the key or +main key 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 +xindy offers: keyword-mappings. +

+

2.3 Keyword Mappings +

+ +

What are keyword mappings for? A good question. I'll try to give some +answers. +

+

    +
  • Merging of differently written words. 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. +
  • +
  • Specifying the sort order. 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. +
  • +
+

A detailed elaboration of these ideas can be found in the paper An +International Version of MakeIndex by Joachim Schrod [3]. +It describes the ideas that led to modifications on one of the +ancestors of the xindy system: makeindex [4]. +

The keyword mappings are as follows. The merge key is generated +from the main key with the so called merge mapping. The +merge mapping can be specified with the command merge-rule. The +sort key is derived from the merge key using the sort +mapping specified with the sort-rule command. The following +scheme shows this mapping process: +

+

+ + +
+

+

We will use this command now to define a suitable sort mapping that +fits our needs: +

+

+
+(sort-rule "à" "a")
+(sort-rule "á" "a")
+(sort-rule "ã" "a")
+(sort-rule "è" "e")
+(sort-rule "é" "e")
+(sort-rule "ç" "c")
+
+
+

These rules define mappings from a keyword to a normalized +version. In the logfile ex1.xlg these transformations are logged so +that one can see how these mappings are performed. In this example we +do not need any merge-rule but we will see applications in +further examples. +

Running xindy and TeXing the result now places the indexentries +at the right positions. +

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 +-L, e.g., in our example we could have used +

+
+eg$ xindy -t ex1.xlg -M style1 -L portuguese -I xindy ex1.raw
+
+
+

If we use one of the available language modules, sort rules in +user-written xindy styles are ignored. +

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 letter groups. +

+

2.4 Letter Groups +

+ +

To group indexentries we must define what indexentries form a group. +The clustering is done by matching the keywords' prefixes (taken from +the sort key) with a user-defined table of prefixes and define +appropriate markup that separates the groups from each other. Here it +goes. +

+

+
+(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")
+
+
+

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 default. +

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. +

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY Style File Tutorial: Advanced Features + + + + + +Next +Previous +Contents +
+

3. Advanced Features

+ +

In the following sections you'll learn more about the features of +xindy. 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. +

+

+

3.1 Location Classes +

+ +

We continue using a more complex index. Copy the current style to a +new file (now style2.xdy) and run xindy on the raw index +ex2.raw by typing: +

+

+
+eg$ cp style1.xdy style2.xdy
+eg$ xindy -t ex2.xlg -M style2 -I xindy ex2.raw
+
+
+

You should see some error messages indicating that something is +unknown to xindy. What has happend? The messages should be +similar to the following snapshot: +

+

+
+ ...
+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)
+ ...
+
+
+

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. xindy 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. +

+

+
+(define-location-class "roman-pages" ("roman-numerals-lowercase"))
+(define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers"))
+(define-location-class-order ("roman-pages" "appendices"))
+
+
+

The first command tells xindy 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 +basetypes, the argument :sep 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 +xindy are: +

+

+
arabic-numbers

contains all non-negative numbers beginning +with zero: 0, 1, 2, .... +

+

roman-numerals-uppercase, roman-numerals-lowercase

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. +

+

ALPHA, alpha

The US-ASCII alphabet letters (uppercase +and lowercase letters). +

+

digits

the digits 0, 1, 2, 3, 4, 5, 6, 7, 8 and 9 in this +order. +

+

`Fine,', you'll say, `but what if my basetypes are completely +different?' You're right! But xindy offers you to define your own +alphabets. For example, you can define a new alphabet by writing +

+

+
+(define-alphabet "my-personal-alphabet" ("Hi" "ho" "here" "I" "go"))
+
+
+

This is a valid alphabet that consists of 5 letters. You can now +define a location class +

+

+
+(define-location-class "my-personal-class"
+    ("my-personal-alphabet" :sep "-" "arabic-numbers"))
+
+
+

to match all of the following locations: Hi-12, ho-2, here-709, +I-9, go-42. xindy will recognize them and be able to sort them +according to your specification which says that Hi comes before +all others and here 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: +

+

+
+(define-alphabet "bible-chapters"
+    ("Genesis" "Exodus" "Leviticus" "Numbers" "Deuteronomy"
+     ... ))
+(define-location-class "bible-verses"
+    ("bible-chapters" :sep " " "arabic-numbers" :sep "," "arabic-numbers"))
+
+
+

This description would match locations like Genesis 1,3, +Exodus 7,8, etc. +

Now run LaTeX on ex2.tex and view the results. It looks a +little bit strange since xindy has automatically built ranges of +successive locations. The first locations of the index entry roman +actually denote the range ii until iv. Ranges consist +of location references. To typeset them correctly you can specify +

+

+
+(markup-range :sep "--")
+
+
+

This indicates that location reference forming a range shall be +separated by a hyphen. Running xindy and LaTeX again gives a +better idea of how it should look like. Here is a part of the +generated output. +

+

+
+  ...
+ \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
+  ...
+
+
+

+

3.2 Hierarchical Location Classes +

+ +

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: +

+

+
+(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")
+
+
+

Note: Since the tilde character serves as our quoting character it +must be quoted itself in the above example. Run xindy and view +the output stored in ex2.ind. The output looks similar to the +following: +

+

+
+  ...
+ \item appendices\quad{}A~1, 7, 11; B~3--5; C~1, 8, 12, 13, 22;
+        D~2, 3, 5, 10
+  ...
+
+
+

You can see that the location references of this class have been +transformed into a hierarchical structure caused by the +:hierdepth 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 `,'. +

Maybe you get an impression why we named xindy a flexible +system. +

+

3.3 More about Letter Groups +

+ +

More problems arise when using languages with different letter +schemes. Hungarian is an example. In Hungarian indexes the words +beginning with the letters Cs, Ly, Ny and more are printed in a +separate block. The words beginning with Ly, for example, appear +behind the words beginning with an L. xindy allows to define +this kind of letter groups as well. Add the following lines to the +style file. +

+

+
+(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)
+
+
+

The result looks like the following: +

+

+

+
+ ...
+ {\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
+  ...
+
+
+

The result describes what the purpose of the above commands is. It +becomes prettier from step to step, doesn't it? +

You have now learned most of the features of xindy. 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. +

+

+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY Style File Tutorial: References + + + + +Next +Previous +Contents +
+

4. References

+ +

+

The following books and papers were referenced in this document. +

+

    +
  1. D. E. Knuth, The TeXbook, Addison-Wesley, 1984 +
  2. +
  3. Leslie Lamport, LaTeX A Document Preparation System, +Addison-Wesley, 1986 +
  4. +
  5. Joachim Schrod, An International Version of MakeIndex, +Cahiers GUTenberg, 10, p81-90, 1991 +
  6. +
  7. Pehong Chen and Michael A. Harrison, Automating Index +Preparation, TR-87/347, University of California Berkeley, 1987 + +
  8. +
  9. Roger Kehr, xindy, Ein Flexibles Indexierungssystem, +Studienarbeit FB Informatik, TH-Darmstadt, November 1995.
  10. +
+

+


+Next +Previous +Contents + + 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 @@ + + + + + XINDY Style File Tutorial + + + + + +Next +Previous +Contents +
+

XINDY Style File Tutorial

+ +

A Flexible Indexing System

+

Roger Kehr

+

Computer Science Department, Technical University of Darmstadt

+ and +

Joachim Schrod

+

Joachim Schrod Net & Publication Consultance GmbH

+Tutorial, Edition March 1997 for xindy version 1.1 +


+ This is a tutorial on writing style files for +the xindy indexing system +[5]. xindy 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. +

+Caution: 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. +


+

+

1. About xindy

+ +

+

2. A Basic Introduction

+ + +

+

3. Advanced Features

+ + +

+

4. References

+ +
+Next +Previous +Contents + + diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw new file mode 100644 index 00000000000..1f4585950a9 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.raw @@ -0,0 +1,20 @@ +;; Example raw-index file. + +(indexentry :key ("sábado") :locref "5" :attr "definition") +(indexentry :key ("sabão") :locref "6" :attr "definition") +(indexentry :key ("saber") :locref "7" :attr "definition") +(indexentry :key ("sabor") :locref "8" :attr "definition") + +(indexentry :key ("academia") :locref "1" :attr "definition") +(indexentry :key ("acafetado") :locref "2" :attr "definition") +(indexentry :key ("açafrão") :locref "3" :attr "definition") +(indexentry :key ("acalmar") :locref "4" :attr "definition") + +(indexentry :key ("index" "flat") :locref "1" :attr "usage") +(indexentry :key ("index" "hierarchical") :locref "2" :attr "usage") +(indexentry :key ("index" "very" "hierarchical") :locref "3" :attr "usage") +(indexentry :key ("index" "very" "impressive") :locref "4" :attr "usage") + +;(indexentry :key ("arts" "classic") :locref "10" :attr "usage") +;(indexentry :key ("arts" "contemporary") :locref "11" :attr "usage") +;(indexentry :key ("arts" "modern") :locref "12" :attr "usage") diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex new file mode 100644 index 00000000000..839c0b9834c --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex1.tex @@ -0,0 +1,16 @@ +%% +%% An sample file for typesetting an index. +%% + +\documentclass[12pt]{article} + +\usepackage[latin1]{inputenc} +\usepackage{makeidx} + +\makeindex + +\begin{document} + +\printindex + +\end{document} diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw new file mode 100644 index 00000000000..88b767aa60f --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.raw @@ -0,0 +1,35 @@ +;; Example raw-index file. + +(indexentry :key ("appendices") :locref "A-1" :attr "usage") +(indexentry :key ("appendices") :locref "A-7" :attr "usage") +(indexentry :key ("appendices") :locref "A-11" :attr "usage") +(indexentry :key ("appendices") :locref "B-3" :attr "usage") +(indexentry :key ("appendices") :locref "B-4" :attr "usage") +(indexentry :key ("appendices") :locref "B-5" :attr "usage") +(indexentry :key ("appendices") :locref "C-8" :attr "usage") +(indexentry :key ("appendices") :locref "C-12" :attr "usage") +(indexentry :key ("appendices") :locref "C-13" :attr "usage") +(indexentry :key ("appendices") :locref "C-22" :attr "usage") +(indexentry :key ("appendices") :locref "C-1" :attr "usage") +(indexentry :key ("appendices") :locref "D-2" :attr "usage") +(indexentry :key ("appendices") :locref "D-3" :attr "usage") +(indexentry :key ("appendices") :locref "D-5" :attr "usage") +(indexentry :key ("appendices") :locref "D-10" :attr "usage") + +(indexentry :key ("roman") :locref "iv" :attr "usage") +(indexentry :key ("roman") :locref "ii" :attr "usage") +(indexentry :key ("roman") :locref "iii" :attr "usage") +(indexentry :key ("roman") :locref "ix" :attr "usage") +(indexentry :key ("roman") :locref "x" :attr "usage") +(indexentry :key ("roman") :locref "mcmxcvi" :attr "usage") + +(indexentry :key ("lyuk") :locref "1" :attr "usage") +(indexentry :key ("lyukas") :locref "2" :attr "usage") +(indexentry :key ("maga") :locref "1" :attr "usage") +(indexentry :key ("magyar") :locref "2" :attr "usage") +(indexentry :key ("nagy") :locref "1" :attr "usage") +(indexentry :key ("nagyon") :locref "9" :attr "usage") +(indexentry :key ("negy") :locref "4" :attr "usage") +(indexentry :key ("nyolc") :locref "8" :attr "usage") +(indexentry :key ("nyelv") :locref "1" :attr "usage") + diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex new file mode 100644 index 00000000000..839c0b9834c --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/ex2.tex @@ -0,0 +1,16 @@ +%% +%% An sample file for typesetting an index. +%% + +\documentclass[12pt]{article} + +\usepackage[latin1]{inputenc} +\usepackage{makeidx} + +\makeindex + +\begin{document} + +\printindex + +\end{document} diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/index.tex b/Master/texmf-dist/doc/xindy/style-tutorial/index.tex new file mode 100644 index 00000000000..839c0b9834c --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/index.tex @@ -0,0 +1,16 @@ +%% +%% An sample file for typesetting an index. +%% + +\documentclass[12pt]{article} + +\usepackage[latin1]{inputenc} +\usepackage{makeidx} + +\makeindex + +\begin{document} + +\printindex + +\end{document} diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy b/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy new file mode 100644 index 00000000000..ee809f9aae8 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/style1.xdy @@ -0,0 +1,55 @@ +;; This is a first example using `xindy'. + +(mapc #'(lambda (x) + (pushnew x *features*)) + '(:STEP1 :STEP2 :STEP3 :STEP4 :STEP5)) + +#+:STEP1 +(progn + (define-location-class "page-numbers" ("arabic-numbers")) + (define-attributes (("definition" "usage"))) + ) + + +#+:STEP2 +(progn + (markup-index :open "~n\begin{theindex}~n" + :close "~n~n\end{theindex}~n" + :tree) + + (markup-locref :class "page-numbers" :attr "definition" + :open "{\bf " :close "}") + + (markup-locref-list :sep ", ") + (markup-locclass-list :open "\quad{}") + ) + +#+:STEP3 +(progn + (markup-indexentry :open "~n \item " :depth 0) + (markup-indexentry :open "~n \subitem " :depth 1) + (markup-indexentry :open "~n \subsubitem " :depth 2) + + (markup-range :class "page-numbers" :sep "--") + ) + +#+:STEP4 +(progn + (sort-rule "à" "a") + (sort-rule "á" "a") + (sort-rule "ã" "a") + (sort-rule "è" "e") + (sort-rule "é" "e") + (sort-rule "ç" "c") + + (sort-rule "\\texttt{\(.*\)}" "\1" :again :bregexp) + ) + +#+:STEP5 +(progn + (define-letter-groups + ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" + "n" "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z")) + + (markup-letter-group-list :sep "~n~n \indexspace~n") + ) diff --git a/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy b/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy new file mode 100644 index 00000000000..e45e2f24482 --- /dev/null +++ b/Master/texmf-dist/doc/xindy/style-tutorial/style2.xdy @@ -0,0 +1,80 @@ +;; This is another example using `xindy'. + +(mapc #'(lambda (x) + (pushnew x *features*)) + '(:STEP1 :STEP2 :STEP3 :STEP4 :STEP5 :STEP6 :STEP7 :STEP8 :STEP9 :STEP10)) + +#+:STEP1 +(progn + (define-location-class "page-numbers" ("arabic-numbers")) + (define-attributes (("definition" "usage"))) + ) + + +#+:STEP2 +(progn + (markup-index :open "~n\begin{theindex}~n" + :close "~n~n\end{theindex}~n" + :tree) + + (markup-locref :class "page-numbers" :attr "definition" + :open "{\bf " :close "}") + + (markup-locref-list :sep ", ") + (markup-locclass-list :open "\quad{}") + ) + +#+:STEP3 +(progn + (markup-indexentry :open "~n \item " :depth 0) + (markup-indexentry :open "~n \subitem " :depth 1) + (markup-indexentry :open "~n \subsubitem " :depth 2) + ) + +#+:STEP4 +(progn + (sort-rule "à" "a") + (sort-rule "á" "a") + (sort-rule "ã" "a") + (sort-rule "è" "e") + (sort-rule "é" "e") + (sort-rule "ç" "c") + + (sort-rule "\\texttt{(.*)}" "\1" :again :bregexp) + ) + +#+:STEP5 +(progn + (define-letter-groups + ("a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" + "n" "o" "p" "q" "r" "s" "t" "u" "v" "w" "x" "y" "z")) + + (markup-letter-group-list :sep "~n~n \indexspace~n") + ) + +#+:STEP6 +(progn + (define-location-class "roman-pages" ("roman-numbers-lowercase")) + #-:STEP8 + (define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers")) + ) + +#+:STEP7 +(markup-range :sep "--") + +#+:STEP8 +(progn + (define-location-class "appendices" ("ALPHA" :sep "-" "arabic-numbers") + :hierdepth 2) + (markup-locref-list :sep "; " :depth 0 :class "appendices") + (markup-locref-list :open "~~" :sep ", " :depth 1 :class "appendices") + ) + +#+:STEP9 +(progn + (define-letter-group "ly" :after "l" :before "m") + (define-letter-group "ny" :after "n" :before "o") + + (markup-letter-group :open-head "~n {\bf " :close-head "}" + :capitalize) + ) diff --git a/Master/texmf-dist/doc/xindy/tex2xindy.pdf b/Master/texmf-dist/doc/xindy/tex2xindy.pdf new file mode 100644 index 00000000000..65b834d225d Binary files /dev/null and b/Master/texmf-dist/doc/xindy/tex2xindy.pdf differ diff --git a/Master/texmf-dist/doc/xindy/texindy.pdf b/Master/texmf-dist/doc/xindy/texindy.pdf new file mode 100644 index 00000000000..0d460cc060f Binary files /dev/null and b/Master/texmf-dist/doc/xindy/texindy.pdf differ diff --git a/Master/texmf-dist/doc/xindy/xindy.pdf b/Master/texmf-dist/doc/xindy/xindy.pdf new file mode 100644 index 00000000000..f861491dfb8 Binary files /dev/null and b/Master/texmf-dist/doc/xindy/xindy.pdf differ -- cgit v1.2.3