Debian Codegraph @

texmf-dist/doc/xelatex/xeindex/xeindex.tex

raw
1 \ifnum\month<10 \edef\month{0\the\month}\else \edef\month{\the\month}\fi
2 \ifnum\day<10 \edef\day{0\the\day}\else \edef\day{\the\day}\fi
3 \documentclass[%
4 %produce,% Uncomment this line to produce xeindex.sty
5 ]{codedoc}
6
7 \usepackage{xeindex}
8
9 \usepackage{silence,xcolor,xltxtra}
10 \WarningFilter{latex}{Marginpar}
11 \setmainfont[Mapping=tex-text]{Bodoni MT}
12 \setmonofont[Mapping=tex-text,Scale=.75]{Lucida Console}
13 \setsansfont[Mapping=tex-text]{Arial}
14 \usepackage[paperwidth=23cm,paperheight=17.5cm,top=1.5cm,bottom=1.5cm,textwidth=14.5cm,right=1.5cm]{geometry}
15
16 \ProduceFile{xeindex.sty}[xeindex][v.0.3][\the\year/\month/\day]
17 \let\printmacro\PrintMacro
18 \newskip\macroskip
19 \def\PrintMacro#1{%
20 \ifdim\macroskip=0pt
21 \midbreak
22 \fi
23 \noindent
24 \setbox0=\hbox{%
25 \lower\macroskip\hbox{%
26 \llap{%
27 \textcolor{red!80!black}{\texttt{#1}}%
28 \enspace
29 }%
30 }%
31 }%
32 \dp0=0pt
33 \box0
34 \macroskip0pt
35 \ignorespaces
36 }
37 \ShortVerb"
38 \CodeFont{\ttfamily\color{red!80!black}}
39 \LineNumber{code}{\footnotesize}{1em}
40
41 \newskip\midskip
42 \midskip=6pt plus 4pt minus 4pt
43 \def\midbreak{\vskip\midskip}
44 \RenewExample{example}{\ttfamily#}{}{\midbreak\noindent\CodeInput\midbreak}
45
46 \title{\FileName\\\FileVersion}
47 \author{Paul Isambert\\\texttt{[email protected]}}
48 \date{\FileDate}
49
50 \def\xeindex{\Xe\kern-.1em Index}
51 \def\xesearch{\Xe\kern-.1em Search}
52 \def\XeLaTeX{\Xe\kern-.1em L\kern-.3em\raise.15em\hbox{\scriptsize A}\kern-.1em\TeX}
53 \SearchList{logos}{\csname#1\endcsname}{xe?,*Xe?}
54 \SearchList{logos2}{\XeTeX}{xetex}
55
56 \begin{document}
57
58 %\maketitle
59
60 {\Huge\hfill\FileName}\par
61 \hfill\FileVersion\ – \FileDate\par
62 {\it \hfill(I simply added a missing comment sign after 4 years of inactivity.\par
63 \hfill The problem was spotted by Tomas Jonsson.)\par}
64 \hfill Paul Isambert – \texttt{[email protected]}\par
65
66
67 \begin{abstract}
68 xeindex is a package based on xesearch that automatically
69 indexes words in a XeLaTeX document. Words or phrases
70 (possibly underspecified) are declared in a list and
71 each of their occurrences then creates an index entry,
72 whose content might be freely specified beforehand.
73 \end{abstract}
74
75 \thispagestyle{empty}
76 Automatic indexes are bad. You know that. Hence the severe
77 look of this documentation. So: don't use xeindex.
78 Or: use it as a tool to generate an index whose relevance
79 you then check. Or: use it for entries that are generally indexed
80 on every occurrence, like proper names. Or: do bad indexes.
81
82 You load xeindex in the usual way:
83
84 \VerbCommand!()
85 \begin{example}
86 !StopSearching()\usepackage{xeindex}
87 \end{example}
88 \UndoVerbCommand
89
90 \noindent
91 There's only one package option, namely \texttt{mark}, which
92 prefixes all index entries generated by xeindex with
93 "***["\meta{word}":"\meta{line number}"]", where \meta{word}
94 is the word that generated the entry and \meta{line number}
95 the line where you can find it in the ".tex" file. Moreover,
96 if a word appears more than once on a page, and thus generates
97 several index entries although they'll be merged in the
98 typeset index, with this option each entry is listed along
99 with each occurrence of the word.
100 So these entries end up at the beginning of the index, sorted with
101 symbols, apart from the entries generated by the usual
102 "\index" command. Thus they can be easily checked and prevented
103 if irrelevant.
104
105 \DescribeMacro\makeindex\macroskip\baselineskip
106 \DescribeMacro\printindex\macroskip2\baselineskip
107 \DescribeMacro{\index\marg{entry}}
108 xeindex loads the \texttt{makeidx} package, so "\makeindex" and "\printindex",
109 which should be executed as usual, as well as the usual "\index" command,
110 are available. (If you don't know what I'm talking about, then you
111 don't know how to produce an index. You should read the \texttt{makeidx}
112 documentation at least, or the rest of this document might seem cryptic.)
113
114 \DescribeMacro{\IndexList\meta{*}\marg{name}\marg{list of entries}}
115 This is xeindex's main command. The star is optional and \meta{list of entries} is
116 made of \meta{word}\textcolor{red!80!black}{$=$\meta{entry}} pairs
117 separated by commas, with the part in red optional too.
118 Let's see the simplest possibility first:
119
120 \begin{example}
121 \IndexList{mylist}{alley cat,dog,gnu}
122 \end{example}
123
124 \noindent
125 This will index \emph{alley cat} on every occurrence of \emph{alley cat}
126 in your document, \emph{dog} on every occurrence of \emph{dog},
127 and \emph{gnu} on every occurrence of \emph{gnu}.
128 But this will also index \emph{alley cat} when seeing \emph{Alley cat},
129 \emph{dog} when seeing \emph{dOg}, and \emph{gnu} when
130 seeing \emph{GNU}. In other words, xeindex is case-%
131 insensitive by default, and the index entries are put
132 in lower case. Most of the time, that's useful. But a gnu
133 is not GNU, so sometimes you want a different behavior.
134 In this case, put a "*" before the word, e.g.:
135
136 \begin{example}
137 \IndexList{mylist}{alley cat,DOG,gnu,*GNU}
138 \end{example}
139
140 \noindent
141 Now xeindex will index \emph{gnu} when seeing \emph{gnu}
142 or \emph{Gnu}, but it will index \emph{GNU} when seeing
143 \emph{GNU}. Note that \texttt{DOG} without a star will
144 index \emph{dog} in any case display, and the index entry
145 will be \emph{dog}, not \emph{DOG}.
146 You can also make a whole list case-sensitive,
147 by adding the star just after "\IndexList", as in:
148
149 \begin{example}
150 \IndexList{mylist}{alley cat,dog,gnu}
151 \IndexList*{mylist}{GNU}
152 \end{example}
153
154 \noindent
155 All words in a "*"-marked list are case-sensitive, and
156 you should not add another star before them. Note that you
157 can use the same list with different case-sensitivies each
158 time, as in the above example.
159
160 Case-sensitity is useful mostly to index proper names.
161
162 \midbreak
163
164 The words in a list need not be fully specified. You can
165 index all words beginning or ending with some letters. To
166 do so, use "?" for the unspecified part. For instance,
167
168 \begin{example}
169 \IndexList{mylist}{cat?,?mals,*?NU}
170 \end{example}
171
172 \noindent
173 will find and index \emph{cat}, \emph{cats}, \emph{catheter},
174 \emph{animals}, \emph{mammals}, \emph{GNU}, \emph{gNU}, but
175 not \emph{gnu}, because "*?NU" means `a word that ends with
176 ``NU'' in upper case.'
177 Each of these words will be indexed in its own entry,
178 so there'll be a \emph{cat} and a \emph{cats} entry, but we'll
179 learn how to have them grouped presently. If a word matches several
180 underspecified forms, the more specific wins, e.g.
181 \emph{mammals} matches \texttt{mam?} and not \texttt{ma?},
182 and `starting-with' forms always win against `ending-with' ones,
183 no matter the degree of specificity, e.g. \emph{cat} matches
184 \texttt{c?} and not \texttt{?at}. Phrases, i.e. words
185 separated by blanks (like \emph{alley cat} above) can be
186 underspecified only at the end, i.e. you can say
187 \texttt{alley ca?} but not \texttt{?ley cat} (actually
188 you can try but it won't work). Finally, underspecified
189 parts are only the beginning or the end of a word, i.e.
190 you can't say \texttt{c?t}, and there should be only
191 one underspecification, i.e. \texttt{?a?} is forbidden.
192
193 \midbreak
194
195 Now we come to the interesting part in
196 \meta{word}\textcolor{red!80!black}{$=$\meta{entry}}, namely the
197 red part: \meta{entry} should be a pseudo-index entry,
198 as it were, i.e. it can be a normal index entry, as in
199
200 \begin{example}
201 \IndexList{another list}{%
202 dog=mammal|textit,
203 snail=Obviously Not Mammal,
204 cat=mammal!pet,
205 horse?=horse@{\bfseries horse}}
206 \end{example}
207
208 \noindent
209 Here, every occurrence of \emph{dog} will produce
210 an index entry at \emph{mammal} with the page number
211 in italic, \emph{snail} will index \emph{Obviously Not Mammal},
212 \emph{cat} will create a sub-entry \emph{pet} in the
213 \emph{mammal} entry and \emph{horse}, \emph{horses},
214 \emph{horseshoe}, etc., will create a bold entry
215 at \emph{horse}. So, as you can see, the left part
216 of the expression specifies which words should generate
217 an index entry, and the right part is the index entry
218 that should be generated. The latter is not case-insensitive
219 anymore: although \texttt{snail} is case-insensitive
220 and will fire on \emph{snail}, \emph{Snail} or
221 \emph{SNaIl}, the index entry itself will be as specified, i.e.
222 \emph{Obviously Not Mammal} and not \emph{obviously not mammal}.
223
224 Now you can index variations of a word under the
225 same entry. As I've just said, \emph{horse} and \emph{horses}
226 will both be indexed under \emph{horse}, as well as
227 all their case-variants, as we already know.
228 (\emph{Horseshoe} will go in that entry too, so beware).
229
230 The right part of those pairs is a `pseudo-index entry,'
231 and not a proper index entry, because the word to index
232 can be omitted, in which case the word that fires the
233 index entry will be used instead. More precisely, whenever
234 xeindex encounters one of the usual MakeIndex operators,
235 namely "!" (for a sub-entry), "|" (for a control sequence)
236 and "@" (to indicate the form of the entry irrespective
237 of alphabetical order), at the beginning of an index entry,
238 it reinterprets this entry with the the firing
239 word or phrase on its left. I.e.
240
241 \begin{example}
242 \IndexList{yet another list}{%
243 dog=@dog (canis lupus familiaris),
244 cat=!basic definition,
245 horse?=|textbf}
246 \end{example}
247
248 \noindent
249 indexes every occurence of \emph{dog} as \emph{dog (canis lupus familiaris)},
250 but with the alphabetical order of \emph{dog},
251 every occurrence of \emph{cat} as a \emph{basic definition} subentry
252 in the \emph{cat} entry, and every occurrence of a word beginning with
253 \emph{horse} as an entry for this word with the page number in boldface.
254 Remember that the "\index" command is still available, so you can still
255 index \emph{cat} as \emph{cat} in your document.
256
257 It's obviously a very bad idea to say something like
258 "\IndexList{mylist}{cat=|(}", since this will fire "\index{cat|(}"
259 on every occurrence of \emph{cat}. So page ranges can't be declared
260 by xeindex (it would be a very bad idea anyway). On the other
261 hand, MakeIndex automatically creates page ranges as soon as
262 an entry is found on at least three successive pages, unless you run it
263 with the "-r" option.
264
265 If you want a comma in the right part of the entry, enclose
266 the entire entry, minus the MakeIndex operator if any, between braces, e.g.:
267
268 \begin{example}
269 \IndexList{writers}{Kafka={Kafka, Franz}}
270 \end{example}
271
272 \noindent
273 (This did not work in version 0.1, and now it's corrected
274 thanks to Simon Spiegel who indicated it to me.)
275
276 \DescribeMacro{\StopIndexList\marg{lists}}\macroskip\baselineskip
277 \DescribeMacro{\StopIndex}\macroskip2\baselineskip
278 \DescribeMacro{\NoIndex\marg{text}}
279 Here are some additional macros to let you regulate the flow of
280 the indexing frenzy.
281 "\StopIndexList" takes a comma-separated list of lists and turn them off.
282 "\StopIndex" turns off all lists.
283 "\NoIndex" simply prevents \meta{text} from being indexed. It's very important,
284 because it lets you prevent irrelevant indexation in the body of your
285 document.
286
287 That's all you need to know to use xeindex. The next paragraph
288 describes how xeindex sets the parameters of xesearch; so if
289 you don't know xesearch and don't intend to use it, there's no need to
290 read what follows.
291
292 \midbreak
293
294 xeindex keeps xesearch's default search order, namely full words before
295 prefixes before suffixes, with case-sensitive tests first each time.
296 Affixes are modified, however: they're sorted by length (longer ones first)
297 and not kept in the order they were declared, and only one affix fires
298 in case of a successful test, instead of all the affixes of a given
299 test. You can modify these specifications since xeindex uses "!"-marked
300 replacement texts, so they won't embed each other, but then you might
301 end up with multiple entries and a lack of consistency.
302
303 You can use "\StartSearching" and "\StopSearching" instead of "\StopIndex",
304 which for the moment renders all lists unavailable. The former two
305 commands, however, will stop all lists defined by xesearch.
306
307 The default set of boundaries is left untouched, i.e. its members are:
308 ".,;:-`'()[]{}"
309
310
311
312
313
314 \section*{Implementation}
315
316 \let\PrintMacro\printmacro
317 \DocStripMarginpar
318
319 Basic declarations and definitions.
320
321 \BoxTolerance\maxdimen
322 \ShortCode/
323 \CodeEscape!
324 \StopSearching
325 /
326 \ProvidesPackage{!FileName}[!FileDate !FileVersion Automatic index for XeLaTeX.]
327 /
328 \UndoCodeEscape
329 \StartSearching
330
331 /
332 \RequirePackage{makeidx,xesearch}
333 \makeatletter
334 \newif\ifxi@mark
335 \DeclareOption{mark}{\xi@marktrue}
336 \ProcessOptions
337 /
338
339 \DefineMacro\xi@Mark
340 \DefineMacro\xi@empty
341 \DefineMacro\xi@end
342 \DefineMacro\xi@Lists
343 "\xi@Mark" either shows the word and the corresponding line,
344 or it gobbles it. It is placed at the beginning of
345 the "\index" command, whose expansion is delayed accordingly.
346 /
347 \ifxi@mark
348 \def\xi@Mark#1{***[#1:\the\inputlineno] }
349 \else
350 \def\xi@Mark#1{}
351 \fi
352 \def\xi@empty{}
353 \def\xi@end{\xi@end}
354 \def\xi@Lists{}
355 /
356
357 \DefineMacro\IndexList
358 \DefineMacro\xi@IndexList
359 Most of the job is done by xesearch. What we need to do
360 is properly analyze the entry to launch an adequate search.
361 /
362 \def\IndexList{%
363 \@ifstar{\def\xi@cs{*}\xi@IndexList}{\def\xi@cs{}\xi@IndexList}%
364 }
365 \def\xi@IndexList#1#2{%
366 \def\xi@ListName{#1}%
367 \edef\xi@Lists{\xi@Lists#1,}%
368 \unless\ifcsname#1@xeindex\endcsname
369 \csname#1@xeindex\endcsname
370 /
371
372 \noindent
373 When a index list is created, we associate five xesearch
374 lists with it: one is for words and affixes that should index
375 themselves in lower case.
376 /
377 \SearchList{#1@xeindex@ncs@normal@list}{%
378 \def\xi@Word{##1}%
379 \lowercase{\expandafter\index\expandafter{\xi@Mark\xi@Word##1}}}{}%
380 /
381
382 \noindent
383 Another one is for case-sensitive words and affixes.
384 /
385 \SearchList{#1@xeindex@cs@normal@list}{%
386 \expandafter\index\expandafter{\xi@Mark{##1}##1}}{}%
387 /
388
389 \noindent
390 And the last three are for words and affixes that launch
391 a special entry, which is stored in an associated command.
392 /
393 \SearchList{#1@xeindex@ncs@special@list}{%
394 \lowercase{\csname##1@#1@xeindex@entry\endcsname}{##1}}{}%
395 \SearchList{#1@xeindex@cs@special@list}{%
396 \csname##1@#1@xeindex@entry\endcsname{##1}}{}%
397 \SearchList{#1@xeindex@affix@special@list}{%
398 \csname\AffixFound @#1@xeindex@entry\endcsname{##1}}{}%
399 \fi
400 \xi@ParseList#2,\xi@end,%
401 }
402 /
403
404 \DefineMacro\xi@ParseList
405 This macro recursively tests each entry in "\SearchList"
406 and feed it to "\xi@ParseEntry" with an additional "="
407 to check for the right part. It also adds "\xi@cs", which
408 was defined do "*" in case "\SearchList" was starred.
409 /
410 \def\xi@ParseList#1,{%
411 \def\xi@temp{#1}%
412 \ifx\xi@temp\xi@end
413 \let\xi@next\relax
414 \else
415 \expandafter\xi@ParseEntry\xi@cs#1=\xi@end
416 \let\xi@next\xi@ParseList
417 \fi\xi@next
418 }
419 /
420
421
422 \DefineMacro\xi@ParseEntry
423 This one analyses the entry. If the third argument
424 is empty, then there is no $=$\meta{entry} part
425 in the entry. In this case we add the word or
426 affix to one of the two simple lists, depending
427 on its case-sensitivity.
428 /
429 \def\xi@ParseEntry#1#2=#3\xi@end{%
430 \def\xi@temp{#3}%
431 \ifx\xi@temp\xi@empty
432 \expandafter\if\noexpand#1*%
433 \AddToList!{\xi@ListName @xeindex@cs@normal@list}{#1#2}%
434 \else
435 \AddToList!{\xi@ListName @xeindex@ncs@normal@list}{#1#2}%
436 \fi
437 /
438
439 \noindent
440 Otherwise we feed the right part to "\xi@MakeEntry" which
441 sets the "\ifxi@NoWord" switch. We also check whether the
442 word is an affix or not, and whether it is case-sensitive.
443 The word is then associated to the right list and an
444 associated macro is created.
445 /
446 \else
447 \xi@MakeEntry#3%
448 \expandafter\if\noexpand#1*%
449 \xi@CheckAffix#2?\xi@end
450 \ifxi@Affix
451 \AddToList!{\xi@ListName @xeindex@affix@special@list}{#1#2}%
452 \expandafter\edef\csname\xi@Affix @\xi@ListName @xeindex@entry\endcsname##1{%
453 \unexpanded{\expandafter\index\expandafter}{%
454 \noexpand\xi@Mark{##1}\ifxi@NoWord##1\fi\unexpanded\expandafter{\xi@temp}}%
455 }%
456 \else
457 \AddToList!{\xi@ListName @xeindex@cs@special@list}{#1#2}%
458 \expandafter\edef\csname#2@\xi@ListName @xeindex@entry\endcsname##1{%
459 \unexpanded{\expandafter\index\expandafter}{%
460 \noexpand\xi@Mark{##1}\ifxi@NoWord#2\fi\unexpanded\expandafter{\xi@temp}}%
461 }%
462 \fi
463 \else
464 \xi@CheckAffix#1#2?\xi@end
465 \ifxi@Affix
466 \AddToList!{\xi@ListName @xeindex@affix@special@list}{#1#2}%
467 \expandafter\edef\csname\xi@lcAffix @\xi@ListName @xeindex@entry\endcsname##1{%
468 \unexpanded{\def\xi@Word}{##1}%
469 \noexpand\lowercase{%
470 \unexpanded{\expandafter\index\expandafter}{%
471 \unexpanded{\xi@Mark{\xi@Word}}%
472 \ifxi@NoWord##1\fi\unexpanded\expandafter{\xi@temp}}%
473 }%
474 }%
475 \else
476 \AddToList!{\xi@ListName @xeindex@ncs@special@list}{#1#2}%
477 \lowercase{%
478 \expandafter\edef\csname#1#2@\xi@ListName @xeindex@entry\endcsname##1{%
479 \unexpanded{\def\xi@Word}{##1}%
480 \unexpanded{\expandafter\index\expandafter}{%
481 \unexpanded{\xi@Mark{\xi@Word}}%
482 \ifxi@NoWord#1#2\fi\unexpanded\expandafter{\xi@temp}}%
483 }%
484 }%
485 \fi
486 \fi
487 \fi
488 }
489 /
490
491 \DefineMacro\xi@MakeEntry
492 This determines whether the entry starts with one
493 of the MakeIndex operators.
494 /
495 \newif\ifxi@NoWord
496 \def\xi@exclam{!} \def\xi@at{@} \def\xi@bar{|}
497 \def\xi@MakeEntry#1#2={%
498 \def\xi@temp{#1#2}%
499 \xi@NoWordtrue
500 \unless\ifx\xi@temp\xi@exclam
501 \unless\ifx\xi@temp\xi@at
502 \unless\ifx\xi@temp\xi@bar
503 \xi@NoWordfalse
504 \fi
505 \fi
506 \fi
507 }
508 /
509
510 \DefineMacro\xi@CheckAffix
511 If the first argument is "?", then the word is
512 unspecified at the beginning. Otherwise, if
513 the third argument is not empty, then it is unspecified
514 at the end (because we added a "?" when giving the
515 word to this macro). In case the "?" is misplaced,
516 xesearch will detect it later.
517 /
518 \newif\ifxi@Affix
519 \def\xi@CheckAffix#1#2?#3\xi@end{%
520 \xi@Affixfalse
521 \expandafter\if\noexpand#1?%
522 \xi@Affixtrue
523 \def\xi@Affix{#2}%
524 \lowercase{\def\xi@lcAffix{#2}}%
525 \else
526 \def\xi@@temp{#3}%
527 \unless\ifx\xi@@temp\xi@empty
528 \xi@Affixtrue
529 \def\xi@Affix{#1#2}%
530 \lowercase{\def\xi@lcAffix{#1#2}}%
531 \fi
532 \fi
533 }
534 /
535
536 \DefineMacro\StopIndexList
537 \DefineMacro\xi@StopIndexList
538 \DefineMacro\StopIndex
539 \DefineMacro\NoIndex
540 These are straightforward.
541 /
542 \def\StopIndexList#1{%
543 \xi@StopIndexList#1,\xi@end,%
544 }%
545 \def\xi@StopIndexList#1,{%
546 \def\xi@temp{#1}%
547 \ifx\xi@temp\xi@end
548 \let\xi@next\relax
549 \else
550 \StopList{%
551 #1@xeindex@ncs@normal@list,%
552 #1@xeindex@cs@normal@list,%
553 #1@xeindex@cs@normal@list,%
554 #1@xeindex@ncs@special@list,%
555 #1@xeindex@cs@special@list,%
556 #1@xeindex@affix@special@list%
557 }%
558 \let\xi@next\xi@StopIndexList
559 \fi\xi@next
560 }
561 \def\StopIndex{%
562 \expandafter\xi@StopIndexList\xi@Lists\xi@end,%
563 }
564 \def\NoIndex#1{%
565 \bgroup
566 \StopIndex
567 #1%
568 \egroup
569 }
570 /
571
572 \DefineMacro\xi@PrintIndex
573 Finally, we patch "\printindex" so it won't be searched,
574 and sets xesearch's parameters.
575 /
576 \let\xi@PrintIndex\printindex \def\printindex{\StopIndex\xi@PrintIndex}
577 \SortByLength{pPsS} \SearchOnlyOne{pPsS}
578 \makeatother
579 /
580 \end{document}
581