summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/gindex/gindex.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/gindex/gindex.tex')
-rw-r--r--macros/latex/contrib/gindex/gindex.tex82
1 files changed, 62 insertions, 20 deletions
diff --git a/macros/latex/contrib/gindex/gindex.tex b/macros/latex/contrib/gindex/gindex.tex
index c240281dfd..42670dfc31 100644
--- a/macros/latex/contrib/gindex/gindex.tex
+++ b/macros/latex/contrib/gindex/gindex.tex
@@ -4,16 +4,16 @@
% 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
+% Repository: https://github.com/jbezos/gindex
%
\documentclass[a4paper]{ltxguide}
-\title{\textsf{gindex}\\\large Version 0.1}
+\title{\textsf{gindex}\\\large Version 0.2}
\author{Javier Bezos\\\texttt{http://www.texnia.com}}
-\date{2019-10-01}
+\date{2019-10-07}
\raggedright
\parskip=.8ex
@@ -42,8 +42,9 @@
{\fontsize{48}{48}\selectfont \color{notes}{gindex}\par}
{\LARGE Formatting indexes with \LaTeX\par}
\vspace*{1ex}
-Version 0.1 (2019-10-01)\par
-Javier Bezos (\texttt{http://www.texnia.com})
+Version 0.2 (2019-10-07)\par
+\texttt{https://github.com/jbezos/gindex}\par
+Javier Bezos (\texttt{http://www.texnia.com})\par
\vspace*{6ex}
@@ -53,7 +54,7 @@ the format of index entries from within \LaTeX. With standard classes,
it works out of the box with some predefined values, which you can (and
in fact should) redefine with |\renewcommand|.
-Note it is version 0.1. Changes of the existing features are unlikely
+Note it is version 0.2. Changes of the existing features are unlikely
to happen (but who knows), but new features, on the other hand, will be
added in the near future.
@@ -67,7 +68,8 @@ What it does is to generate blocks like this for each first-level entry:
\end{verbatim}
As you can see, when |\indexitem| is executed, you know the number of
-subitems, which is necessary for some styles.
+subitems, which is necessary for some styles. Subsubitems are allowed,
+but not counted. Only subitems are counted.
The default values are:
\begin{verbatim}
@@ -93,12 +95,9 @@ example will be:
This explains the line |\indexnoitem{}{}| above, which by default does
nothing. By inspecting the third parameter you decide how to format the
current parameter (of course, in most cases you must emit it again at
-the end of your definition of |\indexitem|).
+the end of your definition of |\indexitem|). See the example below.
-Subsubitems are allowed, but not counted. Only subitems are counted.
-
-
-There is a tool to define the most usual entry format, which is used in
+There is a tool to define the most usual entry format, which is uesd in
the following way:
\begin{verbatim}
\renewcommand\indexitem[2]{%
@@ -118,7 +117,8 @@ Other macros are:
\verb|\end{theindex}| (\verb|\relax| by default).
\item \verb|\indexskip|, which is \verb|\indexspace| by default,
with similar purpose.
-\item \verb|\indexheading|, is defined as follows:
+\item \verb|\indexheading|, which is added by |gindexh.ist| but no by
+|gindex.ist|, is defined as follows:
\begin{verbatim}
\newcommand\indexheading[1]{%
{\bfseries\hfil
@@ -127,15 +127,58 @@ with similar purpose.
\nopagebreak}
\end{verbatim}
\item \verb|\indexrangesep|, which by default is |-|.
+\item \verb|\indexpagessep|, which by default is |, |.
\end{itemize}
Remember to set the style to |gindex| when running \textsf{makeindex}:
\begin{verbatim}
makeindex -s gindex yourfile
\end{verbatim}
+Or if you want |\indexheading|'s to be included:
+\begin{verbatim}
+ makeindex -s gindexh yourfile
+\end{verbatim}
+
+Note also there is usually no need to run \textsf{makeindex} to fine
+tune the format.
+
+\begin{example}
+ With the following definitions, items and subitems are typeset, as
+ usual, as separate paragraphs. However, if the item has no locator,
+ and there is exactly one subitem, they are joined with a comma as
+ separator (the code is somewhat low-level):
+\begin{verbatim}
+\renewcommand\indexitem[5]{%
+ \def\next{%
+ \indexitemhang{0pt}{20pt}{:}{, }{#1}{#2}%
+ #3{#4}{#5}}%
+ \ifnum\value{indexsubitems}=1\relax
+ \ifx\\#2\\%
+ \def\next{%
+ \indexitemhang{0pt}{20pt}{:}{, }{#1, #4}{#5}}%
+ \fi
+ \fi
+ \next}
+
+\renewcommand\indexsubitem[2]{%
+ \indexitemhang{0pt}{40pt}{}{, }{--- #1}{#2}}
+\end{verbatim}
+\end{example}
+
+If an item starts with |\indexspecial|, what follows replaces the
+current item.
+\begin{example}
+With |gindex.ist|, you can generate your own headings. If you are sure
+there is nothing before |a '''| and |l '''| (actually, it can be
+anything provided it is sorted at the right place), the following two
+entries will ``group'' the items under two headings.
+\begin{verbatim}
+\index{a '''@\indexspecial\indexheading{a-k}}
+\index{l '''@\indexspecial\indexheading{l-z}}
+\end{verbatim}
+\end{example}
+
-Note also there is no need to run \textsf{makeindex} to fine tune the
-format.
\section{Internals}
@@ -148,16 +191,15 @@ The |ind| files is generated by |gindex.ist| with generic macros like:
What \textsf{gindex} does is to convert them to the above format. Some
parameters should be cuntomized in the |ist| file, however. These are:
\begin{verbatim}
-headings_flag -1
+headings_flag 0
actual '@'
quote '"'
level '!'
-page_precedence "rnaRA"
+page_precedence "rRnaA"
keyword "\\indexentry"
-delim_n ", "
\end{verbatim}
-As to |headings_flag|, the recommended way to deal with case is with
-|\indexheading|.
+As to |headings_flag|, its value is |-1| with |gindexh| and the
+recommended way to deal with case is with |\indexheading|
\end{document}