summaryrefslogtreecommitdiff
path: root/indexing/upmendex/man/upmendex.1
blob: b46ab922de185a60b00446714a4d6438044b4e5f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
.TH UPMENDEX 1
\"=====================================================================
.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
.if n .ds TX TeX
.\" LX definition must follow TX so LX can use TX
.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
.if n .ds LX LaTeX
\"=====================================================================
.SH NAME
upmendex \- Multilingual index processor
.SH SYNOPSIS
\fBupmendex\fR [-ilqrcgf] [\fB-s\fI sty\fR] [\fB-d\fI dic\fR] [\fB-o\fI ind\fR] [\fB-t\fI log\fR] [\fB-p\fI no\fR] [\fB--\fR] [\fI idx0 idx1 idx2 ...\fR]
.br
\fBupmendex\fR \fB--help\fR
.SH DESCRIPTION
.PP
The program \fIupmendex\fR is a general purpose multilingual hierarchical
index generator working with up\*(LX, Xe\*(LX and Lua\*(LX;
it accepts one or more input files (\fI.idx\fR; often produced by a text
formatter such as \*(LX families), sorts the entries, and produces an output file
which can be formatted.
It supports Latin (including non-English), Greek, Cyrillic, Korean Hangul and
Han (Hanzi ideographs) scripts, as well as Japanese Kana.
It is almost compatible with \fImakeindex\fR and \fImendex\fR, and
additional feature for handling readings of kanji words is also available.
.RE
The formats of the input and output files are specified in a style file.
The readings of kanji words can be specified in a dictionary file.
.RE
The index can have up to three levels (0, 1, and 2) of subitem nesting.
.SH OPTIONS
.PP
.TP 10
\fB-i\fR
Take input from stdin, even when index files are specified.
.TP 10
\fB-l\fR
Set \'sort by character order\'. By default, \'sort by word order\' is used.
Details are described below.
.TP 10
\fB-q\fR
Quiet mode; send no message to \fIstderr\fR, except error
messages and warnings.
.TP 10
\fB-r\fR
Disable implicit page range formation. By default, three or
more successive pages are automatically abbreviated as a range
(e.g. 1\(en5).
.TP 10
\fB-c\fR
Compress sequence of intermediate blanks (space(s) and/or tab(s)) into a space
and ignore leading and trailing blank(s).
By default, blanks in the index key are retained.
.TP 10
\fB-g\fR
Make Japanese index head \fIA\fR-line (\fIA, Ka, Sa, ...\fR) of the gojuon table (Japanese
syllabary). By default, all the characters in the gojuon table
are used.
.TP 10
\fB-f\fR
Force to output characters even if the scripts are not supported by \fIupmendex\fR.
.TP 10
\fB-s\fI sty\fR
Employ \fIsty\fR as the style file.
.TP 10
\fB-d\fI dic\fR
Employ \fIdic\fR as the dictionary file. The dictionary file is
composed of lists of <\fIindex_word\fR\ \fIreading\fR>.
.TP 10
\fB-o\fI ind\fR
Employ \fIind\fR as the output index file. By default, the file
name is created by appending the extension \fIind\fR to the base
name of the first input file.
.TP 10
\fB-t\fI log\fR
Employ \fIlog\fR as the transcript file. By default, the file name
is created by appending the extension \fIilg\fR to the base name
of the first input file.
.TP 10
\fB-p\fI no\fR
Set the starting page number of the output index list to be
\fIno\fR. The argument \fIno\fR may be numerical or one of
the following: \fIany\fR (the next page to the end of contents), \fIodd\fR
(the next odd page to the end of contents), \fIeven\fR (the next even page to the end of contents).
.TP 10
\fB--help\fR
Show summary of options.
.TP 10
\fB--\fR
Arguments after \fB--\fR are not taken as options.

.SH "STYLE FILE"
The style file informs \fIupmendex\fR about the format of the
\fIidx\fR input files and the intended format of the final
output file. The format is upper compatible with the one for
\fImakeindex\fR and \fImendex\fR.
The style file contains a list of
<\fIspecifier\fR\ \fIattribute\fR> pairs.
There are two types of specifiers: input and output.
Pairs do not have to appear in any particular order.
A line begun by \'%\' is a comment.

.PP
\fBInput file style parameter\fR
.TP 30
\fBkeyword\fR  <string>
"\\\\indexentry"
.RS
Command with an argument of index entry.
.RE
.TP 30
\fBarg_open\fR  <char>
\'{\'
.RS
Opening delimiter which shows the beginning of index entry.
.RE
.TP 30
\fBarg_close\fR  <char>
\'}\'
.RS
Closing delimiter which shows the end of index entry.
.RE
.TP 30
\fBrange_open\fR  <char>
\'(\'
.RS
Opening delimiter which shows the beginning of page range.
.RE
.TP 30
\fBrange_close\fR  <char>
\')\'
.RS
Closing delimiter which shows the end of page range.
.RE
.TP 30
\fBlevel\fR  <char>
\'!\'
.RS
Delimiter which shows lower level.
.RE
.TP 30
\fBactual\fR  <char>
\'@\'
.RS
Symbol which shows the next sequence is to appear as index strings
in the output file.
.RE
.TP 30
\fBencap\fR  <char>
\'|\'
.RS
Symbol which shows the next sequence is to be used as command name
attached to the page number.
.RE
.TP 30
\fBpage_compositor\fR  <string>
"-"
.RS
Separator between page levels for a style with multi-levels of page numbers.
.RE
.TP 30
\fBpage_precedence\fR  <string>
"rnaRA"
.RS
Priority of expression for page number.
\'R\' and \'r\' correspond to Roman. \'n\' corresponds to arabic numeral.
\'A\' and \'a\' correspond to Latin alphabet.
.RE
.TP 30
\fBquote\fR  <char>
\'"\'
.RS
Escape character for \fIupmendex\fR parameters.
.RE
.TP 30
\fBescape\fR  <char>
\'\\\\\'
.RS
Escape character for general scripts.
.RE

\fBOutput file style parameter\fR
.TP 30
\fBpreamble\fR  <string>
"\\\\begin{theindex}\\n"
.RS
Preamble of output file.
.RE
.TP 30
\fBpostamble\fR  <string>
"\\n\\n\\\\end{theindex}\\n"
.RS
Postamble of output file.
.RE
.TP 30
\fBsetpage_prefix\fR  <string>
"\\n  \\\\setcounter{page}{"
.RS
Prefix of page number if start page is designated.
.RE
.TP 30
\fBsetpage_suffix\fR  <string>
"}\\n"
.RS
Suffix of page number if start page is designated.
.RE
.TP 30
\fBgroup_skip\fR  <string>
"\\n\\n  \\\\indexspace\\n"
.RS
Strings to insert vertical space before new section of index.
.RE
.TP 30
\fBlethead_prefix\fR  <string>
""
.RS
Prefix of heading for newly appeared heading letter.
.RE
.TP 30
\fBheading_prefix\fR  <string>
""
.RS
Same as \fBlethead_prefix\fR.
.RE
.TP 30
\fBlethead_suffix\fR  <string>
""
.RS
Suffix of heading for newly appeared heading letter.
.RE
.TP 30
\fBheading_suffix\fR  <string>
""
.RS
Same as \fBlethead_suffix\fR.
.RE
.TP 30
\fBlethead_flag\fR  <number>
0
.RS
Flag to control output of heading letters in Latin, Greek and Cyrillic scripts.
\'0\', \'1\', \'-1\' and \'2\' respectively denotes no output, uppercase,
lowercase and titlecase.
.RE
.TP 30
\fBheading_flag\fR  <number>
0
.RS
Same as \fBlethead_flag\fR.
.RE
.TP 30
\fBkana_head\fR  <string>
""
.RS
Heading characters of Kana specified by a string.
By default, it is controlled by \fBletter_head\fR and
command line option \fB-g\fR.
(Extended by upmendex)
.RE
.TP 30
\fBhangul_head\fR  <string>
"ㄱㄴㄷㄹㅁㅂㅅㅇㅈㅊㅋㅌㅍㅎ"
.RS
Heading characters of Hangul specified by a string.
(Extended by upmendex)
.RE
.TP 30
\fBtumunja\fR  <string>
"ㄱㄴㄷㄹㅁㅂㅅㅇㅈㅊㅋㅌㅍㅎ"
.RS
Heading characters of Hangul specified by a string.
(Deprecated, Extended by upmendex)
.RE
.TP 30
\fBhanzi_head\fR  <string>
""
.RS
Heading strings of hanzi (Kanji, Hanja)
specified by a string, which is
concatenated of items with a separator \';\'.
(Extended by upmendex)
.RE
.TP 30
\fBdevanagari_head\fR  <string>
"ऄअआइईउऊऋऌऍऎएऐऑऒओऔकखगघङचछजझञटठडढणतथदधनपफबभमयरलळवशषसह"
.RS
Heading characters of Devanagari specified by a string.
(Experimental, Extended by upmendex)
.RE
.TP 30
\fBthai_head\fR  <string>
"กขฃคฅฆงจฉชซฌญฎฏฐฑฒณดตถทธนบปผฝพฟภมยรฤลฦวศษสหฬอฮ"
.RS
Heading characters of Thai script specified by a string.
(Experimental, Extended by upmendex)
.RE
.TP 30
\fBitem_0\fR  <string>
"\\n  \\\\item "
.RS
Command sequence inserted between primary level entries.
.RE
.TP 30
\fBitem_1\fR  <string>
"\\n     \\\\subitem "
.RS
Command sequence inserted between sub level entries.
.RE
.TP 30
\fBitem_2\fR  <string>
"\\n       \\\\subsubitem "
.RS
Command sequence inserted between subsub level entries.
.RE
.TP 30
\fBitem_01\fR  <string>
"\\n    \\\\subitem "
.RS
Command sequence inserted between primaly and sub level entries.
.RE
.TP 30
\fBitem_x1\fR  <string>
"\\n    \\\\subitem "
.RS
Command sequence inserted between primary and sub level entries
when main entry does not have page number.
.RE
.TP 30
\fBitem_12\fR  <string>
"\\n    \\\\subsubitem "
.RS
Command sequence inserted between sub and subsub level entries.
.RE
.TP 30
\fBitem_x2\fR  <string>
"\\n    \\\\subsubitem "
.RS
Command sequence inserted between sub and subsub level entries
when sub level entry does not have page number.
.RE
.TP 30
\fBdelim_0\fR  <string>
", "
.RS
Delimiter string between primary level entry and first page number.
.RE
.TP 30
\fBdelim_1\fR  <string>
", "
.RS
Delimiter string between sub level entry and first page number.
.RE
.TP 30
\fBdelim_2\fR  <string>
", "
.RS
Delimiter string between subsub level entry and first page number.
.RE
.TP 30
\fBdelim_n\fR  <string>
", "
.RS
Delimiter string between page numbers
commonly used for any entry level.
.RE
.TP 30
\fBdelim_r\fR  <string>
"--"
.RS
Delimiter string between pages to show page range.
.RE
.TP 30
\fBdelim_t\fR  <string>
""
.RS
Delimiter string output at the end of page number list.
.RE
.TP 30
\fBsuffix_2p\fR  <string>
""
.RS
String to be inserted in place of \fBdelim_n\fR and the next page
number when the two pages are contiguous.
.RE
It works only when the parameter is defined.
.RE
.TP 30
\fBsuffix_3p\fR  <string>
""
.RS
String to be inserted in place of \fBdelim_r\fR and the third page
number when the three pages are contiguous.
The parameter is prior to \fBsuffix_mp\fR.
.RE
It works only when the parameter is defined.
.RE
.TP 30
\fBsuffix_mp\fR  <string>
""
.RS
String to be inserted in place of \fBdelim_r\fR and the last page
number when the three or more pages are contiguous.
.RE
It works only when the parameter is defined.
.RE
.TP 30
\fBencap_prefix\fR  <string>
"\\\\"
.RS
Prefix for an encapsulating command
when the encapsulating command is added to the page number.
.RE
.TP 30
\fBencap_infix\fR  <string>
"{"
.RS
Prefix just before the page number
when the encapsulating command is added to the page number.
.RE
.TP 30
\fBencap_suffix\fR  <string>
"}".
.RS
Suffix after the page number
when the encapsulating command is added to the page number.
.RE
.TP 30
\fBline_max\fR  <number>
72
.RS
Maximum number of one line.
If exceed the number, lines are folded.
.RE
.TP 30
\fBindent_space\fR  <string>
"\t\t"
.RS
Space for indent which inserted to
top of folded line.
.RE
.TP 30
\fBindent_length\fR  <number>
16
.RS
Length of space for indent which inserted to top of folded line.
.RE
.TP 30
\fBsymhead_positive\fR  <string>
"Symbols"
.RS
Strings to output as heading letter for numbers and symbols
when lethead_flag or heading_flag is positive number.
.RE
.TP 30
\fBsymhead_negative\fR  <string>
"symbols"
.RS
Strings to output as heading letter for numbers and symbols
when lethead_flag or heading_flag is negative number.
.RE
.TP 30
\fBsymbol\fR  <string>
""
.RS
Strings to output as heading letter for numbers and symbols
when symbol_flag is non zero.
.RE
If specified, the option is prior to symhead_positive and symhead_negative.
(Extended by (up)mendex)
.RE
.TP 30
\fBsymbol_flag\fR  <number>
1
.RS
Flag to output of symbol. If \'0\', do not output.
(Extended by (up)mendex)
.RE
.TP 30
\fBletter_head\fR  <number>
1
.RS
Flag of heading letter for Japanese Kana.
If \'1\' and \'2\', Katakana and Hiragana is used, respectively.
(Extended by (up)mendex)
.RE
.TP 30
\fBpriority\fR  <number>
0
.RS
Flag of sorting method for index words composed of
Japanese and non-Japanese (ex. Latin scripts).
If non zero, one space (U+20) is inserted between
Japanese sequence and non-Japanese sequence in sorting procedure.
(Extended by (up)mendex)
.RE
.TP 30
\fBcharacter_order\fR  <string>
"SNLGCJKHDT"
.RS
Order of scripts and symbols.
\'S\', \'N\', \'L\', \'G\', \'C\', \'J\', \'K\', \'H\', \'D\' and \'T\' respectively
denotes symbol, number, Latin, Greek, Cyrillic, Japanese Kana, Korean Hangul, Hanja,
Devanagari and Thai script.
Please make sure that \'S\' and \'N\' are next to each other,
since \fBupmendex\fR considers numbers as a part of symbol.
(Extended by upmendex)
.RE
.TP 30
\fBicu_locale\fR  <string>
""
.RS
Locale in ICU collator.
By default, "root sort order" is set.
(Extended by upmendex)
.RE
.TP 30
\fBicu_rules\fR  <string>
""
.RS
Customized collation rules in ICU collator.
Unicode characters in UTF-8 encoding and following escape sequences are accepted:
\fB\\Uhhhhhhhh\fR (8-digit hexadecimal [0-9A-Fa-f]), \fB\\uhhhh\fR (4-digit hexadecimal),
\fB\\xhh\fR (2-digit hexadecimal), \fB\\x{h...}\fR (1..8-digit hexadecimal), and
\fB\\ooo\fR (3-digit octal [0-7]).
By default, locale is used.
(Extended by upmendex)
.RE
Ref. <http://userguide.icu-project.org/collation/customization>,
<https://unicode-org.github.io/icu/userguide/collation/customization/>,
<http://www.unicode.org/reports/tr35/tr35-collation.html#Rules>
.RE
.TP 30
\fBicu_attributes\fR  <string>
""
.RS
Attributes in ICU collator.
Followings are available:
"alternate:shifted", "alternate:non-ignorable",
"strength:primary", "strength:secondary", "strength:tertiary",
"strength:quaternary", "strength:identical",
"french-collation:on", "french-collation:off",
"case-first:off", "case-first:upper-first", "case-first:lower-first",
"case-level:on", "case-level:off",
"normalization-mode:on", "normalization-mode:off",
"numeric-ordering:on", "numeric-ordering:off"
(Extended by upmendex)
.RE
Ref. <http://userguide.icu-project.org/collation/customization>,
<https://unicode-org.github.io/icu/userguide/collation/customization/#default-options>,
<http://www.unicode.org/reports/tr35/tr35-collation.html#Setting_Options>
.RE
.PP
.SH ABOUT JAPANESE PROCESSING
.PP
\fIupmendex\fR has an additional feature to simplify the procedure of handling
Japanese indexes, compared to \fImakeindex\fR. Users can save the effort
of manually specifying a reading for every kanji word.
.RE
Japanese kanji words are usually sorted by the syllables of their readings
(\fI\'Yomi\'\fR), which can be represented by kana (Hiragana, Katakana) scripts.
\fIupmendex\fR accepts index words specified in kana expression directly on
an input file, and also accepts conversion from index words to kana scripts
by referring to Japanese dictionaries.
.RE

.LP
Examples of internal simplification of syllables are shown below.
.PP
.RS
.br
かぶしきがいしゃ		かふしきかいしや
.br
マッキントッシュ		まつきんとつしゆ
.br
ワープロ			わあふろ
.RE
.LP
The dictionary file consists of list with <\'index_word\' \'reading\'>.
The index word can be written in any scripts (kanji, kana, etc),
and the reading must be in Hiragana or Katakana scripts.
The delimiter between the index word and its reading is one or more tab(s) or space(s).
.RE
An example of a Japanese dictionary is shown below.
.PP
.RS
.br
漢字		かんじ
.br
読み		よみ
.br
環境		かんきょう
.br
α		アルファ
.RE
.LP
Here, each index word is allowed to have only one Yomi.
Though some kanji words (ex. 「表」) may have more than one Yomi\'s
(ex. 「ひょう」 and 「おもて」), only one of them can be registered in the dictionary.
When some different Yomi\'s are needed, they should be specified explicitly
in kana expression (ex. \\index{ひょう@表} or \\index{おもて@表}) on the input file.
.RE
Moreover, a dictionary file is automatically referred
by setting the file name at an environment variable \fIINDEXDEFAULTDICTIONARY\fR.
The dictionary set by the environment variable can be used
together with file(s) specified by \fI-d\fR option.
.PP
.SH ABOUT SORTING PROCEDURE
.PP
\fIupmendex\fR sorts indexes as is (\'sort by word order\') by default.
Setting \fI-l\fR option, spaces between words in an index are truncated prior to
sorting procedure (\'sort by character order\').
.RE
Even when sort by character order, the index at output remains the original sequence
without the truncation.
.RE
Follows show an example.
.PP
.RS
\fIsort by word order		sort by character order\fR
.br
X Window			Xlib
.br
Xlib				XView
.br
XView				X Window
.RE
.LP
In addition, two sorting methods can be applied for indexes
which contains both Japanese kana and other scripts (e.g. Latin script).
By setting \fIpriority\fR 0 (default) and 1 at a style file,
a space between Japanese Kana and other scripts is inserted and
not inserted respectively, prior to the sorting procedure.
.RE
Follows show an example.
.PP
.RS
\fIpriority=0			priority=1\fR
.br
index sort			indファイル
.br
indファイル			index sort
.RE
.PP
.SH ENVIRONMENT VARIABLES
\fIupmendex\fR refers environment variables as follows.
.PP
.TP 10
\fIINDEXSTYLE\fR
Directory where index style files exist.
.TP 10
\fIINDEXDEFAULTSTYLE\fR
Index style file to be referred to as default.
.TP 10
\fIINDEXDICTIONARY\fR
Directory where dictionary files exist.
.TP 10
\fIINDEXDEFAULTDICTIONARY\fR
Dictionary file which is automatically read.
.PP
.SH DETAIL
Detailed specification is compatible with \fImakeindex\fR.
.PP
.SH KNOWN ISSUES
When plural page number expression is used, \fI.idx\fR files should be
specified along with the order of page numbers. Otherwise,
wrong page numbers might be output.
.PP
.SH "SEE ALSO"
.BR tex(1),
.BR latex(1),
.BR makeindex(1),
.BR mendex(1).
.br
International Components for Unicode (ICU):
<http://site.icu-project.org/>,
<https://unicode-org.github.io/icu/>
.SH AUTHOR
This manual page was written by Takuji Tanaka
based on the mendex manual page written by Japanese \*(TX Development Community.