\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}