UPMENDEX(1)

๐Ÿ“ฆ version 2026.0, in alpine 3.24

๐Ÿ’– upmendex(1) โ€” General Commands Manual ๐Ÿ’–

โœจ NAME โœจ

upmendex โ€” the multilingual index processor, bestie. Thatโ€™s literally the whole name, and honestly? Iconic.

๐ŸŒˆ SYNOPSIS ๐ŸŒˆ

upmendex [-ilqrcgf] [-s sty] [-d dic] [-o ind] [-t log] [-p no] [--] [
       idx0 idx1 idx2 ...]
upmendex --help
upmendex --version

๐Ÿฆ‹ DESCRIPTION ๐Ÿฆ‹

Okay so upmendex is a general purpose multilingual hierarchical index generator, and it works with upLaTeX, XeLaTeX, and LuaLaTeX. It accepts one or more input files (.idx; often produced by a text formatter such as LaTeX families), sorts the entries, and produces an output file which can be formatted. Main character energy, fr fr.

It supports Latin (including non-English), Greek, Cyrillic, Korean Hangul, and Han (Hanzi ideographs) scripts, as well as Japanese Kana. Sheโ€™s multilingual and she ate.

It also experimentally supports Brahmic scripts โ€” Bengali, Devanagari, Gurmukhi, Gujarati, Kannada, Lao, Malayalam, Oriya, Sinhala, Tamil, Telugu, Thai โ€” plus Arabic and Hebrew scripts. Experimental means experimental, bestie; donโ€™t act surprised if itโ€™s giving โ€œweโ€™re still testing.โ€

It is almost compatible with makeindex and mendex, and an additional feature for handling readings of kanji words is also available. 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. The index can have up to five levels (0, 1, 2, 3, and 4) of subitem nesting. Five levels. Thatโ€™s not a drill.

๐Ÿ’… OPTIONS ๐Ÿ’…

  • -i โ€” take input from stdin, even when index files are specified. Yes, she can read from the group chat directly.
  • -l โ€” set sort by character order. By default, sort by word order is used. Details are described below. Iykyk.
  • -q โ€” quiet mode: send no message to stderr, except error messages and warnings. Lowkey the โ€œplease stop yellingโ€ flag.
  • -r โ€” disable implicit page range formation. By default, three or more successive pages are automatically abbreviated as a range (e.g. 1โ€“5). So -r is the โ€œleave my pages aloneโ€ option.
  • -c โ€” 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. Tiny cleanup, huge slay.
  • -g โ€” make Japanese index head A-line (A, Ka, Sa, ...; 10 characters) of the gojuon table (Japanese syllabary). By default, all 48 characters in the gojuon table are used. Periodt.
  • -f โ€” force to output characters even if the scripts are not supported by upmendex. Bold. Chaotic. Use with intention.
  • -s sty โ€” employ sty as the style file.
  • -d dic โ€” employ dic as the dictionary file. The dictionary file is composed of lists of <index_word reading>.
  • -o ind โ€” employ ind as the output index file. By default, the file name is created by appending the extension ind to the base name of the first input file.
  • -t log โ€” employ log as the transcript file. By default, the file name is created by appending the extension ilg to the base name of the first input file.
  • -p no โ€” set the starting page number of the output index list to be no. The argument no may be numerical or one of the following: any (the next page to the end of contents), odd (the next odd page to the end of contents), even (the next even page to the end of contents).
  • --help โ€” show summary of options and exit.
  • --version โ€” show version information and exit.
  • -- โ€” arguments after -- are not taken as options. This is useful when the input file name starts with -.

๐ŸŽ€ STYLE FILE ๐ŸŽ€

The style file informs upmendex about the format of the idx input files and the intended format of the final output file. The format is upper compatible with the one for makeindex and mendex. The style file contains a list of <specifier attribute> 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.

๐ŸŒธ Input file style parameter ๐ŸŒธ

  • keyword <string> โ€” default: "\\indexentry". Command with an argument of index entry which is going to be processed.
  • arg_open <char> โ€” default: {. Opening delimiter which shows the beginning of index entry.
  • arg_close <char> โ€” default: }. Closing delimiter which shows the end of index entry.
  • range_open <char> โ€” default: (. Opening delimiter which shows the beginning of page range.
  • range_close <char> โ€” default: ). Closing delimiter which shows the end of page range.
  • level <char> โ€” default: !. Delimiter which shows lower level.
  • actual <char> โ€” default: @. Symbol which shows the next sequence is to appear as index strings in the output file.
  • encap <char> โ€” default: |. Symbol which shows the next sequence is to be used as command name attached to the page number.
  • page_compositor <string> โ€” default: "-". Separator between page levels for a style with multi-levels of page numbers.
  • page_precedence <string> โ€” default: "rnaRA". Priority of expression for page number. R and r correspond to Roman. n corresponds to arabic numeral. A and a correspond to Latin alphabet.
  • quote <char> โ€” default: ". Escape character for upmendex parameters.
  • escape <char> โ€” default: \\. Escape character for general scripts.

