summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/keyindex/keyindex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/keyindex/keyindex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/keyindex/keyindex.dtx206
1 files changed, 206 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/keyindex/keyindex.dtx b/Master/texmf-dist/source/latex/keyindex/keyindex.dtx
new file mode 100644
index 00000000000..0a14a9035ef
--- /dev/null
+++ b/Master/texmf-dist/source/latex/keyindex/keyindex.dtx
@@ -0,0 +1,206 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2019 by Richard Zach <rzach@ucalgary.ca>
+% -------------------------------------------------------
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3c
+% of this license or (at your option) any later version.
+% The latest version of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{keyindex.sty}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{keyindex}
+%<*package>
+ [2019/04/05 1.0 Index entries by key lookup]
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{keyindex}
+\usepackage[hidelinks]{hyperref}
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{keyindex.dtx}
+ \PrintChanges
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{61}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+%
+% \changes{v1.0}{2019/04/05}{Initial version}
+%
+% \GetFileInfo{keyindex.sty}
+%
+% \DoNotIndex{\newcommand,\newenvironment}
+%
+% \title{The \textsf{keyindex} package\thanks{This document
+% corresponds to \textsf{keyindex}~\fileversion, dated \filedate.}}
+% \author{\href{http://richardzach.org/}{Richard Zach}}
+% \date{}
+%
+% \maketitle
+%
+% \section{Introduction}
+%
+% The |keyindex| package provides functionality for producing an index
+% without directly entering index entries into the text using the
+% |\index| command, but instead by looking up short keys and printing a
+% predefined string in the main text and adding a corresponding index
+% entry. The standard use case is the production of an index of names:
+% Rather than having to write in the text, e.g.,
+% ``|Einstein\index{Einstein, Albert}|'' every time, write
+% ``|\keyindex{Einstein}|,'' which produces ``Einstein'' in the text
+% and an index entry under ``Einstein, Albert''. Of course, the
+% correct index entries must be collected somewhere.
+%
+% The package distribution also includes a bash script |makenameindex|
+% which produces a key index file for use with |keyindex| from a text
+% file with entries of the form
+% \begin{quote}
+% \meta{last name}, \meta{first name}\\
+% \meta{key}\verb+|+\meta{last name}, \meta{first name}\\
+% \meta{key}\verb+@+\meta{indexentry}
+% \end{quote}
+%
+% \section{Interactions}
+%
+% |keyindex| requires the |ifthen| package.
+%
+% \section{Usage}
+%
+% \DescribeMacro{\keyindex}
+% |\keyindex|\oarg{index option}\marg{key}
+% prints the text associated with index key \meta{key} (using the hooks
+% |\keyindexformat| and |\missingkeyindexformat|) followed by an index
+% entry for \meta{key}. The
+% index entry is generated using the hook |\keyindexcommand| and the
+% optional argument \meta{index option} is added to the argument of
+% |\keyindexcommand| after a \verb+|+. For instance,
+% |\keyindex[(]{Einstein}| might produce the same as \begin{center}
+% \verb+Einstein\index{Einstein, Albert|(}+.\end{center}
+% \DescribeMacro{\keyindexprint}
+% \DescribeMacro{\keyindexonly}
+% |\keyindexprint|\marg{key} prints only the text corresponding to
+% \meta{key}, but doesn't add anything to the index.
+% |\keyindexonly|\marg{key}\oarg{index option} only adds the index entry
+% but doesn't print anything in the text.
+%
+% \DescribeMacro{\keyindexfile} |\keyindexfile|\marg{file} will load
+% the index key definitions from \meta{file}|.kix|, which is assumed to
+% contain only a list of lines of the form \begin{center}|\keyindexentry|
+% \marg{key}\marg{print text}\marg{index text}\end{center}
+% If it is not called, |keyindex| will use
+% |\jobname.kix| as default. This must be used in the preamble.
+%
+% \DescribeMacro{\keyindexformat}
+% \DescribeMacro{\missingkeyindexformat}
+% \DescribeMacro{\keyindexcommand}
+% These are hooks to carry out the formatting in the text of the text
+% corresponding to an index entry, or adding the entry to the index.
+% They can be redefined using |\renewcommand|. By default,
+% |\keyindexformat|\marg{text} just adds \meta{text} to the document,
+% |\missingkeyindexformat|\marg{text} adds |\textbf|\marg{text}, and
+% |\keyindexcommand|\marg{text} issues |\index|\marg{text}.
+% \StopEventually{}
+% \section{Implementation}
+% \subsection{Setup}
+% \begin{macrocode}
+\RequirePackage{ifthen}
+% \end{macrocode}
+% |\keyindexfile| sets |\@keyindexfile| to its argument; we set
+% |\@keyindexfile| to default to |\jobname.kix|
+% \begin{macrocode}
+\newcommand*{\keyindexfile}[1]{%
+ \renewcommand*{\@keyindexfile}{#1}}
+\newcommand*{\@keyindexfile}{\jobname.kix}
+% \end{macrocode}
+% |\keyindexformat| formats index text;
+% default: just prints argument.
+% \begin{macrocode}
+\newcommand*{\keyindexformat}[1]{#1}
+% \end{macrocode}
+% |\missingkeyindexformat| prints index key when not defined;
+% by default, |\textbf|.
+% \begin{macrocode}
+\newcommand*{\missingkeyindexformat}[1]{%
+ \textbf{#1}}
+% \end{macrocode}
+% |\keyindexcommand|\marg{index text} adds \marg{index text} to the
+% index; by default, it does |\index|\marg{index text} but can be redefined.
+% \begin{macrocode}
+\newcommand*{\keyindexcommand}[1]{\index{#1}}
+% \end{macrocode}
+% At the beginning of the document, we read the index key definition file
+% \begin{macrocode}
+\AtBeginDocument{%
+ \InputIfFileExists{\@keyindexfile}{%
+ \PackageInfo{keyindex}{Using index key definition file
+ \@keyindexfile.}}{%
+ \PackageWarning{keyindex}{No index key definition file
+ \@keyindexfile!}}}
+% \end{macrocode}
+% |\keyindex|\oarg{index option}\marg{key} prints text for key \meta{key}, and indexes it (with
+% \verb+|+\meta{index option}, if present). Printing is done by |\keyindexprint|,
+% indexing by |\keyindexonly|. If the key is undefined, we issue a
+% warning and print the key (using |\missingkeyindexformat|), not its replacement text.
+% \begin{macrocode}
+\newcommand*{\keyindexprint}[1]{\@ifundefined{kix@e@\detokenize{#1}}{%
+ \PackageWarning{keyindex}{Index key \detokenize{#1}
+ undefined}%
+ \missingkeyindexformat{#1}}{%
+ \keyindexformat{\@nameuse{kix@e@\detokenize{#1}}}}}
+\newcommand*{\keyindexonly}[2][]{\@ifundefined{kix@e@\detokenize{#2}}{%
+ \PackageWarning{keyindex}{Index key \detokenize{#2}
+ undefined}}{%
+ \ifthenelse{\equal{#1}{}}{%
+ \keyindexcommand{\@nameuse{kix@i@\detokenize{#2}}}}{%
+ \keyindexcommand{\@nameuse{kix@i@\detokenize{#2}}|#1}}}}
+\newcommand{\keyindex}[2][]{\keyindexprint{#2}\keyindexonly[#1]{#2}}
+% \end{macrocode}
+% The file |\@keyindexfile| must contain lines of the form
+% |\keyindexentry|\marg{key}\marg{text}\marg{index entry}. It is read at
+% the beginning of the document and for each key, defines commands
+% |\kix@e@|\meta{key} and |\kix@i@|\meta{key} which evaluate to \meta{text}
+% and \meta{index entry}, respectively. Duplicate definitions are
+% ignored but generate a warning.
+% \begin{macrocode}
+\newcommand*{\keyindexentry}[3]{%
+ \@ifundefined{kix@e@\detokenize{#1}}{%
+ \@namedef{kix@e@\detokenize{#1}}{#2}%
+ \@namedef{kix@i@\detokenize{#1}}{#3}}{%
+ \PackageWarning{keyindex}{Duplicate definition for keyindex key
+ \detokenize{#1} ignored}}}
+% \end{macrocode}
+% \Finale
+% \PrintChanges
+\endinput