From fab3fa1f8c37cf7daccd8a00260c863ebe612147 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20Ke=C3=9Fler?= <git@maximilian-kessler.de>
Date: Sun, 30 Jan 2022 19:03:22 +0100
Subject: [PATCH] add symbindex package documentation

---
 doc/indexing/symbindex/.latexmkrc    |   4 +
 doc/indexing/symbindex/Makefile      |   8 ++
 doc/indexing/symbindex/symbindex.tex | 105 +++++++++++++++++++++++++++
 3 files changed, 117 insertions(+)
 create mode 100644 doc/indexing/symbindex/.latexmkrc
 create mode 100644 doc/indexing/symbindex/Makefile
 create mode 100644 doc/indexing/symbindex/symbindex.tex

diff --git a/doc/indexing/symbindex/.latexmkrc b/doc/indexing/symbindex/.latexmkrc
new file mode 100644
index 0000000..4c81cd6
--- /dev/null
+++ b/doc/indexing/symbindex/.latexmkrc
@@ -0,0 +1,4 @@
+$makeindex = "makeindex -s gind.ist %O -o %D %S";
+$clean_ext .= ' glo';
+$clean_ext .= ' hd';
+$clean_ext .= ' ins';
diff --git a/doc/indexing/symbindex/Makefile b/doc/indexing/symbindex/Makefile
new file mode 100644
index 0000000..e174370
--- /dev/null
+++ b/doc/indexing/symbindex/Makefile
@@ -0,0 +1,8 @@
+doc:
+	latexmk
+
+full:
+	latexmk -gg
+
+clean:
+	latexmk -C
diff --git a/doc/indexing/symbindex/symbindex.tex b/doc/indexing/symbindex/symbindex.tex
new file mode 100644
index 0000000..67d2f65
--- /dev/null
+++ b/doc/indexing/symbindex/symbindex.tex
@@ -0,0 +1,105 @@
+\documentclass[full]{l3doc}
+
+\title{The \pkg{mkessler-symbindex} package}
+\author{Maximilian Keßler}
+
+\usepackage{mkessler-symbindex}
+
+\begin{document}
+
+\maketitle
+
+\begin{abstract}
+  This package aims at indexing mathematical symbols properly.
+  It provides a key-value interface for declaring such symbols
+  and indexes them automatically when used.
+\end{abstract}
+
+\begin{documentation}
+
+We base our index on the \pkg{imakeidx} package.
+
+We will also only index each symbol only for its first appearance in the
+document, not congesting the index unnecessarily.
+
+\begin{function}{\DeclareSymbol}
+  \begin{syntax}
+    \cs{DeclareSymbol}\oarg{key=value list}\marg{symbol name}
+  \end{syntax}
+  This declares the command \cs{\meta{symbol name}}.
+  The behavior is controlled by the key-value list,
+  which accepts the following keys:
+
+  \begin{description}
+    \item[group = \meta{index name}]
+      Declares that this symbol will appear
+      in the \meta{index name} given.
+      If not present, the default index of the document will be used.
+
+      The index is assumed to exist.
+
+    \item[formula = \meta{formula}]
+      Controls to what formula the control sequence expands in the document
+      when called.
+      This can be any valid macro that is callable in math mode.
+      It is allowed that this macro captures additional arguments following
+      the command invocation, this will not interfere with indexing.
+
+      When not given, the \meta{formula} will just be the \meta{symbol name}
+      itself.
+
+    \item[ordered = \meta{word}]
+
+      Denotes that the symbol will be ordered alphabetically like \meta{word}
+      in the index.
+
+      When not given, the \meta{symbol name} will be used.
+
+    \item[description = \meta{text}]
+
+      Sets the description that appears in the index behind the symbol.
+
+      If not given, no description is present.
+
+    \item[operator = \meta{function}]
+
+      When \cs{\meta{symbol name}} is called,
+      this expands to the control sequence
+      \enquote{\meta{function}\{\meta{formula}\}}
+      so that the \meta{function} receives the \meta{formula}
+      as its first argument.
+
+      This can e.g.~be set to \cs{operatorname}, \cs{textbf}
+      or similar, adjusting the spacing or layouting of
+      the formula, while not influencing the ordering in the index.
+
+      When \meta{ordered = } is given yet, this is equivalent to
+      not using the \meta{operator = } and just putting this in the
+      \meta{formula = } key together.
+
+      When no \meta{operator} is given, \cs{use:n} is inserted,
+      which strips the braces around \meta{formula} and just
+      leaves formula in the input stream,
+      resulting in no effect.
+
+    \item[defaultargs = \meta{token list}]
+
+      This sets a list of tokens that will be inserted directly
+      after the invocation of \cs{\meta{symbol name}} when listing
+      the symbol in the index.
+
+      This makes it possible e.g.~to define \cs{Mod} as a formula
+      that stands for \enquote{$R$-modules} and is used as
+      \enquote{\texttt{\cs{Mod}\_R}} in the document
+      (or any other symbol that \texttt{R}, of course)
+      and list it as $\text{Mod}_R$ in the index,
+      by setting \enquote{defaultargs = \_R}.
+
+  \end{description}
+\end{function}
+  
+\end{documentation}
+
+\PrintIndex
+  
+\end{document}