%% $Id: xindex-doc.tex 22 2022-02-07 12:18:15Z hvoss $
%
\listfiles\setcounter{errorcontextlines}{100}
\documentclass[paper=a4,fontsize=11pt,DIV=14,parskip=half-,
               captions=tableabove,twoside=on]{scrartcl}
\usepackage{fontspec}
%\usepackage{libertinus-otf}
\setmainfont{AccanthisADFStdNo3}[
  UprightFont   =*-Regular,
  BoldFont      =*-Bold,
  ItalicFont    =*-Italic,
  BoldItalicFont=*-BoldItalic,
  RawFeature    = -rlig,
]
\setsansfont{GilliusADF}[
  UprightFont   =*-Regular,
  BoldFont      =*-Bold,
  ItalicFont    =*-Italic,
  BoldItalicFont=*-BoldItalic,
  RawFeature    = -rlig,
]
\setmonofont{DejaVu Sans Mono}[Scale=MatchLowercase,FakeStretch=0.9]
\newfontfamily\DejaVuMono[Scale=MatchLowercase,FakeStretch=0.9]{DejaVu Sans Mono}
%\setmonofont{Anonymous Pro}[Scale=MatchLowercase,FakeStretch=0.9]

\newfontfamily\Japanese[Scale=MatchUppercase]{SourceHanSans}
\newfontfamily\CODE{CODE2000}

\usepackage[english]{babel}
\usepackage{scrlayer-scrpage}
\automark[section]{section}
\automark*[subsection]{}
\pagestyle{scrheadings}

