gindex (1oct19)

git-svn-id: svn://tug.org/texlive/trunk@52246 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 214 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/gindex/README.md b/Master/texmf-dist/doc/latex/gindex/README.md
new file mode 100644
index 00000000000..ab045e6f42c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gindex/README.md
@@ -0,0 +1,30 @@
+## gindex
+
+This package provides a way to generate the format of index entries from within LaTeX.
+
+What it does is to generate blocks like this for each first-level entry:
+```
+\setcounter{indexsubitems}{2}%
+\indexitem{blah1}{1}%
+  \indexsubitem{subblah1}{3}%
+  \indexsubitem{subblah2}{5}%
+\indexnoitem{}{}%
+```
+
+Then you can define `\indexitem` and the like to whatever you want.
+
+### Recent changes
+
+```
+0.1   2019-10-01
+      - First released version, with the most basic tools.
+``` 
+
+License:     MIT
+________
+Javier Bezos --- http://www.texnia.com
+
+
+
+
+
diff --git a/Master/texmf-dist/doc/latex/gindex/gindex.pdf b/Master/texmf-dist/doc/latex/gindex/gindex.pdf
new file mode 100644
index 00000000000..f2c092f75dc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gindex/gindex.pdf
diff --git a/Master/texmf-dist/doc/latex/gindex/gindex.tex b/Master/texmf-dist/doc/latex/gindex/gindex.tex
new file mode 100644
index 00000000000..c240281dfde
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/gindex/gindex.tex
@@ -0,0 +1,184 @@
+%
+% Copyright (C) 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[a4paper]{ltxguide}
+
+\title{\textsf{gindex}\\\large Version 0.1}
+
+\author{Javier Bezos\\\texttt{http://www.texnia.com}}
+
+\date{2019-10-01}
+
+\raggedright
+\parskip=.8ex
+\advance\oddsidemargin-.7cm
+\advance\textwidth2cm
+\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}
+
+\vspace*{1cm}
+{\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})
+
+\vspace*{6ex}
+
+This package works in conjunction with a \textit{\bfseries g}eneric
+\verb|ist| file, which provides a way to \textit{\bfseries g}enerate
+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
+to happen (but who knows), but new features, on the other hand, will be
+added in the near future.
+
+What it does is to generate blocks like this for each first-level entry:
+\begin{verbatim}
+  \setcounter{indexsubitems}{2}%     The number of subitems
+  \indexitem{blah1}{1}%
+    \indexsubitem{subblah1}{3}%
+    \indexsubitem{subblah2}{5}%
+  \indexnoitem{}{}%                  Usually dummy
+\end{verbatim}
+
+As you can see, when |\indexitem| is executed, you know the number of
+subitems, which is necessary for some styles.
+
+The default values are:
+\begin{verbatim}
+\newcommand\indexitem[2]{\item #1\ifx\\#2\\\else, #2\fi}
+\newcommand\indexsubitem[2]{\subitem #1\ifx\\#2\\\else, #2\fi}
+\newcommand\indexsubsubitem[2]{\subsubitem #1\ifx\\#2\\\else, #2\fi}
+\end{verbatim}
+For example, to replace the comma by a quad:
+\begin{verbatim}
+\renewcommand\indexitem[2]{\item #1\ifx\\#2\\\else\quad #2\fi}
+\end{verbatim}
+
+It is guaranteed that these command can take up to 5 arguments. If you
+define |\indexitem| with all of them, the parameters in the previous
+example will be:
+\begin{enumerate}
+  \item |blah1|
+  \item |1|
+  \item |\indexsubitem|
+  \item |subblah1|
+  \item |3|
+\end{enumerate}
+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|).
+
+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
+the following way:
+\begin{verbatim}
+\renewcommand\indexitem[2]{%
+  \indexitemhang{0pt}%       First line left margin
+                {10pt}%      Second, third...  lines left margin
+                {}%          After entry if no locator
+                {: }%        Entry-locator separator
+                {#1}%        Entry
+                {#2}}%       Locator
+\end{verbatim}
+
+Other macros are:
+\begin{itemize}
+\item \verb|\indexpreamble|, executed just after
+  \verb|\begin{theindex}| (\verb|\relax| by default).
+\item \verb|\indexpostamble|, executed before 
+  \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:
+\begin{verbatim}
+\newcommand\indexheading[1]{%
+  {\bfseries\hfil
+   \MakeUppercase{#1}%
+   \hfil}%
+  \nopagebreak}
+\end{verbatim}
+\item \verb|\indexrangesep|, 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}
+
+Note also there is no need to run \textsf{makeindex} to fine tune the
+format.
+
+\section{Internals}
+
+The |ind| files is generated by |gindex.ist| with generic macros like:
+\begin{verbatim}
+  \addindexitem{bla1}{1}
+    \addindexsubitem{subbla1}{3}
+    \addindexsubitem{subbla2}{5}
+\end{verbatim}
+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
+actual          '@'
+quote           '"'
+level           '!'
+page_precedence "rnaRA"
+keyword         "\\indexentry"
+delim_n         ", "
+\end{verbatim}
+As to |headings_flag|, the recommended way to deal with case is with
+|\indexheading|.
+
+\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.