๐ŸŒŸ Output file style parameter ๐ŸŒŸ

  • preamble <string> โ€” default: "\\begin{theindex}\n". Preamble of output file.
  • postamble <string> โ€” default: "\n\n\\end{theindex}\n". Postamble of output file.
  • setpage_prefix <string> โ€” default: "\n \\setcounter{page}{". Prefix of page number if start page is designated.
  • setpage_suffix <string> โ€” default: "}\n". Suffix of page number if start page is designated.
  • group_skip <string> โ€” default: "\n\n \\indexspace\n". Strings to insert vertical space before new section of index.
  • lethead_prefix <string> โ€” default: "". Prefix of heading for newly appeared heading letter.
  • heading_prefix <string> โ€” default: "". Same as lethead_prefix. (compatible with makeindex)
  • lethead_suffix <string> โ€” default: "". Suffix of heading for newly appeared heading letter.
  • heading_suffix <string> โ€” default: "". Same as lethead_suffix. (compatible with makeindex)
  • lethead_flag <number> โ€” default: 0. 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.
  • heading_flag <number> โ€” default: 0. Same as lethead_flag. (Note: makeindex uses a different name headings_flag)
  • headings_flag <number> โ€” default: 0. Same as lethead_flag. (compatible with makeindex)
  • script_head <string 1> <string 2> โ€” default: "(standard heading characters)". Heading characters of script specified by string 2. One of script names must be specified in string 1: kana, hangul, hanzi, devanagari, bengali, gurmukhi, gujarati, oriya, tamil, telugu, kannada, malayalam, sinhala, thai, or lao. (Extended by upmendex)
  • kana_head <string> โ€” default: "". Heading characters of Kana specified by a string. By default, it is controlled by letter_head and command line option -g. (Extended by upmendex)
  • hangul_head <string> โ€” default: "ใ„ฑใ„ดใ„ทใ„นใ…ใ…‚ใ……ใ…‡ใ…ˆใ…Šใ…‹ใ…Œใ…ใ…Ž". Heading characters of Hangul specified by a string. (Extended by upmendex)
  • hanzi_head <string> โ€” default: "". Heading strings of hanzi (Kanji, Hanja) specified by a string, which is concatenated of items with a separator ;. (Extended by upmendex)
  • devanagari_head <string> โ€” default: "เค„เค…เค†เค‡เคˆเค‰เคŠเค‹เคŒเคเคŽเคเคเค‘เค’เค“เค”เค•เค–เค—เค˜เค™เคšเค›เคœเคเคžเคŸเค เคกเคขเคฃเคคเคฅเคฆเคงเคจเคชเคซเคฌเคญเคฎเคฏเคฐเคฒเคณเคตเคถเคทเคธเคน". Heading characters of Devanagari specified by a string. (Experimental, Extended by upmendex)
  • thai_head <string> โ€” default: "เธเธ‚เธƒเธ„เธ…เธ†เธ‡เธˆเธ‰เธŠเธ‹เธŒเธเธŽเธเธเธ‘เธ’เธ“เธ”เธ•เธ–เธ—เธ˜เธ™เธšเธ›เธœเธเธžเธŸเธ เธกเธขเธฃเธคเธฅเธฆเธงเธจเธฉเธชเธซเธฌเธญเธฎ". Heading characters of Thai script specified by a string. (Experimental, Extended by upmendex)
  • item_0 <string> โ€” default: "\n \\item ". Command sequence inserted between two primary, two secondary, etc. level entries.
  • item_1 <string> โ€” default: "\n \\subitem ". Command sequence inserted between two primary, two secondary, etc. level entries.
  • item_2 <string> โ€” default: "\n \\subsubitem ". Command sequence inserted between two primary, two secondary, etc. level entries.
  • item_3 <string> โ€” default: "\n \\subsubsubitem ". Command sequence inserted between two primary, two secondary, etc. level entries.
  • item_4 <string> โ€” default: "\n \\subsubsubsubitem ". Command sequence inserted between two primary, two secondary, etc. level entries.
  • item_01 <string> โ€” default: "\n \\subitem ".
  • item_12 <string> โ€” default: "\n \\subsubitem ".
  • item_23 <string> โ€” default: "\n \\subsubsubitem ".
  • item_34 <string> โ€” default "\n \\subsubsubsubitem " ๐ŸŒธ this is the command sequence that gets slipped in between primary and secondary level entries, secondary and tertiary, etc. Bestie, it goes between the levels, not before them, okay?
  • item_x1 <string> โ€” default "\n \\subitem "
  • item_x2 <string> โ€” default "\n \\subsubitem "
  • item_x3 <string> โ€” default "\n \\subsubsubitem "
  • item_x4 <string> โ€” default "\n \\subsubsubsubitem "