{\catcode`\%=12 
 \gdef\perCent{%}
 \gdef\DoubleperCent{%%}
}

\usepackage{xcolor,fancyvrb,varioref,awesomebox}
\usepackage{xltabular}
\usepackage{hvlogos} % for Wikipedia W
\usepackage{listings}
\usepackage{hvextern}
\lstset{basicstyle=\ttfamily\small,language=[LaTeX]TeX}
\usepackage{ragged2e}
\usepackage{makeidx}\makeindex
\usepackage{hvindex}
\def\Lfile#1{\texttt{#1}\index{#1 file@\texttt{#1} file}}
\def\Lext#1{\texttt{.#1}\index{#1 file extension@\texttt{.#1} file extension}}
\def\Lcs#1{\texttt{\textbackslash#1}\index{#1@\texttt{\textbackslash#1}}}
\def\Lenv#1{\texttt{#1}\index{#1 environment@\texttt{#1} environment}}
\def\Lpack#1{\texttt{#1}\index{#1 package@\texttt{#1} package}}
\def\Lprog#1{\texttt{#1}\index{#1 program@\texttt{#1} program}}
\def\Loption#1{\texttt{#1}\index{#1@\texttt{#1} package option}}
\def\Largb#1{\emph{\{#1\}}}

%\usepackage[bibstyle=dtk]{biblatex}
%\addbibresource{\jobname.bib}

\raggedbottom
\usepackage{url}
\usepackage[colorlinks,linktocpage]{hyperref}

\makeatletter% from: doc.sty
\newcommand*\GetFileInfo[1]{%
  \def\filename{#1}%
  \def\@tempb##1 ##2 ##3\relax##4\relax{%
    \def\filedate{##1}%
    \def\fileversion{##2}%
    \def\fileinfo{##3}}%
  \edef\@tempa{\csname ver@#1\endcsname}%
  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
\makeatother

%\GetFileInfo{xltabular.sty}
\usepackage{xspace}

\newcommand\XI{\texttt{xindex}\xspace}

\def\setVersion#1{\setVVersion#1!!}
\def\setVVersion#1=#2!!{\def\xIndexVersion{#2}} 

\setVersion{version = 0.64}%  can be automatically changed by perl



\title{Program and package \texttt{xindex} \\--\\ \normalsize \xIndexVersion\ (\today)}
\author{\shortstack{Herbert Voß\\\small \href{mailto:hvoss@tug.org}{hvoss@tug.org}}}
\date{}
\begin{document}
\maketitle
\thispagestyle{empty}
%\enlargethispage{1cm}
\tableofcontents

\begin{noteblock}
\raggedright
Thanks to: \\
Mark Baudoin;
Denis Bitouzé;
Andreas Deininger;
Brian Dunn;
Daniel Flipo;
Michal Hoftich;
Dohyun Kim;
Mykel Kochenderfer;
Alexey Kuznetsov;
Frank Mittelbach;
Peter Müller;
Heiko Oberdiek;
Matteo Paolini;
Stefan Pinnow;
Florent Rougon;
Gonzalo Pesquero Serrano;
Martin Sievers;
Simon Spiegel;
Jürgen Spitzmüller;
\end{noteblock}
\clearpage

\section{Introduction}
The Lua program
\XI is a  \Index{unicode} aware program for creating an index (\Lext{ind}) file from an \Lext{idx} source
file. It is completely compatible to the current \Lprog{makeindex} program, but can handle
\Index{UTF-8}, 16, 32, and 64. The \LaTeX\ package \Lpack{xindex} is a package which provides
a \LaTeX\ command which writes additional text into the index file. This text (comments and/or macros)
will be accepted by the program \XI.

The general structure of a \Index{data element} in the Lua table is:

\begin{verbatim}
data = { Entry = <text>,  -- like the input line without command \indexentry
         pages = {
                    { number  = <roman/arabic number or text>,
                      special = <macro> },  -- the part after | in the input
                    [...]
                    { number  = <roman/arabic number or text>,
                      special = <macro> }
                  },
          sortChar = <unicode codepoint>, -- of the first character of Entry
          Macro    = <TeX macro>  -- only useful with LaTeX package xindex
        }
\end{verbatim}

After reading the input file the Lua table \texttt{pages} has only one element for the number\index{page number}
and the so-called special command. When the pages are compressed the table will collect all pages which
refer to the same \Index{entry name}.
 

\iffalse
EntryList[2] = { 
      Entry   = "Johann",   -- the index item  foo@bar 
      pages   = {           -- the page number(s) and the part after |
        { number  = 111,
          special = '\\emph'  },
        { number  = 11,
          special = "\\textit"}
      },  
      sortChar= 80, -- Initial for later output
      Macro   = ""
}

\fi



\subsection{Syntax}

The \Index{syntax} is \verb|xindex [...] <file(s)>| where \verb|[...]|  are optional \Index{argument}s, either in short or
long form which, of course, can be mixed:

\begin{verbatim}
xindex
    [-q,--quiet ]
    [-h,--help ]
    [-v ]                                 verbose
    [-V,--version ]
    [-a,--no_casesensitive ]              default is false
    [-b,--no_labels ]                     default is false
    [-c,--config ]                        default is cfg
    [-e,--escapechar ]                    default is " 
    [-f,--fix_hyperref ]                  default is false
    [-g,--no_pagenumber]                  default is false
    [-i,--ignoreSpace ]                   default is false
    [-k,--checklang ]                     default ist false 
    [-l,--language ]                      default is en 
    [-n,--noheadings ]                    default is false
    [-o,--output ]                        default is <input>.ind
    [-p,--prefix]                         default L
    [-s,--use_stdin ]                     default is false
    [-x,--no_UCA ]                        default is false    
    <files...> (default stdin) file(s)[.idx]   one or more files
\end{verbatim}

For example:

\begin{noteblock}
\ttfamily
xindex -q -l fr -b myDoc \newline
xindex -l de -c DIN2 demo1 demo2  demo3\newline
xindex -c norsk -o index.ind demo1 demo2.bdx  demo3.adx
\end{noteblock}



\begin{enumerate}
\item \texttt{-q}: quiet; \texttt{-l fr}: french language setting; \texttt{-b}: no labels; \texttt{myDoc}: 
    input data \texttt{myDoc} or \texttt{myDoc.idx}\newline
	output data will be \texttt{myDoc.ind} and logfile \texttt{myDoc.ilg}
\item \texttt{-l de}: German language setting; \texttt{-c DIN2}: 
    config file \texttt{xindex-DIN2.lua}; \texttt{demo1 demo2 demo3}: 
    input data files with or without
	extension \texttt{.idx} \newline
	output data will be \texttt{demo1.ind} and logfile \texttt{xindex.ilg}
\item \texttt{-c norsk}: config file \texttt{xindex-norsk.lua}; \texttt{-o index.ind}: output file; 
   \texttt{demo1 demo2.bdx demo3.adx}: input data files with or without
	extension \texttt{.idx} \newline
	output data will be \texttt{xindex.ind} and logfile \texttt{xindex.ilg}
\end{enumerate}

It is also possible to use standard input for the index data, which needs the \verb|-s| parameter: 

\begin{noteblock}\ttfamily
cat myDoc.idx | xindex -q -l fr -b -s 
xindex -l de -c DIN2 < myDoc.idx
\end{noteblock}



\begin{importantblock}
The \Index{language} has to be chosen as an international abbreviation in 
lower- or uppercase letters, see 
\url{https://en.wikipedia.org/wiki/ISO_3166-2}
\end{importantblock}

\subsection{How it works}
\XI creates by default an \Index{output} file \texttt{<input>.ind} which can be read
by the \LaTeX\ document with the default command \Lcs{printindex}. One can use another
output filename, which makes only sense if one doesn't use the \Lcs{printindex} command
for typesetting the index.
The default \Index{sorting}
is given by the configuration file, which defines replacements for \Index{accented characters},
like \texttt{ö}$\rightarrow$\texttt{o}.

\subsection{The \texttt{.idx} file}
There are three (four) characters which must be escaped if used in the command \Lcs{index}:
\verb=!=, \verb=@=, or \verb=|= and the current escape character itself.  
These characters have a special meaning for 
the index.\index{"!}\index{"@}\index{"|} 

\begin{importantblock}
The default \Index{escape character} is the double quote \verb|"|. The braces
\texttt{\{} and \texttt{\}} cannot be used as argument for the command \Lcs{index}.
Use \Lcs{braceLeft} and \Lcs{braceRight} instead (defined in the package \Lpack{xindex}).
\end{importantblock}

\iffalse
To put a !\index{"!}, @\index{"@}, or |\index{"|} character in an index entry, 
quote it by preceding the
character with a quote ". More precisely, any character is said to be quoted if it
follows an unquoted " that is not part of a \" command. A quoted !, @, or
| character is treated like an ordinary character rather than having its usual
meaning. The " preceding a quoted character is deleted before the entries
are alphabetized.
\fi


\setkeys{hv}{moveToExampleDir=true,ExampleDir=Examples,cleanup={},verbose,force=false,shellesc}


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1,2},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l fr, 
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\usepackage{multicol}
\makeatletter
\renewenvironment{theindex}{%    only for demonstration
  \begin{multicols}{2}[\section*{\indexname}]
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\usepackage{xindex}% for \braceLeft|Right
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\section{Escaping characters}
\begin{itemize}
\item Exclamation mark ! \index{Exclamation ("!)}\index{"!}
\item Vertical bar | \index{Vertical bar ("|)}\index{"|}
\item Doublequote \verb|"| \index{""}
\item Double doublequote \verb|""| \index{""""}
\item At character @ \index{At ("@)}\index{"@}
\item Left parenthesis \{ \index{\braceLeft}
\item Right parenthesis \}  \index{\braceRight}
\end{itemize}
run \texttt{xindex -l fr <file.idx>}\index{file.idx@\texttt{<file.idx>}|textit}\index{123}
\index{Etage} \index{Ètagé}
\twocolumn
\printindex
\end{document}
\end{externalDocument}

It is by design that the braces \{ and \} cannot be used as index entry. The \emph{package}
xindex defines the two commands \Lcs{braceLeft} and \Lcs{braceRight} which can be used instead
(see examples above and and below).

The same example without using unicode sorting (option \Loption{-x}):


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1,2},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-x,  % do not use unicode
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
%! xindex  (no unicode sort -- simple ascii)
\documentclass{scrartcl}
\usepackage{multicol}
\makeatletter
\renewenvironment{theindex}{%    only for demonstration
  \begin{multicols}{2}[\section*{\indexname}]
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\usepackage{xindex}% for \braceLeft|\braceRight
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\section{Escaping characters}
\begin{itemize}
\item Exclamation mark ! \index{Exclamation ("!)}\index{"!}
\item Vertical bar | \index{Vertical bar ("|)}\index{"|}
\item Doublequote \verb|"| \index{""}
\item Double doublequote \verb|""| \index{""""}
\item At character @ \index{At ("@)}\index{"@}
\item Left paranthesis \{ \index{\braceLeft}
\item Right paranthesis \}  \index{\braceRight}
\end{itemize}
run \texttt{xindex -x <file.idx>}\index{file.idx@\texttt{<file.idx>}|textit}\index{123}
\index{Etage} \index{Ètagé}
\twocolumn
\printindex
\end{document}
\end{externalDocument}




For the German language the double quote is an active character and it makes life easier
if one chooses another character.
The escape character can be changed easily by the optional argument \verb|-e "<char>"| or 
\verb|--escapechar "<char">|. The following example shows how
it works for the \Index{escape character} »>« (greater). By default the expression »\verb|>>|«\index{>\kern0pt>}
will
be a \TeX\ ligature with the output »>>«. %Internally the escape sequences are

With the beginning of \Lprog{xindex} the escaped chars
are converted into the internal strings and later back to the original meaning.
The two characters \verb|{}| cannot be used as \verb|\{\}| inside the argument of \Lcs{index}.
The package \Lpack{xindex} defines the two helper macros 

\begin{verbatim}
\providecommand\braceLeft{\{}
\providecommand\braceRight{\}}
\end{verbatim}

The following example shows how to use it:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1,2},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-e ">" -n,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{xindex}
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\section{Escaping characters with >}
\begin{itemize}
\item Exclamation mark ! \index{exclaim (>!)}
\item Vertical bar| \index{Vertical bar (>|)}
\item Escapechar \verb|>| \index{>>}
\item Double escapechar \verb|>>| \index{>>>>}
\item At character @ \index{At (>@)}
\item Group start \{ \index{\braceLeft}
\item Group end \{ \index{\braceRight}
\end{itemize}
Run \texttt{xindex} with \texttt{xindex -e ">" -n}\index{<file.idx>}\index{123}
\newpage
\printindex
\end{document}
\end{externalDocument}


\section{Language}\label{language}

The \Index{language} is only important for the first two headers in the output of the index data.
They are by default \emph{Symbols} followed by \emph{Numbers}. In a new version of \Lprog{xindex}
it will be customizable.
The predefined language is »en« and currently the following languages which its alias are defined:


\begin{Verbatim}[commandchars=\\<>]
<id> = {<symbols>, <numbers>, <alias language name>, ...}
indexheader = { 
  cs = {"Symboly", "Čísla", "czech"},
  da = {"Symboler", "Tal", "danish"},
  de = {"Symbole", "Zahlen", "austrian", "german", "germanb", "ngerman", "naustrian"},
  en = {"Symbols", "Numbers", "english", "USenglish", "american", "UKenglish", "british", "canadian", "australian", "newzealand"},
  es = {"Símbolos", "Números", "spanish"},
  fr = {"Symboles","Nombres", "french", "francais", "canadien", "acadian"},
  it = {"Simboli", "Numeri", "italian"},
  \Japanese jp = {"シンボル","番号","japanese"},
 \DejaVuMono nl = {"Symbolen", "Nummers", "dutch"},
  no = {"Symboler","Tall", "norsk", "nynorsk"},
  ru = {"Символы", "Числа", "russian"}, 
}
\end{Verbatim}

The following example was run with \verb|xindex -l it <file>.idx|:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1,2},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l it -e ">",
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\usepackage[italian]{babel}
\usepackage{multicol}
\makeatletter
\renewenvironment{theindex}{%    only for demonstration
  \begin{multicols}{2}[\section*{\indexname}]
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\section{Escaping simboli con >}
\begin{itemize}
\item punto esclamativo ! \index{exclaim (>!)}
\item linea verticale | \index{Vertical bar (>|)}
\item escapechar \verb|>| \index{>>}
\item doppio escapechar \verb|>>| \index{>>>>}
\item At siboli @ \index{At (>@)}
\end{itemize}
Initio \texttt{xindex} con \texttt{xindex -l it -e ">"}\index{123}
\twocolumn \printindex
\end{document}
\end{externalDocument}


The following example was run with \verb|xindex -k <file>.idx|. 
In this case \verb|xindex| tries to detect the language  from
the \Lfile{aux} file(s). This is only possible if  
package \Lpack{babel} or \Lpack{polyglossia} are used.

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1,2},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-k -e "?",
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\usepackage{multicol}
\makeatletter
\renewenvironment{theindex}{%    only for demonstration
  \begin{multicols}{2}[\section*{\indexname}]
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage[dutch]{babel} % !!!!
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\section{Escaping characters with ?}
\begin{itemize}
\item Exclamation mark ! \index{exclaim (?!)}
\item Vertical bar| \index{Vertical bar (?|)}
\item Escapechar \verb|?| \index{??}
\item Double escapechar \verb|??| \index{????}
\item At character @ \index{At (?@)}\index{?@}
\end{itemize}
Run \texttt{xindex} with \texttt{xindex -k -e "?"}\index{123}
\twocolumn\index{xindex@\texttt{xindex}}
\printindex
\end{document}
\end{externalDocument}

%Instead of using \verb|-l *| one can also use the parameter \verb|-k| or \verb|--checklang|.


For the Russian language you have to choose the language and the config file.
This allows to have different indexes with different language.



\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  pages={1},
  frame,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l RU -c RU -n,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  usefancyvrb,
%  lstOptions={columns=fixed}
]{xindex}
%! lualatex
\documentclass{scrartcl}
\usepackage{multicol}
\makeatletter
\renewenvironment{theindex}{%    only for demonstration
  \begin{multicols}{2}[\section*{\indexname}]
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage[russian]{babel}
\usepackage{fontspec}
\usepackage[regular]{newcomputermodern}
\defaultfontfeatures{Ligatures=TeX}
\usepackage{xindex}\makeindex   % run with xindex -l RU -c RU <file>
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\begin{tabular}{ll}
 Хвойные: & \verb|\index{Хвойные} |\index{Хвойные}\\
\quad торрея, & 
  \verb|\index{Хвойные!тисовые!торрея (Torreya)}|%
  \index{Хвойные!тисовые!торрея (Torreya) }\\
\quad тис ягодный, & 
  \verb|\index{Хвойные!тисовые!тис!ягодный (Táxus baccata)}|%
 \index{Хвойные!тисовые!тис!ягодный (Táxus baccata) }\\ 
\quad ливанский кедр, & 
  \verb|\index{Хвойные!сосновые!кедр!ливанский (Cedrus libani)}|%
  \index{Хвойные!сосновые!кедр!ливанский (Cedrus libani)}\\
\quad ель обыкновенная. &
  \verb|\index{Хвойные!сосновые!ель!обыкновенная (Pícea ábies)}|%
  \index{Хвойные!сосновые!ель!обыкновенная (Pícea ábies)}\\[2ex]
Под колючей ежевикой & \verb|\index{Ежевика (Rúbus) }|%
  \index{Ежевика (Rúbus)}\\ 
жил ушастый ёж. & 
  \verb|\index{Ёж!ушастый (Hemiechinus auritus)}|%
  \index{Ёж!ушастый (Hemiechinus auritus)}
\end{tabular}
\printindex  % xindex -l RU -c RU -n <file>
\end{document}
\end{externalDocument}



\clearpage


\section{Sorting}



\subsection{Default sorting by the UCA (Unicode Collection Algorithm)}
This Lua library from Michal Hoftich is part of \TeXLive\ and is used by default
for sorting. The supported languages and variants are listed in the file 
\Lfile{lua-uca-languages.lua}:

\texttt{af, 
am, 
ar, 
as, 
az, 
be, 
bg, 
bn, 
bs, 
bs\_cyrl, 
ca, 
chr, 
cs, 
cy, 
da, 
de, 
de\_din2, 
dsb, 
dz, 
ee, 
el, 
en, 
eo, 
es, 
et, 
fa, 
fi, 
fil, 
fo, 
fr, 
fr\_backward\_accents, 
ga, 
gl, 
gu, 
ha, 
haw, 
he, 
hr, 
hi, 
hsb, 
hu, 
hy, 
id, 
ig, 
is, 
it, 
ja, 
ka, 
kk, 
kl, 
km, 
kn, 
ko, 
kok, 
ky, 
lb, 
lkt, 
ln, 
lo, 
lt, 
lv, 
mk, 
ml, 
mn, 
mr, 
ms, 
mt, 
my, 
nb, 
ne, 
nl, 
nn, 
no, 
om, 
pa, 
pl, 
ps, 
pt, 
ro, 
ru, 
se, 
si, 
sk, 
sl, 
smn, 
sq, 
sr, 
sr\_latn, 
sv, 
sw, 
ta, 
te, 
th, 
tk, 
to, 
tr, 
ug, 
uk, 
ur, 
uz, 
vi, 
vo, 
wae, 
wo, 
yi, 
yo, 
zh, 
zu}



The sorting order can be easily modified. Read the documentation of the package \texttt{LUA-UCA}
on how to do it and what languages are supported so far. Any additional code setting for
UCA should be done in the file \Lfile{xindex-cfg-uca.lua}, which will automatically be read
by \Lprog{xindex}.

\begin{importantblock}
If possible, you should use the Unicode sorting by default and only for some special cases
where you define your own sorting scheme, you should use the \verb|-x| option.
\end{importantblock}


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
%  pages={6},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l cs,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  usefancyvrb,
%  lstOptions={columns=fixed}
]{xindex}
%! lualatex
\documentclass[paper=a6]{scrartcl}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{multicol}
\usepackage{makeidx}\makeindex
\def\Index#1{#1\index{#1}}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Sorted with \verb|-l cs|
\Index{ahoj} \Index{crha}, \Index{čaj}, \Index{chachar}, 
\Index{rak}, \Index{řeka}, \Index{srp}, \Index{šutr}, 
\Index{hudba}, \Index{linux}, \Index{zebra}, 
\Index{žába}, \Index{7 dubů}
\begin{multicols}{2} \printindex \end{multicols}
\end{document}
\end{externalDocument}




Modifications can be done in a config file which is then loaded by the
option \texttt{-c}. For example: the file \Lfile{xindex-cfg-uca.lua} has
modification for french and norwegian. For french the standard sorting rules 
\texttt{fr\_backward\_accents}, are a bit
special and should be the default also for the  language \texttt{fr}:

\begin{verbatim}
languages.fr = function(collator_obj)
   -- reverse search for accents in French (recommended):
  collator_obj.accents_backward = true
  local tailoring = function(s) collator_obj:tailor_string(s) end
  tailoring("&æ=ae")
  tailoring("&œ=oe")
  tailoring("&th<þ<<<Þ")       -- Canadian, see SGQRI004.pdf
  return collator_obj
end 
\end{verbatim}

Add any additional modifications to this file or create an own
config file and load it with \texttt{-c}.


\subsection{Default sorting by a character table}
This sorting is not completely unicode aware. It uses a translation table for accented characters,
which should only be used if the standard sorting method with UCA is not possible! This kind of sorting
has to be choosen by the option \texttt{-x} (don't use UCA).  The option \texttt{-u} for
using UCA is deprecated, because using UCA is the default.

Again, if one wants to use an own transformation table, then use something like:

\begin{verbatim}
alphabet_lower = { --   for sorting
    { ' ' },  -- only for internal tests
    { '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' }
}
\end{verbatim}

There is also a table for the uppercase letters. If it should be edited or extended then first copy  the
base configuration file \Lfile{xindex-cfg.lua} and modify that new file. It can be used by \XI
with the optional argument \texttt{-c newfile} if it is named as \Lfile{xindex-newfile.lua}. 
For German there already exists a configuration
file \Lfile{xindex-DIN2.lua} which uses the so-called »Telefonbuchsortierung« which converts 
the umlauts like ö$\rightarrow$oe:

\begin{verbatim}
alphabet_upper = { -- for sorting
    { ' ' },
    { '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' }
}
\end{verbatim}


\subsection{Examples}
\subsubsection{German language and no UCA}

\begin{externalDocument}[
  grfOptions={scale=0.9},%width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.4\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l de -x,
  runs=2,code,docType=latex,
  showFilename,
  usefancyvrb,
  align=\centering,
%  lstOptions={columns=fixed}
]{xindex}
%! lualatex
\documentclass[paper=a5]{scrartcl}
\usepackage[ngerman]{babel}
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\newcommand\Index[1]{\index{#1}#1}
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
Sorted with \verb|-l DE -x|\par
\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} 
\Index{Oberin} \Index{Österreich} 
\Index{Öresund} \Index{Ostern} 
\Index{Ober} \Index{Oberin} 
\Index{Obstler} \Index{Öl} 
\Index{ölen} \Index{Ödem} 
\Index{Oligarch} \Index{Oder} 
\Index{oder} \index{Fluss!Oder} 
\index{Oder|seealso{Fluss}} 
\Index{Göbel} \Index{Goethe} 
\Index{Göthe} \Index{Götz} 
\Index{Goldmann}

\printindex
\end{document}
\end{externalDocument}


\subsubsection{German language (DIN2) and no UCA}

In this case a letter Ö, Ä, Ü, ö, ä, ü is converted to Oe, Ae, Ue, oe, ae, ue before sorting:

\noindent
\begin{externalDocument}[
  grfOptions={scale=0.9},%width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.4\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-c DIN2 -l DE -x,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass[paper=a5]{scrartcl}
\usepackage[ngerman]{babel}
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\newcommand\Index[1]{\index{#1}#1}
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
Sorted with 
\verb|--config DIN2 -l DE -x|

\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} 
\Index{Oberin} \Index{Österreich} 
\Index{Öresund} \Index{Ostern} 
\Index{Ober} \Index{Oberin} 
\Index{Obstler} \Index{Öl} 
\Index{ölen} \Index{Ödem} 
\Index{Oligarch} \Index{Oder} 
\Index{oder} \index{Fluss!Oder} 
\index{Oder|seealso{Fluss}} 
\Index{Göbel} \Index{Goethe} 
\Index{Göthe} \Index{Götz} 
\Index{Goldmann}
\printindex
\end{document}
\end{externalDocument}


\clearpage%%%%%%%%%%%

\subsubsection{German language with UCA}

\begin{externalDocument}[
  grfOptions={scale=0.9},%width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.4\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l de, % german and UCA
  runs=2,code,docType=latex,
  showFilename,
  usefancyvrb,
  align=\centering,
%  lstOptions={columns=fixed}
]{xindex}
%! lualatex
\documentclass[paper=a5]{scrartcl}
\usepackage[ngerman]{babel}
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\newcommand\Index[1]{\index{#1}#1}
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
Sorted with \verb|-l DE| and using UCA\par
\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} 
\Index{Oberin} \Index{Österreich} 
\Index{Öresund} \Index{Ostern} 
\Index{Ober} \Index{Oberin} 
\Index{Obstler} \Index{Öl} 
\Index{ölen} \Index{Ödem} 
\Index{Oligarch} \Index{Oder} 
\Index{oder} \index{Fluss!Oder} 
\index{Oder|seealso{Fluss}} 
\Index{Göbel} \Index{Goethe} 
\Index{Göthe} \Index{Götz} 
\Index{Goldmann}
\printindex
\end{document}
\end{externalDocument}


\subsubsection{German language (DIN2) with UCA}

The same sorted with the German DIN variant 2. It uses also the config
file 
with \verb|--config DIN2|, but sets the language internally to \verb|de_din2| for
UCA and do not use the character tables:

\noindent
\begin{externalDocument}[
  grfOptions={scale=0.9},%width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.4\linewidth,
  pages={2},
  frame=false,compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-c DIN2 -l DE,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass[paper=a5]{scrartcl}
\usepackage[ngerman]{babel}
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\newcommand\Index[1]{\index{#1}#1}
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
Sorted with 
\verb|--config DIN2 -l DE|

\Index{Österreich} \Index{Öresund} 
\Index{Ostern} \Index{Ober} 
\Index{Oberin} \Index{Österreich} 
\Index{Öresund} \Index{Ostern} 
\Index{Ober} \Index{Oberin} 
\Index{Obstler} \Index{Öl} 
\Index{ölen} \Index{Ödem} 
\Index{Oligarch} \Index{Oder} 
\Index{oder} \index{Fluss!Oder} 
\index{Oder|seealso{Fluss}} 
\Index{Göbel} \Index{Goethe} 
\Index{Göthe} \Index{Götz} 
\Index{Goldmann}

\printindex
\end{document}
\end{externalDocument}


\clearpage%%%%%%%%%%%

\subsubsection{french language with UCA}

\begin{externalDocument}[
  grfOptions={scale=0.9},%width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.4\linewidth,
  pages={4},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-k, % detect lang (french) and UCA
  runs=2,
  code,docType=latex,
  showFilename,
  usefancyvrb,
  align=\centering,
%  lstOptions={columns=fixed}
]{xindex}
%! lualatex
\documentclass[paper=a5]{scrartcl}
\usepackage[french]{babel}
%StartVisiblePreamble
\usepackage[makeidx]{hvindex}
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
\Index{CÔTÉ} \Index{cote} \Index{Côté} 
\Index{COTÉ} \Index{côte} \Index{COTE} 
\Index{côté} \Index{Coté} \Index{coté} 
\Index{Cote} \Index{CÔTE} \Index{Côte} 
\Index{lésé} \Index{péché}\Index{bohème} 
\Index{gêné} \Index{pêche} \Index{cæsium}
\Index{pêcher} \Index{révèle} 
\Index{pécher} \Index{révélé}
\Index{Bohême} \Index{relève} 
\Index{PÉCHÉ} \Index{maçon}
\Index{relevé} \Index{Élève} 
\Index{gêne} \Index{élevé}
\Index{MÂCON} \Index{gène} 
\Index{Bohémien} \Index{caennais}
\Index{lèse} \Index{coexistence} 
\Index{cœur} \Index{coefficient} 
\Index{cafard} \Index{CŒUR} 
\Index{CÆSIUM} \newpage \Index{coté} 
\Index{cœur} \Index{péché} \newpage
\Index{coté}\Index{coefficient}
\printindex
\end{document}
\end{externalDocument}

\clearpage

\subsubsection{Japanese language with UCA}


The following runs with \verb|xindex -l jp <file>|:

%  {begin\string{document\string}}%       #2
%  {end\string{document\string}}%         #3
%  {\perCent StartVisiblePreamble}% #4
%  {\perCent StopVisiblePreamble}%  #5

\noindent
%\begin{minipage}[t]{0.45\linewidth}
%\vspace{0pt}
\setsansfont{SourceHanSans}\sffamily
\edef\FancyVerbStartString{\perCent StartVisiblePreamble}
\edef\FancyVerbStopString{\perCent StopVisiblePreamble}
\colorbox{black!20}{\parbox{\linewidth}{%
\VerbatimInput[fontfamily=helvetica]{Examples/xindex-12.tex}
}}

\edef\FancyVerbStartString{\string\begin\string{document\string}}
\edef\FancyVerbStopString{\string\end\string{document\string}}
\colorbox{black!10}{\parbox{\linewidth}{%
\VerbatimInput[fontfamily=helvetica]{Examples/xindex-12.tex}
}}

%\end{minipage}\hfill
%\begin{minipage}[t]{0.54\linewidth}
%\vspace{0pt}
\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.5\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l jp,
  runs=2,
  code=false,
  docType=latex,
  showFilename,
  align=\centering,
  usefancyvrb,
%  lstOptions={fontfamily=helvetica}
]{xindex}
%! lualatex
\documentclass[a5paper]{article}
%StartVisiblePreamble
\usepackage{fontspec}
\setmainfont{SourceHanSans}
\usepackage[japanese]{babel}
\addto\captionsjapanese{\def\indexname{指数}}
\usepackage{hvindex}% for \Index
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}  
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
\pagestyle{empty}
\begin{document}
\Index{車} \Index{車道} 日本\index{日本|fbox}  \Index{病院} \Index{コンピュータ} 
\Index{プリンタ} \Index{印刷}  \Index{スイミングプール} \Index{天王} \Index{広島} 
\Index{ドイツ} \Index{日本} \Index{ワープロ} 
\Index{foo} und \Index{bar} \Index{//} \Index{4711}   \newpage\printindex
\end{document}
\end{externalDocument}
%\end{minipage}


\setsansfont{Libertinus Sans}\rmfamily



\subsection{Case sensitive index entries}
By default \textsf{foo} and \textsf{Foo} are two different entries and will handled differently
by \Lprog{xindex}: \textsf{Foo} will be as an own entry \emph{before} \textsf{foo}. Let's see 
a more complex example. In the index the entry \verb|xindex-DIN2.lua| is the first one of
the \verb|xindex-???| series because uppercase letters are sorted before lowercase letters.

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
%  xindexOptions=,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}
]{xindex}
%%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\begin{filecontents}[force,noheader]{\jobname.idx}
\indexentry{xindex package@\texttt  {xindex} package|hyperpage}{2}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{4}
\indexentry{xindex-cfg.lua file@\texttt  {xindex-cfg.lua} file|hyperpage}{6}
\indexentry{xindex-newfile.lua file@\texttt  {xindex-newfile.lua} file|hyperpage}{6}
\indexentry{xindex-DIN2.lua file@\texttt  {xindex-DIN2.lua} file|hyperpage}{6}
\indexentry{xindex-cfg-common.cfg file@\texttt  {xindex-cfg-common.cfg} file|hyperpage}{9}
\indexentry{xindex-cfg.lua file@\texttt  {xindex-cfg.lua} file|hyperpage}{10}
\indexentry{xindex-HAdW-eKO.lua file@\texttt  {xindex-HAdW-eKO.lua} file|hyperpage}{10}
\indexentry{xindex-dtk.lua file@\texttt  {xindex-dtk.lua} file|hyperpage}{12}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{13}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{14}
\indexentry{xindex-cfg-common.lua file@\texttt  {xindex-cfg-common.lua} file|hyperpage}{14}
\indexentry{xindex package@\texttt  {xindex} package|hyperpage}{15}
\end{filecontents}
%StartVisiblePreamble
\usepackage{makeidx}
\usepackage{hyperref}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
foo\newpage
\printindex
\end{document}
\end{externalDocument}



The same example sorted with the \verb|-a| or \verb|--no_casesensitive| has another output: now
\verb|xindex-cfg-common.lua| is the first one of the \verb|xindex-???| series.


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
  xindexOptions=-a,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\begin{filecontents}[force,noheader]{\jobname.idx}
\indexentry{xindex package@\texttt  {xindex} package|hyperpage}{2}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{4}
\indexentry{xindex-cfg.lua file@\texttt  {xindex-cfg.lua} file|hyperpage}{6}
\indexentry{xindex-newfile.lua file@\texttt  {xindex-newfile.lua} file|hyperpage}{6}
\indexentry{xindex-DIN2.lua file@\texttt  {xindex-DIN2.lua} file|hyperpage}{6}
\indexentry{xindex-cfg-common.cfg file@\texttt  {xindex-cfg-common.cfg} file|hyperpage}{9}
\indexentry{xindex-cfg.lua file@\texttt  {xindex-cfg.lua} file|hyperpage}{10}
\indexentry{xindex-HAdW-eKO.lua file@\texttt  {xindex-HAdW-eKO.lua} file|hyperpage}{10}
\indexentry{xindex-dtk.lua file@\texttt  {xindex-dtk.lua} file|hyperpage}{12}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{13}
\indexentry{xindex program@\texttt  {xindex} program|hyperpage}{14}
\indexentry{xindex-cfg-common.lua file@\texttt  {xindex-cfg-common.lua} file|hyperpage}{14}
\indexentry{xindex package@\texttt  {xindex} package|hyperpage}{15}
\end{filecontents}
%StartVisiblePreamble
\usepackage{makeidx}
\usepackage{hyperref}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
foo\newpage
\printindex
\end{document}
\end{externalDocument}







\subsection{Ignore space for sorting}
By default »\textsf{alpha sort}« will be sorted \emph{before} »\textsf{alphaA}«:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
%  xindexOptions=,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
% default sorting 
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Test
\index{alpha sort}\index{alphaA}
\newpage
\printindex
\end{document}
\end{externalDocument}


This can be changed with the optional argument \verb|-i| or \verb|--ignoreSpace|:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
  xindexOptions=-i,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
% sort with xindex -i <file>
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Test
\index{alpha sort}\index{alphaA}
\newpage
\printindex
\end{document}
\end{externalDocument}




\section{Pagenumbers}
\subsection{Compressing pagenumber series}\label{Compressing}
By default page sequences of an entry are compressed to 
\begin{description}
\item[8f] page 8 and 9
\item[8ff] page 8, 9, and 10
\item[8-12] page 8, 9, \ldots, 12
\end{description}

The so-called folio abbreviation is language dependent and defined in the
file \Lfile{xindex-cfg-common.cfg}:

{\setsansfont[Scale=MatchUppercase]{SourceHanSans}
\small
\begin{Verbatim}[fontfamily=helvetica]
folium = { 
  cs = {"f.", "ff."},
  da = {"f", "ff"},
  de = {"f", "ff"},
  en = {"f", "ff"},
  es = {"f", "ff"},
  fr = {"\\,sq.","\\,sqq."},
  it = {"f", "ff"},
  jp = {"シンボル","番号"},
  no = {"\\,f.","\\,ff."},
}
\end{Verbatim}
}

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={6},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l fr,
  runs=2,
  code,docType=latex,
  showFilename,
%  runsequence={lualatex,{xindex -l fr},lualatex,lualatex},
%  shellesc=false,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage[french]{babel}
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Sorted with \verb|-l fr|

foobar\index{foobar|(}
foo\index{foo}\index{bar}\index{baz}\newpage
foo\index{foo}\index{bar}\index{baz}\newpage
foo\index{bar}\index{baz}\newpage
foo\index{baz}\newpage
foo\index{foo}foobar\index{foobar|)}
\newpage
\printindex
\end{document}
\end{externalDocument}


\subsection{Modify Pagenumber}
Every page can be combined with an additional macro, like \verb=\index{foo|fbox}=, the page number
will be set into a framebox. If we have on the same page the two commands:

\begin{verbatim}
foo\index{foo} and foo\index{foo|bar}
\end{verbatim}

then we have two \emph{different} index entries which will not be compressed to one entry.
In the following example we have four different entries for \emph{foo} which is the reason
that we do not get an output like \texttt{foo, 1--4}. Only the first two entries are
of the same type, so we get \texttt{1f} in the output.

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={5},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Ein foo\index{foo} \newpage und \index{foo} 
ein foo\index{foo|textit} \newpage 
und foo\index{foo|textbf} \newpage 
und foo\index{foo|fbox}

\newpage
\printindex
\end{document}
\end{externalDocument}

\subsection{Supress Pagenumber}
Instead of printing an index in the default way, one can also print a glossary without
the pagenumbers. This is possible with the optional argument \verb|-g| which is equivalent
to the long form \verb|--no_pagenumber|. The following example uses an own config file for
the definition of the \Lenv{description} environment:

\begin{verbatim}
itemPageDelimiter = ""     
compressPages     = true   
fCompress         = false  
minCompress       = 2   
rangeSymbol       = "--"
numericPage       = true
sublabels         = {"", "\\item", "\\item", "\\item"} 
pageNoPrefixDel   = ""    
idxnewletter      = "\\textbf" 
envStart          = "\\begin{description}"
indexOpening      = "\\makeatletter\z
                     \\def\\subitem{\\@idxitem} \\def\\subsubitem{\\@idxitem}\z 
                     \\def\\subsubsubitem{\\@idxitem}\z
                     \\makeatother\z
                     \\itemsep 0.1ex" -- commands after envStart
envStop           = "\\end{description}"
\end{verbatim}

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.55\linewidth,
  pages={2,3},
  frame=true,
  compiler=lualatex,
  verbose,
  shellesc,
%  xindex,
%  xindexOptions=-c description -g, 
  runs=2,
  code,docType=latex,
 %xindex -c description -n -g xindex-17.idx
 %xindex -c description -n --no_pagenumber gls.idx
%  runsequence={lualatex,{xindex -c description -n -g},lualatex,lualatex},
  showFilename,
  align=\centering,
  grfOptions={width=0.45\linewidth},
  usefancyvrb,
  %lstOptions={columns=fixed}
  ]{xindex}
%! lualatex
\documentclass{article}
\usepackage[a5paper]{geometry}
\usepackage{libertinus}
\setmonofont{DejaVu Sans Mono}[Scale=0.88,FakeStretch=0.9]
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\begin{filecontents}[force,noheader]{xindex-description.lua}
itemPageDelimiter = ""     -- Hello, 14
compressPages     = true    -- something like 12--15, instead of 12,13,14,15. the |( ... |) syntax is still valid
fCompress	      = false    -- 3f -> page 3, 4 and 3ff -> page 3, 4, 5
minCompress       = 2       -- 1--3 
rangeSymbol       = "--"
numericPage       = true    -- for non numerical pagenumbers, like "VI-17"
sublabels         = {"", "\\item", "\\item", "\\item"}  -- for the (sub(sub(sub-items  first one is for item
pageNoPrefixDel   = ""     -- a delimiter for page numbers like "VI-17"  -- not used !!!
idxnewletter      = "\\textbf"  -- Only valid if -n is not set
envStart          = "\\begin{description}"  
indexOpening      = "\\makeatletter\z
							\\def\\subitem{\\@idxitem} \\def\\subsubitem{\\@idxitem} \\def\\subsubsubitem{\\@idxitem}\z
							\\makeatother\z
							\\itemsep 0.1ex" -- commands after envStart
envStop           = "\\end{description}"

alphabet_lower = { { 'е', 'ё' } }
alphabet_upper = { { 'Е', 'Ё' } }
\end{filecontents}
%xindex -c description -n --no_pagenumber gls.idx
%StartVisiblePreamble
\usepackage[english]{babel}
\usepackage[imakeidx]{xindex}%  run xindex internally
\makeindex
\makeindex[name=gls, options= -c description -n --no_pagenumber]
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Abbreviations:

XAS,\index{XAS --- X-ray absorption spectroscopy.}
XAFS,\index{XAFS --- Extended x-ray absorption fine structure.}
EXAFS,\index{EXAFS --- Extended x-ray absorption fine structure.}
XANES,\index{XANES --- X-ray absorption near edge structure.}
PES,\index{PES --- Photo emission spectroscopy.}
ARPES,\index{ARPES --- Angle resolved photo electron spectroscopy.}
SCES,\index{SCES --- Strongly correlated tlectron systems.}
HTSC,\index{HTSC --- High temperature superconductivity.}
MOCVD,\index{MOCVD --- Metalorganic chemical vapour deposition.}
PLD.\index{PLD ---Pulsed laser deposition.}

\smallskip Terms.

Fermions:
\index[gls]{Fermions@[Fermions]}%
\index[gls]{Fermions@[Fermions]![\sf Fermion] --- a particle with a 
	half-odd-integer spin $S$.}electron,
\index[gls]{Fermions@[Fermions]![\sf Electron] --- a subatomic particle 
	with a negative elementary electric charge: $S=1/2$.}proton,
\index[gls]{Fermions@[Fermions]![\sf Proton] --- a subatomic particle with a 
	positive elementary electric charge: $S=1/2$.}positron,
\index[gls]{Fermions@[Fermions]![\sf Positron] --- a particle with a positive 
	elementary electric charge, and the same mass as an electron: $S=1/2$.}neutron,
\index[gls]{Fermions@[Fermions]![\sf Neutron] --- a subatomic electrically 
	neutral particle: $S=1/2$.}neutrino.
\index[gls]{Fermions@[Fermions]![\sf Neutrino] --- an elementary  electrically 
	neutral particle with very small rest mass: $S=1/2$.}

Bosons:
\index[gls]{Bosons@[Bosons]}%
\index[gls]{Bosons@[Bosons]![\sf Boson] --- a particle with an 
integer spin $S$.}photon,
\index[gls]{Bosons@[Bosons]![\sf Photon] --- a quantum of the 
electromagnetic field: $S=1$.}meson,
\index[gls]{Bosons@[Bosons]![\sf Meson] --- a hadronic subatomic particle 
composed of an equal number of quarks and antiquarks: $S=0$.}pion.
\index[gls]{Bosons@[Bosons]![\sf Pion] --- any of $\pi^0$-, $\pi^+$-, 
	$\pi^-$- mesons consisting of quark and antiquark: $S=0$.}

\printindex
\printindex[gls]
\end{document}
\end{externalDocument}




\section{The config file}

The main config file is \Lfile{xindex-cfg.lua} and used by default. % and loading it by the 
%optional parameter -c makes no sense. 
A new config file must have the prefix \texttt{xindex-}
and the file extension \Lext{lua}, for example: \Lfile{xindex-HAdW-eKO.lua} which can be used
with \verb|--config HAdW-eKO|. The file must be saved in the documents directory or in
one which is known to \Lprog{kpsewhich}, for example\footnote{The directory \texttt{xindex} must be created
before saving the file.} \verb|$TEXMFLOCAL/tex/lualatex/xindex/| %$
Do not forget to update the filename database.

A new config file must declare at least the variables which are part of the
default config file: the translation tables and

\begin{verbatim}
itemPageDelimiter = ","     -- Hello, 14
compressPages     = true    
  -- something like 12--15, instead of 12,13,14,15. the |( ... |) syntax is still valid
fCompress	  = true    -- 3f -> page 3, 4 and 3ff -> page 3, 4, 5
minCompress       = 3       -- 14--17 
rangeSymbol       = "--"    
numericPage       = true    -- for non numerical pagenumbers, like "VI-17"
sublabels         = {"", "-\\-", "--\\-", "---\\-"} 
   -- for the sub(sub(sub-items, first one is empty
pageNoPrefixDel   = ""     -- a delimiter for page numbers like "VI-17"  -- not used !!!
indexOpening      = ""     -- commands/text after \begin{theindex}
\end{verbatim}

The new config file can define own functions for compressing the pagelist
for a given entry and for the formatting of the output. They must be called 
\verb|specialCompressPageList| and  \verb|specialGetPageList|.
%needs
%the unmodified list of pages for one entry. 

For example:

\begin{verbatim}
function specialCompressPageList(pages)
  if (pages[1]["number"] == "") then pages[1]["number"] = " " end
  if (#pages <= 1) then 
    pages[1]["number"] = pages[1]["number"]:gsub('-',':~')-- replace "-" with ":~"
    return pages 
  end  -- only one pageno
  local sortPages = {}
  local roman 
  local volume
  local page
  local i
  for i=1,#pages do
     roman = string.gsub(pages[i]["number"],'%U*','') -- only uppercase to catch VII/1-123f and VII/3-123ff (folium pages)
     if romanToNumber(roman) then
       roman = string.format("%05d",tonumber(romanToNumber(roman))) -- only roman part VII
     else
       roman = ""
     end
     volume = string.gsub(pages[i]["number"],'%a*','') -- only the number /2 123 or /2-123
     if volume then volume = volume:gsub('-%d*','') end -- delete - char to get /2
     page = string.gsub(pages[i]["number"],'.*-','')
     page = string.format("%5s",page)
     sortPages[#sortPages+1] = {
       origin = pages[i],
       sort = roman..volume.." "..page }  -- no minus between Roman/Volume and first page
   end
  table.sort(sortPages, function(a,b) return a["sort"] < b["sort"] end )

[...]

    return pages
  end
end
\end{verbatim}

The above code 
is a special function which can handle \Index{page number}s like VII-17, VIII/2/1-186.
Internally exists a function \verb|compressPageList| which is used if no
\verb|specialCompressPageList| is defined. 

\begin{externalDocument}[
  grfOptions={scale=0.9},% width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.25\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-c HAdW-eKO,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\begin{filecontents}[force,noheader]{\jobname.idx}
\indexentry{Aachen, Johannes von}{VII/1-215}
\indexentry{Aarones}{VII/2/1-1003}
\indexentry{Aarones}{VII/2/1-1012}
\indexentry{Abrahamson}{VII/2/1-864}
\indexentry{Abrahamson}{VII/2/1-991}
\indexentry{Abrahamson}{VII/2/1-1048}
\indexentry{Abrahamson}{VII/2/1-1067}
\indexentry{Abrahamson}{VII/2/1-1156}
\indexentry{Adamson}{VII/2/1-1223}
\indexentry{Adamson}{IX/1-1228}
\indexentry{Karl!der Große, Kaiser}{VI/2-987}
\indexentry{Karl!der Große, Kaiser}{VI/2-989}
\indexentry{Karl!der Große, Kaiser}{VI/2-1028}
\indexentry{Karl!IV., Kaiser}{VI/1-12}
\indexentry{Karl!V., Kaiser}{VI/1-84}
\indexentry{Karl!V., Kaiser}{VI/1-284}
\indexentry{Karl!V., Kaiser}{VI/1-654}
\indexentry{Karl!V., Kaiser}{VI/2-708}
\indexentry{Karl!V., Kaiser}{VI/2-1014}
\indexentry{Karl!V., Kaiser}{VI/2-1043}
\indexentry{Karl!V., Kaiser}{VI/2-1131}
\indexentry{Karl!V., Kaiser}{VI/2-1210}
\indexentry{Braunschweig-Wolfenbüttel!Karl Viktor von, Herzog}{VI/1-83}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-758}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-759}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-760}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-761}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-765}
\indexentry{Adrian!Hauster}{VII/1-514}
\indexentry{Adrian!Hauster}{XI/1-515}
\indexentry{Alting!Mensa}{VII/1-426}
\indexentry{Alting!Mensa}{VII/1-434}
\indexentry{Alting!Mensa}{VII/1-453}
\indexentry{Alting!Mensa}{VII/1-455}
\indexentry{Alting!Mensa}{VII/1-466}
\indexentry{Alting!Mensa}{VII/1-467}
\indexentry{Bremen!Heinz von, Erzbischof|see{Sachsen-Lauenburg}}{}
\indexentry{Osnabrück!Heinz  von, Bischof|see{Sachsen-Lauenburg}}{}
\indexentry{Zwingl, Haldrich}{IX-479}
\indexentry{Zwingl, Haldrich}{IX-692}
\indexentry{Julian!Apostata, römischer Kaiser}{VII/2/1-904}
\indexentry{Justinian I., byzantinischer Kaiser}{VII/1-326}
\indexentry{Justinian I., byzantinischer Kaiser}{VII/1-734}
\indexentry{Justinian I., byzantinischer Kaiser}{VII/2/1-1011}
\indexentry{Karl!V., Kaiser}{VII/1-34}
\indexentry{Karl!II., Kaiser}{VII/1-147}
\indexentry{Karl!III., Kaiser}{VII/1-149}
\indexentry{Karl!VI., Kaiser}{VII/1-296}
\indexentry{Karl!IV., Kaiser}{VII/1-34}
\indexentry{Karl!IV., Kaiser}{VII/1-147}
\indexentry{Karl!X., Kaiser}{VII/1-149}
\indexentry{Karl!IX., Kaiser}{VII/1-296}
\end{filecontents}
\documentclass[a4paper]{article}
\usepackage[margin=1cm]{geometry}
\usepackage{xcolor}
\usepackage{url}
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{Personenverzeichnis}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@ \raggedright
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\mbox{}\printindex
\end{document}
\end{externalDocument}

The \Lext{idx} file of the above example looks like

\begin{verbatim}
\indexentry{Karl!V., Kaiser}{VI/2-1210}
\indexentry{Braunschweig-Wolfenbüttel!Karl Viktor von, Herzog}{VI/1-83}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-758}
\indexentry{Schleswig-Holstein!Rudolf von, Herzog}{VII/2/1-759}
[...]
\end{verbatim}





The \Index{config file} \Lfile{xindex-dtk.lua} defines a special page output:

\begin{verbatim}
function specialGetPageList(v,hyperpage)  -- Entry table, boolean
  local Pages = {}
[..]
      if (Pages[1]["special"] == nil) or (Pages[1]["number"] == nil) then return ""  end 
      if #Pages == 1 then
        return "\\relax"..Pages[1]["number"].."\\@nil"
      else        
        pageNo = "\\relax"..Pages[1]["number"] 
        for i=2,#Pages do
          if Pages[i]["number"] then
            pageNo = pageNo..", "..Pages[i]["number"].."\\@nil"
            Pages[i] = {}
          end
        end
[..]
end
\end{verbatim}


The following example runs \verb|xindex -c dtk -l de -n <input>| and the \Lext{idx} file looks like

\begin{verbatim}
\indexentry{BährendtsenElke@Elke Bährendtsen!\Email {elke"@xyz.de}}{14}
\indexentry{JacekJonasson Jared@Jonasson Jared Jazek!\Email {mail"@jones.net}}{20}
[...]
\end{verbatim}

\begin{externalDocument}[
  grfOptions={scale=0.9},% width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.25\linewidth,
  pages={1},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-c dtk -n -l de,
  runs=2,code,docType=latex,
  runsAfter=2,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\begin{filecontents}[force,noheader]{\jobname.idx}
\indexentry{VoßHerbert@Herbert Voß!Wasgensteig 12\protect \\10127 Potsdam\protect \\\Email {herbert"@xyz.de}}{3}
\indexentry{SeversMarkus@Markus Severs!siehe Seite~\protect \pageref  {president}}{4}
\indexentry{VoßHerbert@Herbert Voß!Wasgensteig 12\protect \\10127 Potsdam\protect \\\Email {herbert"@xyz.de}}{5}
\indexentry{ZiegendaMichael@Michael Ziegenda!Lokostr. 19 \protect \\ 20713 Kallin \protect \\\Email {ziegenda"@mail.com}}{9}
\indexentry{BährendtsenElke@Elke Bährendtsen!\Email {elke"@xyz.de}}{14}
\indexentry{JacekJonasson Jared@Jonasson Jared Jazek!\Email {mail"@jones.net}}{20}
\indexentry{KoonMartin@Martin Koon!Freiherr-Links-Weg~16\protect \\ 15525~Neckar\protect \\ \Email {koo"@xyz.org}}{24}
\indexentry{KoonMartin@Martin Koon!Freiherr-Links-Weg~16\protect \\ 15525~Neckar\protect \\ \Email {koo"@xyz.org}}{31}
\indexentry{SchusterEike@Eike Schulter!Haussteig~15\protect \\ 36396~Stuttgart\protect \\ \Email {eike.schulter"@kabel.de}}{40}
\indexentry{FanntHorst@Horst Fannt!Friedrichallee 74\protect \\13233 Neu-Isenburg\protect \\\Email {horst.fannt"@gmxnet.de}}{48}
\end{filecontents}
\documentclass{article}
\usepackage{url}
\DeclareUrlCommand\Email{%
  \def\UrlLeft{}%
  \def\UrlRight{}%
  \def\UrlLinkPrefix{mailto:}%
  \def\UrlType{email}%
}
\usepackage{multicol}
\makeatletter
\def\DTK@scan@item#1\subitem#2\relax#3\@nil{%
  \def\DTK@tempa{#1}\def\DTK@tempb{#2}\def\DTK@tempc{#3}%
}
\def\theindex{%    only for demonstration
  \columnseprule=\z@ \columnsep=10\p@
  \begin{multicols}{2}[\noindent\textbf{\large Autorenliste}]%
    \makeatletter
    \def\indexspace{}%
    \parindent\z@
    \setlength{\parskip}{\z@ \@plus .3\p@}%
    \setlength{\parfillskip}{\z@ \@plus 1fil}%
    \raggedright
    \def\item##1\@nil{\DTK@scan@item##1\@nil
      \par\parbox{\columnwidth}{%
        \textbf{\DTK@tempa}\hfill[\DTK@tempc]\par\DTK@tempb
      }%
      \par\bigskip
    }%
}
\def\endtheindex{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
\mbox{}\label{president}
\printindex
\end{document}
\end{externalDocument}


%\subsection{Sublabels}
There are three predefined sublabels for \Lcs{subitems}. The program itself can handle more, there is
no limit for \Lprog{xindex}.

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
%  xindexOptions=,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{article}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \pagestyle{empty}%
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\pagestyle{empty}%
%StartVisiblePreamble
\makeatletter
\g@addto@macro{\theindex}{%
  \def\subsubsubitem{\@idxitem\hspace*{35\p@}}
  \def\subsubsubsubitem{\@idxitem\hspace*{40\p@}}
}
\makeatother
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\begin{document}
foo\index{foo} bar\index{foo!bar}
baz\index{foo!bar!baz} foobar%
\index{foo!bar!baz!foobar} Kuba 
\index{foo!bar!baz!foobar!Kuba}
\newpage \printindex
\end{document}
\end{externalDocument}


\clearpage

\section{\texttt{hyperref}}

Using the package \Lpack{hyperref} is no problem:

%\enlargethispage{2.5\normalbaselineskip}

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={3},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass[paper=a6]{scrartcl}
\usepackage{multicol}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \begin{multicols}{2}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\def\endtheindex{\end{multicols}}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\usepackage{hvindex}% for \Index
\usepackage[colorlinks]{hyperref}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Sorted with \verb|-l DE| \par
\Index{Österreich} \Index{Öresund} \Index{Ostern} 
\Index{Ober} \Index{Oberin} \Index{Österreich} 
\index{Öresund|textbf} \Index{Ostern} \Index{Ober} 
\Index{Oberin} \Index{Obstler} \Index{Öl} \Index{ölen} 
\Index{Ödem} \Index{Oligarch} \Index{Oder} \Index{oder} 
\index{Fluss!Oder|textit} \Index{Oder|seealso{Fluss}} 
\Index{Göbel} \Index{Goethe} \Index{Göthe} \Index{Götz} 
\newpage\Index{Goldmann} \Index{Goethe} \newpage \printindex
\end{document}
\end{externalDocument}


The following example fixes a problem with \Lpack{hyperref} and escaping the | character,
e.g.\verb/"|/. In such a case \Lpack{hyperref} ignores the vertical bar.
With the optional parameter \verb/-f | --fix_hyperref/, which is still experimental,
\Lprog{xindex} tries to fix this problem. However, instead
of using this problematic vertical character, you can use \Lcs{textbar}, which also solves the
problem.

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.55\linewidth,
  pages={3},
  frame=false,
  compiler=lualatex, 
  crop,
  shellesc,
%  xindex,
%  xindexOptions=-,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
%  grfOptions={width=\linewidth},
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{article}
\usepackage{libertinus}
\let\NewPage\newpage% only for demo
\makeatletter
\renewcommand\newpage{\NewPage\let\ps@plain\ps@empty}
\makeatother
%StartVisiblePreamble
\usepackage[imakeidx]{xindex}
\usepackage{hvindex}
\makeindex[columns=5, columnsep=6pt, options=--fix_hyperref]
\usepackage{hyperref}
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
	Symbols:\\
	! \index{"!} " \index{""} \# \index{#@\#} \$ \index{$@\$}
	\% \index{%@\%} \& \index{&@\&} ' \index{'} ) \index{)}
	( \index{(} * \index{*} + \index{+} , \index{,@,\,}
	- \index{-} . \index{.} / \index{/} : \index{:}
	; \index{;} < \index{<} = \index{=} > \index{>}
	? \index{?} @ \index{"@} [ \index{[} ] \index{]}
	\_ \index{_@\_} ` \index{`} | \index{\textbar}
	\newpage\index{"|}\index{\textbar}\index{123}\Index{Post}
	\{ \index{\braceLeft} \} \index{\braceRight}
	\textbackslash \index{\@\textbackslash}
	\textasciicircum \index{^@\textasciicircum}
	\textasciitilde \index{~@\textasciitilde}
	Alphabet: \Index{Z},\Index{Zeppelin}\Index{Foo}\dots
	\Index{...@\ldots}
	\printindex
\end{document}
\end{externalDocument}



\section{Including \LaTeX\ commands into the \Lext{idx} file}
The command \Lcs{addtocontents} doesn't work for the index file. With the \LaTeX\ package
\Lpack{xindex} (same name as the Lua program \Lprog{xindex}) defines a macro \Lcs{writeidx}
which writes its argument into the \Lext{idx} file. This can be useful to insert a 
\Index{pagebreak}\slash\Index{columnbreak}
before a new letter in the output of the index file:


\begin{verbatim}
\documentclass{article}
\usepackage{makeidx}
\makeindex
\usepackage{xindex}
\begin{document}

\index{foo}foo and
\writeidx{\clearpage}
\index{bar}bar

\printindex
\end{document} 
\end{verbatim}


Such commands are then taken into account by the program \Lprog{xindex}. With the often used program \Lprog{makeindex}
such commands are ignored. In the following example we put an horizontal line after the first entry:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
%  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
%StartVisiblePreamble
\usepackage{xindex}
\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\makeatletter
\def\theindex{%    only for demonstration
  \newpage
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\begin{document}
\index{foo}foo and
\writeidx{\item\protect\hrulefill}
\index{bar}bar
\index{gex}gex
\printindex
\end{document}
\end{externalDocument}


\section{Headings}
By default the output uses the English headings: \textit{Symbols}, \textit{Numbers}, and \textit{A} \ldots
There are three predefined languages \texttt{en}, \texttt{de}, and \texttt{fr}. The definition is in the file
\Lfile{xindex-cfg-common.lua} (see also section \vref{language}).
%
It can easily be extended for other \Index{language}s. Sometimes the headers are not needed, for example in a name
list. With the optional argument \verb=-n= or \verb=--noheadings= the created \Lext{ind} file has only
the vertical space between different first letters:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={5},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-n,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
Ein foo\index{foo}\index{bar|(}
 \newpage und \index{foo} 
ein foo\index{foo|textit} \newpage 
und foo\index{foo|textbf} \newpage 
und foo\index{foo|fbox}
\index{bar|)}
\newpage
\verb|xindex -n <file>|
\printindex
\end{document}
\end{externalDocument}


The headings are printed by default as \Lcs{textbf}. This can be changed in the config file 
by setting the
variable \texttt{idxnewletter}, for example: \verb|idxnewletter = "\\textit"|. If you need some
more code here then define an own  macro for it, which can be seen in the following example. It has
an own config file \Lfile{xindex-header.lua} which has the line

\verb|idxnewletter = "\\idxnewletter"|


\clearpage


In the documents preamble there is the definition:

\verb|\newcommand\idxnewletter[1]{\textbf{\textit{#1}}}|




\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.6\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex,
  crop,
  xindex,
  xindexOptions=-c header,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex
\documentclass{scrartcl}
\begin{filecontents}[force,noheader]{xindex-header.lua}
-----------------------------------------------------------------------
--         FILE:  xindex-header.lua
--  DESCRIPTION:  configuration file for xindex.lua
-- REQUIREMENTS:  
--       AUTHOR:  Herbert Voß
--      LICENSE:  LPPL1.3
-----------------------------------------------------------------------

if not modules then modules = { } end modules ['xindex-header'] = {
      version = 0.20,
      comment = "main configuration to xindex.lua",
       author = "Herbert Voss",
    copyright = "Herbert Voss",
      license = "LPPL 1.3"
}

itemPageDelimiter = ","     -- Hello, 14
compressPages     = true    -- something like 12--15, instead of 12,13,14,15. the |( ... |) syntax is still valid
fCompress	  = true    -- 3f -> page 3, 4 and 3ff -> page 3, 4, 5
minCompress       = 3       -- 14--17 or 
rangeSymbol       = "--"
numericPage       = true    -- for non numerical pagenumbers, like "VI-17"
sublabels         = {"", "-\\,", "--\\,", "---\\,"} -- for the (sub(sub(sub-items  first one is for item
pageNoPrefixDel   = ""     -- a delimiter for page numbers like "VI-17"  -- not used !!!
indexOpening      = ""     -- commands after \begin{theindex}
idxnewletter      = "\\idxnewletter"
envStart          = "\\begin{theindex}"  
envStop           = "\\end{theindex}"

--[[
    Each character's position in this array-like table determines its 'priority'.
    Several characters in the same slot have the same 'priority'.
]]
alphabet_lower = { --   for sorting
    { ' ' },  -- only for internal tests
    { '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', 'ž' }
}
alphabet_upper = { -- for sorting
    { ' ' },
    { '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', 'Ž' }
}
\end{filecontents}
\makeatletter
\def\theindex{%    only for demonstration
  \section*{\indexname}
  \parskip\z@ \@plus .3\p@\relax \parindent\z@
  \let\item\@idxitem}
\makeatother
\pagestyle{empty}
%StartVisiblePreamble
\usepackage{makeidx}\makeindex
\newcommand\idxnewletter[1]{\textbf{\textit{#1}}}
%StopVisiblePreamble
\begin{document}
\section{Escaping characters}
\begin{itemize}
\item Exclamation mark ! \index{exclaim ("!)}
\item Vertical bar| \index{Vertical bar ("|)}
\item Doublequote \verb|"| \index{""}
\item Double doublequote \verb|""| \index{""""}
\item At character @ \index{At ("@)}
\end{itemize}
run \verb|xindex -c header <file.idx>|
\index{<file.idx>@\texttt{<file.idx>}} 
\index{123}
\newpage \printindex
\end{document}
\end{externalDocument}


%\clearpage


\section{Automatic index creation}
With package \Lpack{xindex} one can define several different index files, e.\,g.
an \Index{index of names}. With the optional argument \Loption{imakeidx} the package itself loads  \Lpack{imakeidx}
and adds the program \Lprog{xindex} as the default program to  \Lpack{imakeidx}. 

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={6},
  frame=false,
  compiler=lualatex, 
  crop,
%  xindex,
%  xindexOptions=-l de,
  runs=2,code,docType=latex,
%  runsAfter=2,
%  cleanup={},
%  moveToExampleDir=false,
  shellesc,
  showFilename,
  align=\centering,
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass{scrartcl}
\usepackage{libertinus-otf}
\makeatletter
\let\ps@plain\ps@empty
\makeatother
%StartVisiblePreamble
\usepackage[imakeidx]{xindex}
\makeindex[name=persons,title=Index of names,
   columns=1,options= --noheadings]
\def\ThanhVN{Hàn Thê\protect\llap{%
  \raise 0.5ex\hbox{\'{}}}}
%StopVisiblePreamble
\pagestyle{empty}\renewcommand\thepage{}
\begin{document}
foo\index[persons]{Niepraschk,~ Rolf}
foo\index[persons]{Lamport,~ Leslie}
foo\index[persons]{Knuth,~ Donald}
foo\index[persons]{Knuth,~ Donald}
\newpage
foo\index[persons]{Lamport,~ Leslie}
foo\index[persons]{Thành,~ \ThanhVN}
foo\index[persons]{Kew,~ Jonathan}
foo\index[persons]{Kohm,~ Markus}
foo\index[persons]{Preining,~ Norbert}
\newpage
foo\index[persons]{Schenk,~ Christian}
foo\index[persons]{Feuerstack,~ Thomas}
foo\index[persons]{Tobin,~ Geoffrey}
foo\index[persons]{Wilson,~ Peter}
\newpage
foo\index[persons]{Kohm,~ Markus}
foo\index[persons]{Theiling,~ Henrik}
foo\index[persons]{Pégourié-Gonnard,~ Manuel}
foo\index[persons]{Roux,~ Élie}
\newpage
foo\index[persons]{Mittelbach,~ Frank}
foo\index[persons]{Fairbairns,~ Robin}
foo\index[persons]{Lemberg,~ Werner}
foo\index[persons]{Volovich,~ Vladimir}

\printindex[persons]
\end{document}
\end{externalDocument}


You have to run \LaTeX\  with the \verb|--shell-escape|\index{Shell escape} option to run \Lprog{xindex}
from within the \LaTeX\ document.


\section{Labels}
By default \XI creates \Index{label}s in the index for the \Index{symbols}, \Index{numbers}, and other parts (letters) to which one can refer.
with \Lcs{ref}\Largb{label}.
The labels are named \verb|L-xindex-<name>|. The prefix \verb|L| can be changed by the config file. \verb|<name>|
may be \verb|symbols|, \verb|numbers|, or \verb|A| (a letter). For example

\begin{verbatim}
\begin{theindex}
\par\textbf{Symbols}\label{L-xindex-symbols}
\nopagebreak[4]
  \item  @, \hyperpage{3}
  \item  (, \hyperpage{3}
  \item  !, \hyperpage{3}

\indexspace
\textbf{A}\label{L-xindex-A}
[...]
\end{verbatim}

The labels can be used to create a reference to a specific part in the index, for example the
letter X is in the index on page \pageref{L-xindex-X} (\Lcs{pageref}\Largb{L-xindex-X}).

With the optional argument \verb|-b| for the run of \XI one can suppress the creation of the 
labels, e.g. \verb|xindex -b -l fr ...|


\section{Demerits}
\begin{itemize}
\item For more than 5000 entries in the \Lext{idx} file the internal Lua function
for \Index{sorting} may take some time.
\item The \Lext{idx} file is not checked for \LaTeX\  errors\index{LaTeX\ errors@\LaTeX\  errors} 
in the argument of \Lcs{indexentry}.
\end{itemize}


\appendix
\section{Examples}

Correct french sorting with UCA:

\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={3},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
  xindexOptions=-l fr,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  grfOptions={width=\linewidth},
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass[paper=a4,twocolumn]{scrartcl}
\usepackage{libertinus-otf}
\let\NewPage\newpage% only for demo
\makeatletter
\renewcommand\newpage{\NewPage\let\ps@plain\ps@empty}
\makeatother
%StartVisiblePreamble
\usepackage[french]{babel}
\usepackage[imakeidx]{xindex} \makeindex
\newcommand*{\IND}[1]{\index{#1}#1\par}
%StopVisiblePreamble
\begin{document}
%%% xindex -l fr <file>
\IND{CÔTÉ} \IND{cote} \IND{Côté} \IND{COTÉ} \IND{côte} 
\IND{COTE} \IND{côté} \IND{Coté} \IND{coté} \IND{Cote} 
\IND{CÔTE} \IND{Côte} \IND{lésé} \IND{péché} 
\IND{bohème} \IND{gêné} \IND{pêche} \IND{cæsium} 
\IND{pêcher} \IND{révèle} \IND{pécher} \IND{révélé} 
\IND{Bohême} \IND{relève} \IND{PÉCHÉ} \IND{maçon} 
\IND{relevé} \IND{Élève} \IND{gêne} \IND{élevé} 
\IND{MÂCON} \IND{gène} \IND{Bohémien} \IND{caennais} 
\IND{lèse} \IND{coexistence} \IND{cœur} 
\IND{coefficient} \IND{cafard} \IND{CŒUR} \IND{CÆSIUM}
\newpage \IND{coté} \IND{cœur} \IND{péché} \newpage
\IND{coté}\IND{coefficient} \printindex
\end{document}
\end{externalDocument}




\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
%  xindex,
%  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  grfOptions={width=\linewidth},
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass[paper=a5]{scrartcl}
\usepackage{libertinus-otf}
\let\NewPage\newpage% only for demo
\makeatletter
\renewcommand\newpage{\NewPage\let\ps@plain\ps@empty}
\makeatother
%StartVisiblePreamble
\usepackage[imakeidx]{xindex}
\makeindex
% Brian Dunn
%StopVisiblePreamble
\begin{document}
First level.\index{first level}

First level second level.\index{first level!second level}

Duplicate.\index{first level!second level}

Alpha.\index{alpha}

Alpha beta.\index{alpha!beta}

Alpha beta gamma.\index{alpha!beta!gamma}

Duplicate alpha beta.\index{alpha!beta}

Duplicate alpha beta gamma.\index{alpha!beta!gamma}

\newpage
\printindex
\end{document}
\end{externalDocument}


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
%  xindex,
%  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
  grfOptions={width=\linewidth},
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass[paper=a5]{scrartcl}
\usepackage{libertinus-otf}
\let\NewPage\newpage% only for demo
\makeatletter
\renewcommand\newpage{\NewPage\let\ps@plain\ps@empty}
\makeatother
%StartVisiblePreamble
\usepackage[imakeidx]{xindex}
\makeindex[options=-l de]
% Martin Sievers
%StopVisiblePreamble
\begin{document}
Test \index{A!Test} oder auch \index{B!Test}
\newpage
\printindex
\end{document}
\end{externalDocument}


\clearpage


\begin{externalDocument}[
%  grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
  mpwidth=0.55\linewidth,
  pages={2},
  frame=false,
  compiler=lualatex, 
  crop,
  xindex,
%  xindexOptions=-l de,
  runs=2,code,docType=latex,
  showFilename,
  align=\centering,
%  grfOptions={width=\linewidth},
  lstOptions={columns=fixed}]{xindex}
%! lualatex --shell-escape
\documentclass[paper=a5]{scrartcl}
\usepackage{libertinus-otf}
\let\NewPage\newpage% only for demo
\makeatletter
\renewcommand\newpage{\NewPage\let\ps@plain\ps@empty}
\makeatother
%StartVisiblePreamble
%% Denis Bitouzé
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\begin{document}
Foo\index{foo!bar1!baz1}
Foo\index{foo!bar1!baz2}
Foo\index{foo!bar2!baz1}
Foo\index{foo!bar2!baz2}
\printindex
\end{document}
\end{externalDocument}

\printindex

\end{document}
