diff options
author | Karl Berry <karl@freefriends.org> | 2018-12-03 22:49:28 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-12-03 22:49:28 +0000 |
commit | 510cc1b8395f714ec6c1b7299cf73371563b1a16 (patch) | |
tree | ef1d3f055e87db8e906501a88ca550b861ac22e2 /Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex | |
parent | f855360800d3dd036378f102ca41cf5fa3e87db1 (diff) |
xindex (2dec18)
git-svn-id: svn://tug.org/texlive/trunk@49312 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex | 1191 |
1 files changed, 1191 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex b/Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex new file mode 100644 index 00000000000..6450a0275fb --- /dev/null +++ b/Master/texmf-dist/doc/lualatex/xindex/xindex-doc.tex @@ -0,0 +1,1191 @@ +%% $Id: xltabular-doc.tex 635 2017-10-24 18:22:59Z herbert $ +% +\listfiles\setcounter{errorcontextlines}{100} +\documentclass[paper=a4,fontsize=11pt,DIV=13,parskip=half-, + captions=tableabove,twoside=on]{scrartcl} +\usepackage{fontspec} +\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{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} +\usepackage{xltabular} +\usepackage{dtk-logos} % for Wikipedia W +\usepackage{listings} +\usepackage{dtk-extern} % for Wikipedia W +\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}} + +%\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.05}% can be autimatically changed by perl + +\title{Program and package \texttt{xindex} \\--\\ \normalsize \xIndexVersion\ (\today)} +\author{Herbert Voß\thanks{hvoss@tug.org}} +\begin{document} +\maketitle +\tableofcontents + + +\clearpage + +\section{Introduction} +The Lua program +\XI is a \Index{unicode} aware program for creating an index 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 \Lpack{xindex} + } +\end{verbatim} + +After reading the input file the 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>| 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 + [-c,--config ] default is cfg + [-e,--escapechar ] default is " + [-n,--noheadings ] + [-o,--output ] default is <input>.ind + [-l,--language ] default is en + <input file> +\end{verbatim} + + + +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} + + +\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 four characters which must be escaped if used in the command \Lcs{index}: +\verb=!=, \verb=@=, \verb="=, or \verb=|=. These charactzers have a special meaning for +the index.\index{"!}\index{"@}\index{"|} +The default \Index{escape character} is the double quote \verb|"|: + +\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 + + +\begin{externalDocument}[ +% grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule}, + pages={1,2}, + frame, + compiler=lualatex, + crop, + xindex, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} +\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 \texttt{xindex <file.idx>}\index{<file.idx>}\index{123} +\newpage +\printindex +\end{document} +\end{externalDocument} + + +For the german language the double quote is an active character and it makes live 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). Internally the escape sequences are +now defined as: + +\begin{verbatim} +escape_chars = { -- by default " is the escape char + {esc_char..'"', '//escapedquote//', '\\"{}' }, + {esc_char..'@', '//escapedat//', '@' }, + {esc_char..'|', '//escapedvert//', "|" }, + {esc_char..'!', '//scapedexcl//', '!' } +} +\end{verbatim} + +which is, of course, not of interest for the user. With the beginning the escaped chars +are converted into the internal strings and later back to the origin meaning. + + +\begin{externalDocument}[ +% grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule}, + pages={1,2}, + frame, + compiler=lualatex, + crop, + xindex, + xindexOptions=-e ">", + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} +\section{Escaping characters with >} +\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 \texttt{xindex} with \texttt{xindex -e ">"}\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 are possible: + + +{\Japanese\small +indexheader = \{ \\ +\quad de = \{\"{}Symbole\"{}, \"{}Zahlen\"{}\},\\ +\quad en = \{\"{}Symbols\"{}, \"{}Numbers\"{}\},\\ +\quad fr = \{\"{}Symboles\"{},\"{}Chiffre\"{}\},\\ +\quad jp = \{\"{}シンボル\"{},\"{}番号\"{}\},\\ +\} +%\end{verbatim} +} + +The following example was run with \verb|xindex -l de <file>.idx|: + +\begin{externalDocument}[ +% grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule}, + pages={1,2}, + frame, + compiler=lualatex, + crop, + xindex, + xindexOptions=-l de -e ">", + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} +\section{Escaping characters with >} +\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 \texttt{xindex} with \texttt{xindex -l de -e ">"}\index{123} +\newpage +\printindex +\end{document} +\end{externalDocument} + + +\section{Sorting} + +The default sorting is unicode aware and uses a translation table for accented characters: + +\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 copy first 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', 'Á', 'À', 'Å', 'Æ'}, + { 'AE', 'Ä'}, + { 'B' }, + { 'C', 'Ç' }, + { 'D' }, + { 'E', 'È', 'È', 'Ë' }, + { 'F' }, + { 'G' }, + { 'H' }, + { 'I', 'Í', 'Ì', 'Ï' }, + { 'J' }, + { 'K' }, + { 'L' }, + { 'M' }, + { 'N', 'Ñ' }, + { 'O', 'Ó', 'Ò', 'Ø','Œ' }, + { 'OE', 'Ö' }, + { 'P' }, + { 'Q' }, + { 'R' }, + { 'S', 'Š' }, + { 'T' }, + { 'U', 'Ú', 'Ù' }, + { 'UE', 'Ü' }, + { 'V' }, + { 'W' }, + { 'X' }, + { 'Y', 'Ý', 'Ÿ' }, + { 'Z', 'Ž' } +} +\end{verbatim} + + + +\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, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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| + +\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} + + + +The same sorted with the german DIN variant 2 with \verb|--config DIN2|, which +is part of the \TeX\ distribution. In this case a letter Ö is converted to Oe before sorting +the word beginninjg with the letter Ö: + +\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, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} + + + +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-6.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-6.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, + force=false, + runs=2, + code=false, + docType=latex, + showFilename, + align=\centering, +% usefancyvrb, + lstOptions={fontfamily=helvetica}]{xindex} +\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} + + + +%\clearpage + +\section{Compressing pagenumbers}\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 = { + de = {"f", "ff"}, + en = {"f", "ff"}, + fr = {"\,sq","\,sqq"}, + jp = {"シンボル","番号"}, +} +\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, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} +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} + + + +\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, + force, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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| +\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} + + +\section{Page argument} +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 follwoing 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, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} + + + + + + +\section{The config file} + +The main config file is \Lfile{xindex-cfg.lua} is 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.lua} which can be used +with \verb|--config HAdW|. 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/| %$ +Don not forgot 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, instaead 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 +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) or (pages[1] == "") then return pages end -- only one pageno +--[[ +modify pagelist +sortPages = {{ origin = { number = VII/1-715, special = \textbf }, + sort = 07/1-00715 }, + {...} + } +]] + local sortPages = {} + +[...] + +return pages +end +\end{verbatim} + +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. + +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>| + +\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, + force, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\RequirePackage{filecontents} +\begin{filecontents*}{\jobname.idx} +\indexentry{VoßHerbert@Herbert Voß!Wasgenstraße 121\protect \\10127 Berlin\protect \\\Email {herbert"@xyz.de}}{3} +\indexentry{SieversMartin@Martin Sievers!siehe Seite~\protect \pageref {president}}{4} +\indexentry{VoßHerbert@Herbert Voß!Wasgenstraße 121\protect \\10127 Berlin\protect \\\Email {herbert"@xyz.de}}{5} +\indexentry{ZiegenhagenUwe@Uwe Ziegenhagen!Lokostr. 19 \protect \\ 20713 Köln \protect \\\Email {ziegenhagen"@mail.com}}{9} +\indexentry{BehrendtDoris@Doris Behrendt!\Email {doris"@xyz.de}}{14} +\indexentry{JacekJonas Jared@Jonas Jared Jazek!\Email {mail"@jones.net}}{20} +\indexentry{KohmMarkus@Marcus Tohm!Freiherr-von-Stein-Straße~16\protect \\ 15525~Edingen-Neckarhausen\protect \\ \Email {komascript"@xyz.info}}{24} +\indexentry{KohmMarkus@Marcus Tohm!Freiherr-von-Stein-Straße~16\protect \\ 15525~Edingen-Neckarhausen\protect \\ \Email {komascript"@xyz.info}}{31} +\indexentry{SchubertElke@Elke Schubert!Hausstraße~15\protect \\ 36396~Stutense\protect \\ \Email {elke.schubert"@kabelxyz.de}}{40} +\indexentry{FennJürgen@Jürgen Fennt!Friedrichallee 74\protect \\13233 Neu-Isenburg\protect \\\Email {juergen.fennt"@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{}\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=, + force=false, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\documentclass{article} +\makeatletter +\def\theindex{% only for demonstration + \section*{\indexname} + \parskip\z@ \@plus .3\p@\relax \parindent\z@ + \let\item\@idxitem} +\makeatother +%StartVisiblePreamble +\makeatletter +\g@addto@macro{\theindex}{% + \pagestyle{empty}% + \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} + + + + + + + + +\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 usefull to insert a +\Index{pagebreak}/""\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 --shell-escape, + crop, + xindex, + xindexOptions=-l de, + force, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\documentclass{scrartcl} +\usepackage{libertinus-otf} +%StartVisiblePreamble +\usepackage{xindex} +\makeindex +%StopVisiblePreamble +\makeatletter +\let\ps@plain\ps@empty +\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, + force, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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} + +\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 --shell-escape, + crop, + xindex, + xindexOptions=-l de, + force, + runs=2,code,docType=latex, + showFilename, + align=\centering, + lstOptions={columns=fixed}]{xindex} +\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{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} + + + + + +%\nocite{*} +%\printbibliography + + +\printindex + +\end{document} + + + +folium = { + de = {"f", "ff"}, + en = {"f", "ff"}, + fr = {"sq","sqq"}, +} |