summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-09-30 21:50:14 +0000
committerKarl Berry <karl@freefriends.org>2019-09-30 21:50:14 +0000
commitac5265994eff929bf5acbbe5447272453dfe250b (patch)
treea59380bd4d403f5a55d130e5e151c8542edbb58a /Master/texmf-dist/doc
parent0c7873f9ffd7192fe2ad9c08c8f3a42bb7b9d71b (diff)
esindex (30sep19)
git-svn-id: svn://tug.org/texlive/trunk@52226 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/esindex/README.md29
-rw-r--r--Master/texmf-dist/doc/latex/esindex/esindex.pdfbin210647 -> 61713 bytes
-rw-r--r--Master/texmf-dist/doc/latex/esindex/esindex.tex132
3 files changed, 136 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/latex/esindex/README.md b/Master/texmf-dist/doc/latex/esindex/README.md
index df626eab5fc..a2b357cd576 100644
--- a/Master/texmf-dist/doc/latex/esindex/README.md
+++ b/Master/texmf-dist/doc/latex/esindex/README.md
@@ -1,8 +1,35 @@
+## esindex
Generates automatically sort keys. Originally only for Spanish, but
version 1.5 provides tools for it to be adapted to other languages, so
-that, for example, \esindex{\textit{Höhe}} can be made equivalent to
+that, for example,
+```
+\esindex{\textit{Höhe}}
+```
+can be made equivalent to
+```
\index{Hoehe@\textit{Höhe}}
+```
+
+This package is based on the principle that sort keys should be
+generated in most cases in the context where the entry appears
+in the document.
+
+### Recent changes
+
+```
+1.6 2019-09-30
+ - Package option 'babel', which wraps each entry not in the main
+ language with \foreignlanguage (or other macro).
+
+1.5 2019-01-28
+ - Macro \esindexactual, to replace all ocurrences of an entry
+ with a new text.
+ - Package option 'nospanish', for it to be adapted to other
+ languages.
+ - \esindexreplace, \esindexlastchar, \esindexkey now work with
+ xe/lua.
+```
License: MIT
________
diff --git a/Master/texmf-dist/doc/latex/esindex/esindex.pdf b/Master/texmf-dist/doc/latex/esindex/esindex.pdf
index f94fd894349..d1e0de5e5f2 100644
--- a/Master/texmf-dist/doc/latex/esindex/esindex.pdf
+++ b/Master/texmf-dist/doc/latex/esindex/esindex.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/esindex/esindex.tex b/Master/texmf-dist/doc/latex/esindex/esindex.tex
index 467d14ed4df..a654b2aa8d5 100644
--- a/Master/texmf-dist/doc/latex/esindex/esindex.tex
+++ b/Master/texmf-dist/doc/latex/esindex/esindex.tex
@@ -7,31 +7,60 @@
% Repository: https://github.com/jbezos/esindex
%
-\documentclass{article}
+\documentclass[a4paper]{ltxguide}
+
\usepackage[english,spanish]{babel}
\spanishdatedel
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
-\title{Paquete \textsf{esindex}\footnote{Este
- archivo est\'a actualmente en la versión 1.5
- con fecha 2019-01-28.
- Esta copia del manual se compuso el~\today.}}
+\title{\textsf{esindex}\\\large 1.6\quad 2019-09-30}
-\author{Javier Bezos\footnote{Para comentarios y sugerencias:
-\texttt{http://www.texnia.com}.}}
+\author{Javier Bezos}
\raggedright
-\parskip=1ex
-
-\date{2019-01-28}
+\parskip=.8ex
+\advance\oddsidemargin-.7cm
+\advance\textwidth1.8cm
+\addtolength{\textheight}{3.5cm}
+\addtolength{\topmargin}{-2cm}
+
+\usepackage{xcolor,bera}
+
+\definecolor{notes}{rgb}{.75, .3, .3}%
+
+\makeatletter
+\def\@begintheorem#1#2{%
+ \list{}{}%
+ \global\advance\@listdepth\m@ne
+ \item[{\sffamily\bfseries\color{notes}\MakeUppercase{#1}}]}%
+\makeatother
+\newtheorem{warning}{Warning}
+\newtheorem{note}{Note}
+\newtheorem{example}{Example}
\begin{document}
-\maketitle
+\vspace*{1cm}
+{\fontsize{48}{48}\selectfont \color{notes}{esindex}\par}
+{\LARGE Generating automatically sort keys for \textit{MakeIndex}
+with \LaTeX\par}
+\vspace*{1ex}
+Version 1.6 (2019-09-30)\par
+Javier Bezos (\texttt{http://www.texnia.com})
+
+\vspace*{6ex}
+
+{\small\itshape Please, report any issues you find in
+ \texttt{https://github.com/jbezos/esindex/issues}.\par}
+
+This package defines the command \verb|\esindex|, which adds sort keys
+to the index entries for you. Although originally a specifically Spanish
+tool (so part of the documentation is in Spanish), the idea behind this
+package may be applied to other languages, and tools to adapt it are
+provided. They are explained below, section 2.
-This package defines the command \verb|\esindex| which eases writing
-Spanish index entries:
+So,
\begin{verbatim}
\esindex{cañón}
\end{verbatim}
@@ -39,17 +68,24 @@ is equivalent to
\begin{verbatim}
\index{can^^ffon@cañón}
\end{verbatim}
-As you can see, the package generates the sort key within \TeX{}
-itself, which has a number of advantages.
-Although it is a specifically Spanish tool (so most of the
-documentation is in Spanish), the idea behind this package may be
-applied to other languages, and tools to adapt it are provided, too.
-They are explained below.
+\verb|\index| is not touched at all (except if requested with the package
+option \verb|replaceindex|).
+
+As you can see, the package generates the sort key within \TeX{}
+itself, which has a number of advantages (and some disadvantages, of
+course).
Version 1.5 provides tools for other languages and adds support for
\textsf{luatex} and \textsf{xetex}.
+Version 1.6 adds a package option -- with \verb|babel| the `actual' value
+(ie, the text to be printed in the index) is wrapped with
+\verb|\foreignlanguage| if the current language is not the main one
+(this replacement comes after \verb|\esindexactual|). Actually, the
+macro is \verb|\esindexlanguage|, which by default is `let' to the
+\textsf{babel} macro.
+
\section{Spanish}
Este paquete ha sido diseñado para facilitar la escritura de índices
@@ -151,9 +187,9 @@ entradas idénticas.
\item La orden \verb|\esindexsort| permite predefinir claves asociadas
a entradas concretas, para ajustar su ordenación (lo que normalmente se
-consigue añadiendo texto adicional para que makeindex lo tenga en
-cuenta). Estas correspondencias deben darse antes de la aparición del
-primer \verb|\esindex| con ese término, y las claves se procesan
+consigue añadiendo texto adicional para que \textsf{makeindex} lo tenga
+en cuenta). Estas correspondencias deben darse antes de la aparición
+del primer \verb|\esindex| con ese término, y las claves se procesan
posteriormente con \verb|ignorespaces|, \verb|\ignorewords| y
\verb|\everyesindex|, si están activadas. Por ejemplo:
\begin{verbatim}
@@ -206,7 +242,7 @@ is still based on “Felipe II”, of course).
\end{enumerate}
-Do you find it chaotic? Well, you are right. After all this package is
+Do you find it chaotic? Well, you are right. After all this package was
for Spanish indexes with some readjustments for it to be adapted to
other languages. A general solution deserves another package. Feel free
to create one based on this package (MIT license), if you like.
@@ -237,14 +273,62 @@ for this precise expansion.
\item Make a direct replacement of some characters.
\end{enumerate}
+Note there is a pattern: first flatten the key by removing macros, and
+then the resulting unmarked text is processed to replace some chars.
+
Remember these changes are not shown -- they are used by
\textit{MakeIndex} to sort the entries. Note also replacements can be
-language dependent with the appropriate test (eg, with
+made language dependent with the appropriate test (eg, with
\textsf{iflang}).
As a convenience tool, \verb|\esindexlastchar| is \verb|^^ff| or
\verb|^^^^ffff|, depending on the engine.
+You can play with \textsf{lua} inside \verb|\everyesindex|, too. For
+example, to convert at once things like \textit{2,3-dimetilfenol} to
+\textit{dimetilfenol}:
+\begin{verbatim}
+\everyesindex{
+ \directlua{
+ token.set_macro('esindexkey',
+ string.gsub([[\esindexkey]], '^[-0-9,]+', ''))
+ }}
+\end{verbatim}
+
+It is just the concept (for example, it fails if the key contains
+\verb|]]|).
+
+\section{Final remarks}
+
+Indexing has many subtleties. Recommended readings are:
+\begin{itemize}
+ \item \textit{Guidelines for Alphabetical Arrangement of Letters and
+ Sorting of Numerals and Other Symbols},
+ \verb|https://www.niso.org/sites/default/files/2017-08/tr03.pdf|
+ \item \textit{Guidelines for Indexes and Related Information Retrieval
+ Devices},
+ \verb|https://www.niso.org/sites/default/files/2017-08/tr02.pdf|
+ \item \textit{Unicode Collation Algorithm},
+ \verb|https://unicode.org/reports/tr10/|,
+ \item \textit{Unicode Locale Data Markup Language (LDML)}, part 5,
+ \textit{Collation},
+ \verb|http://www.unicode.org/reports/tr35/tr35-collation.html|.
+\end{itemize}
+
+There are at least 3 tasks, from \LaTeX{} to a suitable key (eg,
+\verb|$\delta$| to \verb|delta| or whatever you want), collating these
+keys, and generate the formated index in a form \LaTeX{}
+understands.\footnote{There can be also sub-tasks. For example, the
+last task is best split in two sub-tasks, namely, first generate a
+sorted list of terms, and then format them, but unfortunately, most
+\texttt{ist} styles output a formatted list. We also need to format and
+collapse locators and so on.} With \textsf{makeindex} these 3 steps are
+intermingled, and so does \textsf{esindex}. This is another reason why
+a general solution deserves a completely new package. However, with
+some patience you can do many useful things with \textsf{esindex}, even
+sorting words in non-Latin scripts (at least, with the most basic
+rules).
+
\end{document}
MIT License