UPMENDEX(1)

📦
version 74401 · 7 versions
, in fedora 44, opensuse-leap 16.0

✨ UPMENDEX(1) ✨ — General Commands Manual 🎀

okay bestie, sit down, hydrate, because this one is a whole thing and it's lowkey iconic. it's upmendex, from the General Commands Manual, and she does a LOT. let's go 💅

🌸 NAME 🌸

upmendex — the multilingual index processor. that's her. that's the whole name. periodt.

🦋 SYNOPSIS 🦋

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

like, that's the vibe. options, then optionally a lil pile of index files. no cap.

💖 DESCRIPTION 💖

so. the program upmendex is a general purpose multilingual hierarchical index generator — she works with upLaTeX, XeLaTeX and LuaLaTeX. you hand her one or more input files (.idx files, which are often produced by a text formatter like the LaTeX families), she sorts all the entries, and she hands you back an output file that can be formatted. chef's kiss.

she supports Latin (including non-English), Greek, Cyrillic, Korean Hangul and Han (Hanzi ideographs) scripts, plus Japanese Kana. she is almost compatible with makeindex and mendex, and on top of that there's an extra feature for handling readings of kanji words. not me being multilingual AND humble 😭

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.

and the nesting? the index can have up to five levels (0, 1, 2, 3, and 4) of subitem nesting. five. she's deep like that. 🫶

🔥 OPTIONS 🔥

one bullet per flag, no skipping, we respect her fully:

  • -i — take input from stdin, even when index files are specified. like, yes, ignore those files, we're reading from the pipe now.
  • -l — set ´sort by character order´. by default, ´sort by word order´ is used. the details are described below.
  • -q — quiet mode; send no message to stderr, except error messages and warnings. she's chill but she WILL tell you if something's wrong.
  • -r — disable implicit page range formation. by default, three or more successive pages are automatically abbreviated as a range (e.g. 1–5).
  • -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.
  • -g — make the Japanese index head the A-line (A, Ka, Sa, ...; 10 characters) of the gojuon table (Japanese syllabary). by default, all 48 characters in the gojuon table are used.
  • -f — force to output characters even if the scripts are not supported by upmendex.
  • -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. tiny menu, big help.
  • -- — 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. (yes, ´%´, we see you.)

💜 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)
  • 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)
  • tumunja <string> — default "ㄱㄴㄷㄹㅁㅂㅅㅇㅈㅊㅋㅌㅍㅎ" — heading characters of Hangul specified by a string. (Deprecated, Extended by upmendex)
bestie, heads up: tumunja is deprecated. she's still here, but she's giving legacy energy. 🙈
  • 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 "
  • item_1 <string> — default "\n \\subitem "
  • item_2 <string> — default "\n \\subsubitem "
  • item_3 <string> — default "\n \\subsubsubitem "
  • item_4 <string> — default "\n \\subsubsubsubitem "

and the shared description for the whole item_0 through item_4 block: 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 "

and the shared description for the whole item_01 through item_34 block: command sequence inserted between primaly and secondary, secondary and tertiary, etc. level entries. (yes, "primaly". we are transcribing her exactly, typos and all, no edits 💅)

  • item_x1 <string> — default "\n \\subitem "
  • item_x2 <string> — default "\n \\subsubitem "
  • item_x3 <string> — default "\n \\subsubsubitem "
  • item_x4 <string> — default "\n \\subsubsubsubitem "

and the shared description for the whole item_x1 through item_x4 block: command sequence inserted between primary and secondary, secondary and tertiary, etc. level entries when the higher level entry does not have page number.

  • delim_0 <string> — default ", "
  • delim_1 <string> — default ", "

okay bestie, these next ones are the page-number delimiters — the little glue strings that sit between an entry and its page numbers 📎

  • delim_2 <string> — default ", "
  • delim_3 <string> — default ", "
  • delim_4 <string> — default ", ". This is the delimiter string that goes between the primary, secondary, etc. level entry and the first page number.
  • delim_n <string> — default ", ". The delimiter string between page numbers, the one commonly used for any entry level.
  • delim_r <string> — default "--". Delimiter string between pages when you're showing a page range.
  • delim_t <string> — default "". Delimiter string output at the end of the page number list.

now the suffix girlies ✨ these ones are conditional, so pay attention:

  • suffix_2p <string> — default "". String inserted in place of delim_n and the next page number when the two pages are contiguous. It works only when the parameter is defined.
  • suffix_3p <string> — default "". String inserted in place of delim_r and the third page number when the three pages are contiguous. This parameter is prior to suffix_mp. It 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. It works only when the parameter is defined.

encapsulation time, we're wrapping page numbers in commands like it's a gift 🎁

  • encap_prefix <string> — default "\\". Prefix for an encapsulating command, used when that encapsulating command gets added to the page number.
  • encap_infix <string> — default "{". Goes 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.

line-wrapping behaviour, aka when the vibes get too long 📏

  • line_max <number> — default 72. Maximum number of one line. If you exceed that number, the lines are folded.
  • indent_space <string> — default "". Space for the indent that gets inserted at the top of a folded line.
  • indent_length <number> — default 16. Length of the space for the indent that gets inserted at the top of a folded line.