So like, item_x1 through item_x4 are also command sequences inserted between primary and secondary, secondary and tertiary, etc. level entries โ€” but only when the higher level entry has no page number. That's the whole difference, iykyk ๐Ÿ’…

  • delim_0 <string> โ€” default ", "
  • delim_1 <string> โ€” default ", "
  • delim_2 <string> โ€” default ", "
  • delim_3 <string> โ€” default ", "
  • delim_4 <string> โ€” default ", "

These cuties are the delimiter string that sits between the primary, secondary, etc. level entry and the first page number โœจ (delim_0 for level 0, delim_1 for level 1 โ€” you get the vibe).

  • delim_n <string> โ€” default ", " โ€” the delimiter string between page numbers, commonly used for any entry level. One setting, all the levels, highkey efficient ๐Ÿซถ
  • delim_r <string> โ€” default "--" โ€” the delimiter string between pages when you're showing a page range. Dash dash, iconic.
  • delim_t <string> โ€” default "" โ€” the delimiter string output at the end of the page number list. The little send-off ๐ŸŽ€
  • suffix_2p <string> โ€” default "" โ€” string inserted in place of delim_n and the next page number when the two pages are contiguous. Works only when the parameter is defined โ€” define it or it does nothing, no cap ๐Ÿ™ˆ
  • suffix_3p <string> โ€” default "" โ€” string inserted in place of delim_r and the third page number when the three pages are contiguous. Heads up: this parameter is prior to suffix_mp (it takes priority, bestie). And again โ€” works only when the parameter is defined.
  • suffix_mp <string> โ€” default "" โ€” string inserted in place of delim_r and the last page number when three or more pages are contiguous. Also only works when defined, fr fr.
  • encap_prefix <string> โ€” default "\\" โ€” the prefix for an encapsulating command, used when that encapsulating command gets added to the page number.
  • encap_infix <string> โ€” default "{" โ€” sits just before the page number when the encapsulating command is added to the page number.
  • encap_suffix <string> โ€” default "}" โ€” comes after the page number when the encapsulating command is added to the page number.

okay the next batch is all the layout + heading behavior, stay with me ๐ŸŒˆ

  • line_max <number> โ€” default 72 โ€” maximum number of one line. If you exceed the number, the lines get folded. Respect the limit ๐Ÿ’€
  • indent_space <string> โ€” default "" โ€” the space for indent that gets inserted to the top of a folded line.
  • indent_length <number> โ€” default 16 โ€” the length of space for indent inserted to the top of a folded line.
  • symhead_positive <string> โ€” default "Symbols" โ€” string output as the heading letter for symbols when lethead_flag or heading_flag or headings_flag is a positive number.
  • symhead_negative <string> โ€” default "symbols" โ€” string output as the heading letter for symbols when lethead_flag or heading_flag or headings_flag is a negative number.
  • symbol <string> โ€” default "" โ€” strings to output as heading letter for symbols when symbol_flag is non zero. If specified, this option is prior to symhead_positive and symhead_negative. (Extended by (up)mendex) โœจ
  • numhead_positive <string> โ€” default "Numbers" โ€” string output as heading letter for numbers when lethead_flag or heading_flag or headings_flag is a positive number and symbol_flag is 2.
  • numhead_negative <string> โ€” default "numbers" โ€” string output as heading letter for numbers when lethead_flag or heading_flag or headings_flag is a negative number and symbol_flag is 2.
  • symbol_flag <number> โ€” default 1 โ€” flag for symbol output, and babes there are three modes:
    • 0 โ†’ do not output headings for symbols and numbers
    • 1 โ†’ output symbols and numbers as a group of symbols
    • 2 โ†’ output symbols and numbers separately

