summaryrefslogtreecommitdiff
path: root/indexing/xindex/doc/xindex-doc.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-07-17 03:03:42 +0000
committerNorbert Preining <norbert@preining.info>2023-07-17 03:03:42 +0000
commit2d6f89f83b7567136c3a40b3b55f9be1e06bd99e (patch)
tree9f4acc9c2c0e94ea2bc4626e2d2e6e6a92984ffe /indexing/xindex/doc/xindex-doc.tex
parentbfb037e9e2deef77f8837a4421b029f8298437cf (diff)
CTAN sync 202307170303
Diffstat (limited to 'indexing/xindex/doc/xindex-doc.tex')
-rw-r--r--indexing/xindex/doc/xindex-doc.tex261
1 files changed, 149 insertions, 112 deletions
diff --git a/indexing/xindex/doc/xindex-doc.tex b/indexing/xindex/doc/xindex-doc.tex
index 0c5974e046..62240e6037 100644
--- a/indexing/xindex/doc/xindex-doc.tex
+++ b/indexing/xindex/doc/xindex-doc.tex
@@ -37,7 +37,7 @@
\gdef\DoubleperCent{%%}
}
-\usepackage{xcolor,fancyvrb,varioref}
+\usepackage{xcolor,fancyvrb,varioref,awesomebox}
\usepackage{xltabular}
\usepackage{hvlogos} % for Wikipedia W
\usepackage{listings}
@@ -81,7 +81,7 @@
\def\setVersion#1{\setVVersion#1!!}
\def\setVVersion#1=#2!!{\def\xIndexVersion{#2}}
-\setVersion{version = 0.51}% can be automatically changed by perl
+\setVersion{version = 0.53}% can be automatically changed by perl
@@ -95,7 +95,8 @@
\tableofcontents
\clearpage
-\bgroup\raggedright
+\begin{noteblock}
+\raggedright
Thanks to: \\
Mark Baudoin;
Denis Bitouzé;
@@ -104,7 +105,7 @@ Brian Dunn;
Gonzalo Pesquero Serrano;
Michal Hoftich;
Mykel Kochenderfer;
-Alexey Kuznetzov;
+Alexey Kuznetsov;
Frank Mittelbach;
Peter Müller;
Heiko Oberdiek;
@@ -114,12 +115,12 @@ Florent Rougon;
Martin Sievers;
Simon Spiegel;
Jürgen Spitzmüller;
-\egroup
+\end{noteblock}
\clearpage
\section{Introduction}
The Lua program
-\XI is a \Index{unicode} aware program for creating an index file from an \Lext{idx} source
+\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)
@@ -173,30 +174,32 @@ 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 "
- [-a, --no_casesensitive ] default is false
- [-b,--no_labels ] default is false
- [-n,--noheadings ] default is false
+ [-f,--fix_hyperref ] default is false
+ [-g,--no_pagenumber] default is false
[-i,--ignoreSpace ] default is false
- [-o,--output ] default is <input>.ind
[-k,--checklang ] default ist false
[-l,--language ] default is en
- [-g,--no_pagenumber] default is false
+ [-n,--noheadings ] default is false
+ [-o,--output ] default is <input>.ind
[-p,--prefix] default L
- [-u,--use_UCA ] default is false
[-s,--use_stdin ] default is false
- [-V,--version ]
+ [-u,--use_UCA ] default is false
<files...> (default stdin) file(s)[.idx] one or more files
\end{verbatim}
For example:
-\begin{verbatim}
-xindex -q -l fr -b myDoc
-xindex -l de -c DIN2 demo1 demo2 demo3
+\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{verbatim}
+\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
@@ -211,17 +214,18 @@ xindex -c norsk -o index.ind demo1 demo2.bdx demo3.adx
It is also possible to use standard input for the index data, which needs the \verb|-s| parameter:
-\begin{verbatim}
+\begin{noteblock}\ttfamily
cat myDoc.idx | xindex -q -l fr -b -s
xindex -l de -c DIN2 < myDoc.idx
-\end{verbatim}
+\end{noteblock}
-
-The \Index{language} has to be chosen as an international abbreviation in lower- or uppercase letters, see
+\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
@@ -233,13 +237,20 @@ is given by the configuration file, which defines replacements for \Index{accent
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 characters have a special meaning for
-the index.\index{"!}\index{"@}\index{"|}
-The default \Index{escape character} is the double quote \verb|"|:
+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
+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
@@ -353,19 +364,10 @@ For the German language the double quote is an active character and it makes lif
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}
+it works for the \Index{escape character} »>« (greater). By default the expression »>!">« will
+be a \TeX\ ligature with the output »>>«. %Internally the escape sequences are
-which is, of course, not of interest for the user. With the beginning the escaped chars
+With the beginning of \Lprog{xindex }the escaped chars
are converted into the internal strings and later back to the origin 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
@@ -383,6 +385,7 @@ The following example shows how to use it:
frame,
compiler=lualatex,
crop,
+ force=true,
xindex,
xindexOptions=-e ">",
runs=2,code,docType=latex,
@@ -407,8 +410,8 @@ The following example shows how to use it:
\begin{itemize}
\item Exclamation mark ! \index{exclaim (>!)}
\item Vertical bar| \index{Vertical bar (>|)}
-\item Doublequote \verb|"| \index{>"}
-\item Double doublequote \verb|""| \index{>">"}
+\item Escapechar \verb|>| \index{>>}
+\item Double escapechar \verb|>>| \index{>>>>}
\item At character @ \index{At (>@)}
\item Group start \{ \index{\braceLeft}
\item Group end \{ \index{\braceRight}
@@ -425,9 +428,11 @@ Run \texttt{xindex} with \texttt{xindex -e ">"}\index{<file.idx>}\index{123}
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 possible:
+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"},
@@ -451,6 +456,7 @@ The following example was run with \verb|xindex -l it <file>.idx|:
frame,
compiler=lualatex,
crop,
+ force=true,
xindex,
xindexOptions=-l it -e ">",
runs=2,code,docType=latex,
@@ -471,23 +477,25 @@ The following example was run with \verb|xindex -l it <file>.idx|:
%StopVisiblePreamble
\pagestyle{empty}
\begin{document}
-\section{Escaping characters with >}
+\section{Escaping simboli con >}
\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 (>@)}
+\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}
-Run \texttt{xindex} with \texttt{xindex -l it -e ">"}\index{123}
+Initio \texttt{xindex} con \texttt{xindex -l it -e ">"}\index{123}
\newpage
\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.
+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},
@@ -495,6 +503,7 @@ the \Lfile{aux} file(s). This is only possible if package \Lpack{babel} or \Lpa
frame,
compiler=lualatex,
crop,
+ force=true,
xindex,
xindexOptions=-k -e "?",
runs=2,code,docType=latex,
@@ -510,7 +519,7 @@ the \Lfile{aux} file(s). This is only possible if package \Lpack{babel} or \Lpa
\let\item\@idxitem}
\makeatother
%StartVisiblePreamble
-\usepackage[dutch]{babel}
+\usepackage[dutch]{babel} % !!!!
\usepackage{makeidx}\makeindex
%StopVisiblePreamble
\pagestyle{empty}
@@ -519,12 +528,12 @@ the \Lfile{aux} file(s). This is only possible if package \Lpack{babel} or \Lpa
\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 (?@)}
+\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}
-\newpage
+\newpage\index{xindex@\texttt{xindex}}
\printindex
\end{document}
\end{externalDocument}
@@ -865,6 +874,9 @@ The following runs with \verb|xindex -l jp <file>|:
\end{externalDocument}
%\end{minipage}
+
+\setsansfont{Libertinus Sans}\rmfamily
+
\subsection{Sorting by using UCA (Unicode Collation Algorithm)}
With the optional argument \verb|-u| or alternatively \verb|--use_UCA| the sorting will be done
by Michal Hoftich's Lua package \texttt{LUA-UCA}, which should be part of any \TeX{} installation.
@@ -874,6 +886,20 @@ on how to do it and what languages are supported so far. Any additional code set
UCA should be don't in the file \Lfile{xindex-cfg-uca.lua}, which will automatically be read
by \Lprog{xindex}.
+\iffalse
+\begin{noteblock}
+This package can display, in a
+\begin{itemize}
+ \item to change dimensions and colors ;
+\end{itemize}
+It's
+\end{noteblock}
+\fi
+\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 not use the \verb|-u| option.
+\end{importantblock}
+
\begin{externalDocument}[
% grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
@@ -1151,8 +1177,11 @@ folium = {
crop,
xindex,
xindexOptions=-l fr,
- runs=2,code,docType=latex,
+ runs=2,
+ code,docType=latex,
showFilename,
+% runsequence={lualatex,{xindex -l fr},lualatex,lualatex},
+% shellesc=false,
align=\centering,
lstOptions={columns=fixed}]{xindex}
%! lualatex
@@ -1202,6 +1231,7 @@ of the same type, so we get \texttt{1f} in the output.
frame=false,
compiler=lualatex,
crop,
+ force=true,
xindex,
xindexOptions=-l de,
runs=2,code,docType=latex,
@@ -1263,6 +1293,7 @@ envStop = "\\end{description}"
frame=true,
compiler=lualatex,
verbose,
+ shellesc,
% xindex,
% xindexOptions=-c description -g,
runs=2,
@@ -1270,7 +1301,7 @@ envStop = "\\end{description}"
force=true,
%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}
+% runsequence={lualatex,{xindex -c description -n -g},lualatex,lualatex},
showFilename,
align=\centering,
grfOptions={width=0.45\linewidth},
@@ -1733,6 +1764,65 @@ Sorted with \verb|-l DE|
+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,
+ force=true,
+ 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
@@ -2194,7 +2284,7 @@ Test \index{A!Test} oder auch \index{B!Test}
\end{externalDocument}
-\clearpage
+%\clearpage
\begin{externalDocument}[
@@ -2231,59 +2321,6 @@ Foo\index{foo!bar2!baz2}
\end{document}
\end{externalDocument}
-The following example fixes a problem with \Lpack{hyperref} and escaping the | character
-
-
-\begin{externalDocument}[
-% grfOptions={width=\dimexpr\linewidth-2\fboxsep-2\fboxrule},
-% mpwidth=0.55\linewidth,
- pages={3},
- frame=false,
- compiler=lualatex,
- crop,
- force=true,
- 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=4, columnsep=6pt, options=--fix_hyperref]
-\usepackage[unicode]{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{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}
-
\printindex
\end{document}