heading letters for symbols, the glow-up section 👑

  • symhead_positive <string> — default "Symbols". Strings to 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". Strings to 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 the heading letter for symbols when symbol_flag is non zero. If it's specified, this option is prior to symhead_positive and symhead_negative. (Extended by (up)mendex)
  • numhead_positive <string> — default "Numbers". Strings to output as the 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". Strings to output as the 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:
    • ´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. ´1´ and ´2´ mean Katakana and Hiragana are used, respectively. (Extended by (up)mendex)
  • priority <number> — default 0. Flag of 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 during the sorting procedure. (Extended by (up)mendex)

script order, this one's the character_order moment 🌈

  • character_order <string> — default "SNLGCJKHDTah". Order of scripts and symbols. ´S´, ´N´, ´L´, ´G´, ´C´, ´J´, ´K´, ´H´, ´D´, ´T´, ´a´ and ´h´ respectively denote symbol, number, Latin, Greek, Cyrillic, Japanese Kana, Korean Hangul, Hanzi, Devanagari, Thai, Arabic and Hebrew script. ´@´ denotes scripts which are not explicitly designated, and their order is 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 blocks, so your output file gets a lil intro and outro 💖

  • script_preamble <string 1> <string 2> — default "". 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´, ´thai´, ´arabic´, or ´hebrew´. (Extended by upmendex)
  • script_postamble <string 1> <string 2> — default "". Postamble 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´, ´thai´, ´arabic´, or ´hebrew´. (Extended by upmendex)

and now the ICU collator section, aka the sorting sorcery 🧚

  • icu_locale <string> — default "". 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. Unicode characters in UTF-8 encoding and the following escape sequences are accepted: \Uhhhhhhhh (8-digit hexadecimal [0-9A-Fa-f]), \uhhhh (4-digit hexadecimal), \xhh (2-digit hexadecimal), \x{h...} (1..8-digit hexadecimal), and \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> — default "". Attributes in the ICU collator. These 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)

Ref. https://unicode-org.github.io/icu/userguide/collation/customization/#default-options, http://www.unicode.org/reports/tr35/tr35-collation.html#Setting_Options

🌸 ABOUT JAPANESE PROCESSING 🌸

okay so here's the tea, bestie: upmendex has an extra lil superpower that makes handling Japanese indexes SO much easier than makeindex ever was. 💖 You get to skip the whole "manually typing a reading for every single kanji word" grind. Like, nobody has time for that.

Japanese kanji words are usually sorted by the syllables of their readings (that's the ´Yomi´, iykyk), which can be written out in kana — Hiragana, Katakana, whichever. upmendex will straight up accept index words written in kana directly on an input file, AND it'll also convert index words that are in Kanji or symbols into phonogram scripts by consulting Japanese dictionaries. No cap. 👑

Examples of that internal syllable simplification, bestie:

        かぶしきがいしゃ         かふしきかいしや
        マッキントッシュ         まつきんとつしゆ
        ワープロ            わあふろ

Now, the dictionary file is literally just a list with <´index_word´ ´reading´>. The index word can be in ANY script (kanji, kana, whatever your heart desires), and the reading can be in any phonograms — Hiragana, Katakana, you name it. What separates the index word from its reading? One or more tab(s) or space(s). Simple as. ✨

Here's an example of a Japanese dictionary:

        漢字      かんじ
        読み      よみ
        環境      かんきょう
        ＄        ドル

⚠️ important: each index word is allowed only one Yomi. So yeah, some kanji words (like 「表」) might have more than one Yomi (like 「ひょう」 and 「おもて」), but only one of them can be registered in the dictionary. When you need different Yomi's, you have to specify them explicitly in kana expression on the input file, like \index{ひょう@表} or \index{おもて@表}. That's the move. 💅

AND — plot twist — a dictionary file gets automatically referred to by setting the file name at an environment variable called INDEXDEFAULTDICTIONARY. And get this: the dictionary set by that environment variable can be used together with file(s) you specify with the -d option. They vibe together. 🫶

🦋 ABOUT SORTING PROCEDURE 🦋

So upmendex sorts indexes as is by default — that's the ´sort by word order´ life. But if you set the -l option, spaces between words in an index get truncated before the sorting happens, and that's called ´sort by character order´.

And listen — even when you're doing sort by character order, the index in the output stays in its original sequence, no truncation. The sort is just for sorting, bestie, it's not gonna mess with your output. 😌

Here's an example so it clicks:

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

On top of that, there are two sorting methods you can apply to indexes that contain BOTH Japanese kana and other scripts (Latin script, for example). By setting priority 0 (that's the default) and 1 at a style file, a space between Japanese Kana and other scripts gets inserted, or not inserted, respectively — before the sorting procedure kicks in.

Example time:

        priority=0               priority=1
        index sort               indファイル
        indファイル              index sort

🌈 ENVIRONMENT VARIABLES 🌈

upmendex refers to environment variables like this, bestie:

  • INDEXSTYLE — the directory where index style files live. 📁
  • INDEXDEFAULTSTYLE — the index style file that gets referred to as the default.
  • INDEXDICTIONARY — the directory where dictionary files live. 📚
  • INDEXDEFAULTDICTIONARY — the dictionary file that gets automatically read.

⭐ DETAIL ⭐

The detailed specification is compatible with makeindex. periodt. 💯

💀 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. 😭 not a vibe. be careful, bestie.

👑 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 icons, honestly. 🎀

and that's the whole UPMENDEX(1) page, bestie — the source is this very manual page, version UPMENDEX(1), dated as shown in the footer. tysm for reading, go forth and sort your indexes, you're gonna ate this. ✨🦋💅🌸

📦 where this page comes from