(Extended by (up)mendex)

  • letter_head <number> โ€” default 1 โ€” flag of heading letter for Japanese Kana. If 1, Katakana is used; if 2, Hiragana is used. (Extended by (up)mendex) ๐Ÿฆ‹
  • priority <number> โ€” default 0 โ€” flag for the sorting method for index words composed of Japanese and non-Japanese (ex. Latin scripts). If non zero, one space (U+0020) is inserted between the Japanese sequence and the non-Japanese sequence in the sorting procedure. (Extended by (up)mendex)
  • character_order <string> โ€” default "SNLGCJKHDbpgotukmsTlah" โ€” this is the order of scripts and symbols, and each letter means something, so let me lay it out for you ๐Ÿ‘‘:
    • S โ†’ symbol
    • N โ†’ number
    • L โ†’ Latin
    • G โ†’ Greek
    • C โ†’ Cyrillic
    • J โ†’ Japanese Kana
    • K โ†’ Korean Hangul
    • H โ†’ Hanzi
    • D โ†’ Devanagari
    • b โ†’ Bengali
    • p โ†’ Gurmukhi
    • g โ†’ Gujarati
    • o โ†’ Oriya
    • t โ†’ Tamil
    • u โ†’ Telugu
    • k โ†’ Kannada
    • m โ†’ Malayalam
    • s โ†’ Sinhala
    • T โ†’ Thai
    • l โ†’ Lao
    • a โ†’ Arabic
    • h โ†’ Hebrew script

And @ denotes scripts which are not explicitly designated โ€” those get their order configured by icu_rules or icu_locale. โš ๏ธ Please make sure that S and N are next to each other if symbol_flag=1, since numbers are classified as a part of symbol. (Extended by upmendex)

  • script_preamble <string 1> <string 2> โ€” default "" โ€” the preamble of a script block in the output file, specified by string 2. One of the script names must be specified in string 1: latin, cyrillic, greek, kana, hangul, hanzi, devanagari, bengali, gurmukhi, gujarati, oriya, tamil, telugu, kannada, malayalam, sinhala, thai, lao, arabic, or hebrew. (Extended by upmendex) ๐Ÿงš
  • script_postamble <string 1> <string 2> โ€” default "" โ€” the postamble of a script block in the output file, specified by string 2. Same deal, one of these script names has to go in string 1: latin, cyrillic, greek, kana, hangul, hanzi, devanagari, bengali, gurmukhi, gujarati, oriya, tamil, telugu, kannada, malayalam, sinhala, thai, lao, arabic, or hebrew. (Extended by upmendex) ๐Ÿงš
  • icu_locale <string> โ€” default "" โ€” the locale in the ICU collator. By default, "root sort order" is set. (Extended by upmendex)
  • icu_rules <string> โ€” default "" โ€” customized collation rules in the ICU collator. It accepts Unicode characters in UTF-8 encoding plus these escape sequences, bestie, memorize the list ๐Ÿ“:
    • \Uhhhhhhhh โ†’ 8-digit hexadecimal [0-9A-Fa-f]
    • \uhhhh โ†’ 4-digit hexadecimal
    • \xhh โ†’ 2-digit hexadecimal
    • \x{h...} โ†’ 1..8-digit hexadecimal
    • \ooo โ†’ 3-digit octal [0-7]

If icu_rules and icu_locale are simultaneously specified, the collation rules specified by icu_rules are added on the collation rules specified by icu_locale. By default, locale is used. (Extended by upmendex)

Ref. https://unicode-org.github.io/icu/userguide/collation/customization/, http://www.unicode.org/reports/tr35/tr35-collation.html#Rules ๐Ÿฆ‹

  • icu_attributes <string> โ€” defaults to "". These are the attributes for the ICU collator, and here's the whole menu of them, no gatekeeping: "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" โ€” and yeah, this one's Extended by upmendex ๐Ÿ’…

Refs if you wanna go deeper, bestie: <https://unicode-org.github.io/icu/userguide/collation/customization/#default-options> and <http://www.unicode.org/reports/tr35/tr35-collation.html#Setting_Options>

๐ŸŒธ ABOUT JAPANESE PROCESSING ๐ŸŒธ

okay so this is the part where upmendex is lowkey showing off, and honestly? deserved. Compared to makeindex, upmendex has an additional feature that simplifies the whole procedure of handling Japanese indexes. The serve here is that users can save the effort of manually specifying a reading for every single kanji word ๐Ÿ˜ญ like, the tedium? gone.

