From 403320dd22cca2f38bae3745418df68536355c60 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 27 Sep 2019 21:29:01 +0000 Subject: esindex (27sep19) git-svn-id: svn://tug.org/texlive/trunk@52195 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/esindex/esindex.tex | 270 ++++++++++++++++++++++++ 1 file changed, 270 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/esindex/esindex.tex (limited to 'Master/texmf-dist/doc/latex/esindex/esindex.tex') diff --git a/Master/texmf-dist/doc/latex/esindex/esindex.tex b/Master/texmf-dist/doc/latex/esindex/esindex.tex new file mode 100644 index 00000000000..467d14ed4df --- /dev/null +++ b/Master/texmf-dist/doc/latex/esindex/esindex.tex @@ -0,0 +1,270 @@ +% +% Copyright (C) 1998-2019 Javier Bezos http://www.texnia.com +% +% This file may be distributed and/or modified under the conditions of +% the MIT License. A version can be found at the end of this file. +% +% Repository: https://github.com/jbezos/esindex +% + +\documentclass{article} +\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.}} + +\author{Javier Bezos\footnote{Para comentarios y sugerencias: +\texttt{http://www.texnia.com}.}} + +\raggedright +\parskip=1ex + +\date{2019-01-28} + +\begin{document} + +\maketitle + +This package defines the command \verb|\esindex| which eases writing +Spanish index entries: +\begin{verbatim} +\esindex{cañón} +\end{verbatim} +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. + +Version 1.5 provides tools for other languages and adds support for +\textsf{luatex} and \textsf{xetex}. + +\section{Spanish} + +Este paquete ha sido diseñado para facilitar la escritura de índices +correctamente alfabetizados en castellano. Su principal orden es +\verb|\esindex|, que convierte a una forma adecuada su argumento. Así +por ejemplo, +\begin{verbatim} +\esindex{cañón} +\end{verbatim} +equivale a +\begin{verbatim} +\index{can^^ffon@cañón} +\end{verbatim} +No es necesario usar \textsf{babel} salvo, lógicamente, si los acentos +están escritos en forma de abreviaciones (\verb|'a|, \verb|'e|, etc.) +en lugar de con los caracteres reales. En este último caso, el paquete +utiliza ciertas órdenes internas de \textsf{babel}, por lo que no puedo +garantizar su funcionamiento correcto con versiones distintas a las 3.6 +a 3.27. En caso de que \textsf{esindex} sea incompatible con futuras +versiones de \textsf{babel} (lo cual no es realmente probable) +intentaré adaptarlo en el menor tiempo posible. + +Salvo el carácter \verb|actual| (normalmente \verb|@|) se pueden usar +todos los caracteres especiales de \textit{MakeIndex}. Se pueden +aplicar convenciones diferentes a las normales, pero en este caso hacen +falta ajustes adicionales en caso de que los modificados sean +\verb|actual|, \verb|encap|, \verb|level| o \verb|quote|. En ese caso +basta con indicar los caracteres que hay que usar como opciones de +paquete. Por ejemplo, si para \verb|quote| decidimos usar \verb|$| en +nuestro archivo \verb|.ist| particular, tendríamos que llamar al +paquete del siguiente modo: +\begin{verbatim} +\usepackage[quote=$]{esindex} +\end{verbatim} + +Es importante observar que, a diferencia de la opción para alemán de +\textit{MakeIndex}, el uso de \verb|"| en abreviaciones como \verb|"u| +es completamente legítimo, ya que el paquete reconoce tal combinación y +la trata aparte. Lo mismo vale para \verb|'| o \verb|~| en caso de que +se usaran como carácter especial. Es decir +\begin{verbatim} +\esindex{{"!`}Cig"ue'nas{"!}|textbf} +\end{verbatim} +equivale a +\begin{verbatim} +\index{{"!`}Ciguen^^ffas{"!}@{"!`}Cig\"ue\~nas{"!}|textbf} +\end{verbatim} + +Sin embargo, el uso del carácter \verb|quote| ante \verb|encap| o +\verb|level| no se detecta a menos que el grupo esté encerrado entre +llaves. Por ejemplo, en lugar de \verb/\esindex{Pleca: "|}/ debe +escribirse \verb/\esindex{Pleca: {"|}}/. (En realidad en este caso +podría haberse usado \verb|\index|. Es tan sólo un ejemplo.) + +Aunque el hecho de que \verb|@| no se pueda usar en \verb|\esindex| +hace que todavía algunas entradas se tengan que hacer a mano, la mayor +parte del trabajo se ve considerablemente simplificado. + +Finalmente, hay que señalar que con este paquete no se crea en el +índice una entrada propia para la palabras que empiezan por eñe, sino +que tan sólo se añaden al final de la ene. En el rarísimo caso de que +hubiera palabras que empiezan por eñe habría que modificar el archivo +\verb|.ind| a mano o bien redefinir de algún modo las entradas +generadas. + +La versión 1.3 elimina una incompatibilidad con recientes versiones de +\LaTeX{} y añade nuevas funciones: +\begin{itemize} +\item Opción de paquete \verb|ignorespaces|: al formar la clave de +ordenación se suprimen los espacios, de forma que: +$$\mbox{adentro} < \mbox{a donde} = \mbox{adonde}.$$ +\item Opción de paquete \verb|replaceindex|: el comportamiento de +\verb|\index| se reemplaza por el de \verb|\esindex|, aunque en este +caso no es posible introducir entradas que no se adapten a lo +requerido por \verb|\esindex|. +\item La orden \verb|\ignorewords| da +una lista de palabras separadas por comas que no se cuentan en la +ordenación. Por ejemplo, con \verb|\ignorewords{de}| tendríamos: +$$\mbox{pino albar} < \mbox{pino laricio} < \mbox{pino de montaña}.$$ +Distingue la caja, por lo que las formas con mayúsculas hay que darlas +explícitamente, si hicieran falta. +\end{itemize} + +Algunas funciones adicionales son: +\begin{itemize} +\item La lista de tókenes \verb|\everyesindex| permite dar definiciones +locales para establecer el comportamiento de otras órdenes. Por +ejemplo: +\begin{verbatim} +\everyesindex{\renewcommand\emph[1]{#1}} +\end{verbatim} +elimina de la clave esa orden. Con: +\begin{verbatim} +\everyesindex{\renewcommand\emph[1]{#1'}} +\end{verbatim} +la entrada en cursiva iría detrás de la redonda, si la hubiera. Es una +técnica que se puede emplear en otros casos para reajustar el orden de +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 +posteriormente con \verb|ignorespaces|, \verb|\ignorewords| y +\verb|\everyesindex|, si están activadas. Por ejemplo: +\begin{verbatim} +\esindexsort{adonde}{adonde'1} +\esindexsort{adónde}{adonde'2} +\esindexsort{a donde}{a donde'7} +\esindexsort{a dónde}{a donde'8} +\end{verbatim} +daría el orden \emph{adonde, adónde, a donde, a dónde}, con +\verb|ignorespaces|, o bien \emph{a donde, a dónde,} [probablemente +otros términos], \emph{adonde, adónde}, sin \verb|ignorespaces|. +\end{itemize} + +\section{Other languages} + +First, you very likely want to ignore de Spanish specific settings with +the package option \verb|nospanish|. What \verb|\esindex| does is the +following: + +\begin{enumerate} +\item Replacements set by \verb|\esindexsort|. See an example above. + +\item \verb|\esindexreplace| in \verb|\everyesindex|. See an example +below. + +\item Replacements by \LaTeX{} (protected) expansion, including +redefinitions in \verb|\everyesindex| and, in Spanish, \verb|\`|, +\verb|\"| and \verb|\~|. You may force protected expansion at any point +inside \verb|\everyesindex| with \verb|\esindexexpandkey|. In addition, +the sort key is stored in \verb|\esindexkey|, which can be manipulated +directly. + +\item Removal of words listed in \verb|\ignoredwords| (maybe not the +logical place, but real life is not always logical). For example, with +\verb|\ignorewords{de,la}| the words “de” and “la” (preceded and +followed by spaces) are removed from the key. + +\item Removal of spaces if \verb|ignorespaces|. Very often this is +similar to the \verb|-l| option of \textit{MakeIndex}. + +\item Replacement of `actual' as set by \verb|\esindexactual|, but +still based on the original \verb|\esindex| argument, without changes. +For example, with: +\begin{verbatim} +\esindexactual{Felipe II}{Felipe II, \textit{rey de España}} +\end{verbatim} +just write \verb|\esindex{Felipe II}| (as many times as you want), and +the entry will show “Felipe II, \textit{rey de España}” (the sort key +is still based on “Felipe II”, of course). + +\end{enumerate} + +Do you find it chaotic? Well, you are right. After all this package is +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. + +Here is an example of an \verb|\everyesindex|. Like other +\verb|\every...|'s, it is a token register: +\begin{verbatim} +\everyesindex{% + \renewcommand\"[1]{#1e}% + \renewcommand\textit[1]{#1}% + \esindexexpandkey + \esindexreplace{ä}{ae}% + \esindexreplace{ü}{ue}% + \esindexreplace{ö}{oe}} +\end{verbatim} + +What it does is: +\begin{enumerate} +\item Redefines \verb|\textit| so that it is removed to build the key. +With \verb|\everyesindex{\renewcommand\textit[1]{#1'}}| italics would +be sorted after upright. + +\item Redefines \verb|\"|. Of course, this only works correctly if used +for this precise expansion. + +\item Applies the previous changes with a protected expansion. + +\item Make a direct replacement of some characters. + +\end{enumerate} +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 +\textsf{iflang}). + +As a convenience tool, \verb|\esindexlastchar| is \verb|^^ff| or +\verb|^^^^ffff|, depending on the engine. + +\end{document} + +MIT License +----------- + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -- cgit v1.2.3