Japanese kanji words are usually sorted by the syllables of their readings (Yomi), which can be represented by kana (Hiragana, Katakana) scripts. So upmendex accepts index words specified in kana expression directly on an input file โ€” and it also accepts conversion from index words in Kanji or symbols to phonogram scripts by referring to Japanese dictionaries. it's giving multilingual icon behavior โœจ

Examples of internal simplification of syllables are shown below โ€” watch the glow-up:

ใ‹ใถใ—ใใŒใ„ใ—ใ‚ƒ         ใ‹ใตใ—ใใ‹ใ„ใ—ใ‚„
ใƒžใƒƒใ‚ญใƒณใƒˆใƒƒใ‚ทใƒฅ         ใพใคใใ‚“ใจใคใ—ใ‚†
ใƒฏใƒผใƒ—ใƒญ            ใ‚ใ‚ใตใ‚

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 can be in any phonograms such as Hiragana or Katakana scripts. The delimiter between the index word and its reading is one or more tab(s) or space(s). yes bestie, tabs OR spaces, the dictionary is not a hater ๐Ÿซถ

An example of a Japanese dictionary is shown below:

ๆผขๅญ—      ใ‹ใ‚“ใ˜
่ชญใฟ      ใ‚ˆใฟ
็’ฐๅขƒ      ใ‹ใ‚“ใใ‚‡ใ†
๏ผ„        ใƒ‰ใƒซ

Here, each index word is allowed to have only one Yomi. And I know what you're thinking, so let me say it plainly: 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. periodt ๐Ÿ’…

Moreover, a dictionary file is automatically referred by setting the file name at an environment variable INDEXDEFAULTDICTIONARY. The dictionary set by the environment variable can be used together with file(s) specified by -d option. so they co-exist, they're not fighting, it's a collab ๐Ÿค

โญ ABOUT SORTING PROCEDURE โญ

upmendex sorts indexes as is (sort by word order) by default. Setting -l option, spaces between words in an index are truncated prior to sorting procedure (sort by character order). And before you panic โ€” even when sort by character order, the index at output remains the original sequence without the truncation. the sort is just for ordering purposes, the output stays cute and untouched ๐Ÿ’–

Follows show an example:

sort by word order       sort by character order
X Window            Xlib
Xlib                XView
XView                    X Window

In addition, two sorting methods can be applied for indexes which contains both Japanese kana and other scripts (e.g. Latin script). By setting priority 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.

Follows show an example:

priority=0               priority=1
index sort               indใƒ•ใ‚กใ‚คใƒซ
indใƒ•ใ‚กใ‚คใƒซ              index sort

see how they just swapped places? iconic. no cap ๐Ÿฆ‹

๐ŸŒˆ ENVIRONMENT VARIABLES ๐ŸŒˆ

upmendex refers environment variables as follows โ€” the whole guest list:

  • INDEXSTYLE โ€” Directory where index style files exist.
  • INDEXDEFAULTSTYLE โ€” Index style file to be referred to as default.
  • INDEXDICTIONARY โ€” Directory where dictionary files exist.
  • INDEXDEFAULTDICTIONARY โ€” Dictionary file which is automatically read.

๐Ÿ’œ DETAIL ๐Ÿ’œ

Detailed specification is compatible with makeindex. that's it, that's the whole vibe check โ€” if you know makeindex, you already know โœจ

๐Ÿ’€ KNOWN ISSUES ๐Ÿ’€

When plural page number expression is used, .idx files should be specified along with the order of page numbers. Otherwise, wrong page numbers might be output.

fr fr, read that twice. the order of the .idx files actually matters here, and if you get it wrong the page numbers come out wrong. not a drill ๐Ÿ˜ญ

๐ŸŽ€ SEE ALSO ๐ŸŽ€

tex(1), latex(1), makeindex(1), mendex(1).

International Components for Unicode (ICU): <http://icu.unicode.org/>, <https://unicode-org.github.io/icu/>

๐Ÿ‘‘ AUTHOR ๐Ÿ‘‘

This manual page was written by Takuji Tanaka based on the mendex manual page written by Japanese TeX Development Community. absolute legends, all of them ๐Ÿซถ

and that's the whole page, bestie โ€” nothing skipped, nothing summarised, every last detail is in there ๐Ÿ’– the footer at the very bottom is just the page's own name-and-section doing its little cameo, UPMENDEX(1), hanging out in the version-and-date slot like the main character it is. go sort something. slay ๐ŸŒŸ

๐Ÿ“ฆ where this page comes from