Initial commit

4 files changed, 661 insertions, 0 deletions

diff --git a/macros/latex/contrib/idxcmds/README b/macros/latex/contrib/idxcmds/README
new file mode 100644
index 0000000000..b4530b0861
--- /dev/null
+++ b/macros/latex/contrib/idxcmds/README
@@ -0,0 +1,33 @@
+--------------------------------------------------------------------------
+the IDXCMDS package v0.2c 2015/08/13
+
+  create commands for adding formatted index entries
+
+--------------------------------------------------------------------------
+Clemens Niederberger
+Web:    https://bitbucket.org/cgnieder/idxcmds/
+        http://www.mychemistry.eu/forums/forum/idxcmds/
+E-Mail: contact@mychemistry.eu
+--------------------------------------------------------------------------
+Copyright 2012-2015 Clemens Niederberger
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+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.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Clemens Niederberger.
+--------------------------------------------------------------------------
+The idxcmds package consists of the files
+ - idxcmds.sty
+ - idxcmds_en.tex, idxcmds_en.pdf
+ - README
+--------------------------------------------------------------------------
+If you have any ideas, questions, suggestions or bugs to report, please
+feel free to contact me.
+--------------------------------------------------------------------------
diff --git a/macros/latex/contrib/idxcmds/idxcmds.sty b/macros/latex/contrib/idxcmds/idxcmds.sty
new file mode 100644
index 0000000000..0edfb9df9f
--- /dev/null
+++ b/macros/latex/contrib/idxcmds/idxcmds.sty
@@ -0,0 +1,308 @@
+% --------------------------------------------------------------------------
+% the IDXCMDS package
+% 
+%   create commands for adding formatted index entries
+% 
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web:    https://bitbucket.org/cgnieder/idxcmds/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2012-2015 Clemens Niederberger
+% 
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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.
+% 
+% This work has the LPPL maintenance status `maintained'.
+% 
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The idxcmds package consists of the files
+%  - idxcmds.sty
+%  - idxcmds_en.tex, idxcmds_en.pdf
+%  - README
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+\newcommand*\idxcmds@date{2015/08/13}
+\newcommand*\idxcmds@version{v0.2c}
+\newcommand*\idxcmds@description{create commands for adding formatted index entries}
+
+\ProvidesPackage{idxcmds}[\idxcmds@date\space \idxcmds@version\space
+  \idxcmds@description\space (CN)]
+\RequirePackage{etoolbox,pgfopts,ltxcmds}
+
+% --------------------------------------------------------------------------
+% message handling:
+\newcommand*\idxcmds@create@message[1]{%
+  \ifstrequal{#1}{Error}
+    {%
+      \lowercase{\csdef{@idxcmds@#1}}##1##2{%
+        \csuse{Package#1}{idxcmds}{##1}{##2}}%
+    }{%
+      \lowercase{\csdef{@idxcmds@#1}}##1{%
+        \csuse{Package#1}{idxcmds}{##1}}%
+    }}
+\idxcmds@create@message{Error}
+\idxcmds@create@message{Warning}
+\idxcmds@create@message{WarningNoLine}
+\idxcmds@create@message{Info}
+
+% --------------------------------------------------------------------------
+% package options:
+\newcommand*\idxcmds@sortsep{@}
+\newcommand*\idxcmds@subsep{!}
+\newcommand*\idxcmds@default@index{\index}
+
+\pgfkeys{
+  idxcmds/.cd,
+    sort-sep/.code = \def\idxcmds@sortsep{#1} ,
+    sub-sep/.code  = \def\idxcmds@subsep{#1} ,
+    idx-cmd/.code  = \def\idxcmds@default@index{#1}
+}
+\ProcessPgfOptions*
+
+\newrobustcmd*\setidxcmds[1]{\pgfqkeys{/idxcmds}{#1}}
+
+% --------------------------------------------------------------------------
+% a few helpers:
+\newcommand*\idxcmds@stripbs{\expandafter\@gobble\string}
+\newrobustcmd*\idxcmds@csdef[1]{\csdef{\idxcmds@stripbs#1}}
+\newcommand*\idxcmds@csuse[1]{\csuse{\idxcmds@stripbs#1}}
+\protected\def\idxcmds@appdef#1[#2]{\idxcmds@csdef{#1@idx@app}{#2}}
+\newcommand*\idxcmds@newcommand{%
+  \@ifstar
+    {\idxcmds@newcommand@star}
+    {\idxcmds@newcommand@nostar}%
+}
+\newrobustcmd*\idxcmds@newcommand@nostar[1]{%
+  \expandafter\newrobustcmd\csname\idxcmds@stripbs#1\endcsname
+}
+\newrobustcmd*\idxcmds@newcommand@star[1]{%
+  \expandafter\newrobustcmd\expandafter*\csname\idxcmds@stripbs#1\endcsname
+}
+
+% --------------------------------------------------------------------------
+% \newidxcmd[<index cmd>]{<cs>}{<formatting specs>}[<app to idx entry>]
+% new commands will have the syntax
+%   \cmd*{<text>}            => no index entry
+%   \cmd{<text>}             => index entry
+%   \cmd[<sort idx>]{<text>} => alt. sort index
+%
+
+\newrobustcmd\newidxcmd[3][\idxcmds@default@index]{%
+  \idxcmds@csdef{#2@base}##1{#3}%
+  \idxcmds@csdef{#2@idx}##1##2##3{%
+    \ifblank{##1}
+      {%
+        #1{%
+          ##2\idxcmds@sortsep
+          \idxcmds@csuse{#2@base}{##2}%
+          \idxcmds@csuse{#2@idx@app}%
+          ##3%
+        }%
+      }
+      {%
+        #1{%
+          ##1\idxcmds@sortsep
+          \idxcmds@csuse{#2@base}{##2}%
+          \idxcmds@csuse{#2@idx@app}%
+          ##3%
+        }%
+      }%
+    }%
+  \idxcmds@csdef{#2@star}##1{\idxcmds@csuse{#2@base}{##1}}%
+  \idxcmds@csdef{#2@nostar}{%
+    \ltx@ifnextchar[% ]
+      {\idxcmds@csuse{#2@nostar@opt}}
+      {\idxcmds@csuse{#2@nostar@opt}[]}%
+  }%
+  \idxcmds@csdef{#2@nostar@opt}[##1]##2{%
+    \idxcmds@csuse{#2@base}{##2}%
+    \ltx@ifnextchar@nospace[% ]
+      {\idxcmds@csuse{#2@idx@optarg}{##1}{##2}}
+      {\idxcmds@csuse{#2@idx}{##1}{##2}{}}%
+  }%
+  \idxcmds@csdef{#2@idx@optarg}##1##2[##3]{%
+    \idxcmds@csuse{#2@idx}{##1}{##2}{##3}%
+  }%
+  \newrobustcmd*#2{%
+    \@ifstar
+      {\idxcmds@csuse{#2@star}}
+      {\idxcmds@csuse{#2@nostar}}%
+  }%
+  \idxcmds@newcommand*{#2idx}[2][]{%
+    \ltx@ifnextchar@nospace[% ]
+      {\idxcmds@csuse{#2@idx@optarg}{##1}{##2}}
+      {\idxcmds@csuse{#2@idx}{##1}{##2}{}}%
+  }%
+  \ltx@ifnextchar[% ]
+    {\idxcmds@appdef{#2}}
+    {\idxcmds@appdef{#2}[]}%
+}
+
+% ---------------------------------------------------------------------------
+% \newsubmainidxcmd[<index cmd>]{<cs>}{<formatting specs>}[<app to idx entry>]
+\newrobustcmd\newsubmainidxcmd[3][\idxcmds@default@index]{%
+  \idxcmds@csdef{#2@base}##1{#3}%
+  \idxcmds@csdef{#2@idx}##1##2##3##4{%
+    \ifblank{##1}
+      {%
+        #1{%
+          ##3\idxcmds@subsep##2\idxcmds@sortsep
+          \idxcmds@csuse{#2@base}{##2}%
+          \idxcmds@csuse{#2@idx@app}%
+          ##4%
+        }%
+      }{%
+        #1{%
+          ##3\idxcmds@subsep##1\idxcmds@sortsep
+          \idxcmds@csuse{#2@base}{##2}%
+          \idxcmds@csuse{#2@idx@app}%
+          ##4%
+        }%
+      }%
+    }%
+  \idxcmds@csdef{#2@star}##1{\idxcmds@csuse{#2@base}{##1}}%
+  \idxcmds@csdef{#2@nostar}{%
+    \ltx@ifnextchar[% ]
+      {\idxcmds@csuse{#2@nostar@opt}}
+      {\idxcmds@csuse{#2@nostar@opt}[]}%
+  }%
+  \idxcmds@csdef{#2@nostar@opt}[##1]##2##3{%
+    \idxcmds@csuse{#2@base}{##2}%
+    \ltx@ifnextchar@nospace[% ]
+      {\idxcmds@csuse{#2@idx@optarg}{##1}{##2}{##3}}
+      {\idxcmds@csuse{#2@idx}{##1}{##2}{##3}{}}%
+  }%
+  \idxcmds@csdef{#2@idx@optarg}##1##2##3[##4]{%
+    \idxcmds@csuse{#2@idx}{##1}{##2}{##3}{##4}%
+  }%
+  \newrobustcmd*#2{%
+    \@ifstar
+      {\idxcmds@csuse{#2@star}}
+      {\idxcmds@csuse{#2@nostar}}%
+  }%
+  \idxcmds@newcommand*{#2idx}[3][]{%
+    \idxcmds@csuse{#2@idx}{##1}{##2}{##3}%
+  }%
+  \ltx@ifnextchar[% ]
+    {\idxcmds@appdef{#2}}
+    {\idxcmds@appdef{#2}[]}%
+}
+
+% ---------------------------------------------------------------------------
+% \newsubidxcmd[<index cmd>]{<cs>}{<idx cmd>}{<formatting specs>}[<app to idx entry>]
+% \newsubidxcmd*[<index cmd>]{<cs>}{<main entry>}{<formatting specs>}[<app to idx entry>]
+\newbool{idxcmds@sub@star}
+
+% get main if starred
+\newrobustcmd*\idxcmds@extract@main[2]{%
+  \ltx@ifnextchar[% ]
+    {\idxcmds@extract@main@aux{#1}{#2}}
+    {\idxcmds@extract@main@aux{#1}{#2}[]}%
+}
+\protected\def\idxcmds@extract@main@aux#1#2[#3]#4{%
+  \idxcmds@csdef{#1@main}{\idxcmds@csuse{#2@base}{#4}}%
+  \ifstrempty{#3}
+    {\idxcmds@csdef{#1@main@sort}{#4}}
+    {\idxcmds@csdef{#1@main@sort}{#3}}%
+}
+
+\newcommand*\newsubidxcmd{%
+  \@ifstar
+    {\booltrue{idxcmds@sub@star}\idxcmds@subidx}
+    {\boolfalse{idxcmds@sub@star}\idxcmds@subidx}%
+}
+\newrobustcmd\idxcmds@subidx[4][\idxcmds@default@index]{%
+  \idxcmds@csdef{#2@base}##1{#4}%
+  \ifbool{idxcmds@sub@star}{%
+    \idxcmds@extract@main#2#3%
+    \idxcmds@csdef{#2@idx}##1##2##3{%
+      \ifblank{##1}
+        {%
+          #1{%
+            \idxcmds@csuse{#2@main@sort}\idxcmds@sortsep
+            \idxcmds@csuse{#2@main}%
+            \idxcmds@subsep##2\idxcmds@sortsep
+            \idxcmds@csuse{#2@base}{##2}%
+            \idxcmds@csuse{#2@idx@app}%
+            ##3%
+          }%
+        }{%
+          #1{%
+            \idxcmds@csuse{#2@main@sort}\idxcmds@sortsep
+            \idxcmds@csuse{#2@main}%
+            \idxcmds@subsep##1\idxcmds@sortsep
+            \idxcmds@csuse{#2@base}{##2}%
+            \idxcmds@csuse{#2@idx@app}%
+            ##3%
+          }%
+        }%
+    }%
+  }{%
+    \idxcmds@csdef{#2@idx}##1##2##3{%
+      \ifblank{##1}
+        {%
+          #1{%
+            #3%
+            \idxcmds@subsep##2\idxcmds@sortsep
+            \idxcmds@csuse{#2@base}{##2}%
+            \idxcmds@csuse{#2@idx@app}%
+            ##3%
+          }%
+        }{%
+          #1{%
+            #3%
+            \idxcmds@subsep##1\idxcmds@sortsep
+            \idxcmds@csuse{#2@base}{##2}%
+            \idxcmds@csuse{#2@idx@app}%
+            ##3%
+          }%
+        }%
+    }%
+  }%
+  \idxcmds@csdef{#2@star}##1{\idxcmds@csuse{#2@base}{##1}}%
+  \idxcmds@csdef{#2@nostar}{%
+    \ltx@ifnextchar[% ]
+      {\idxcmds@csuse{#2@nostar@opt}}
+      {\idxcmds@csuse{#2@nostar@opt}[]}%
+  }%
+  \idxcmds@csdef{#2@nostar@opt}[##1]##2{%
+    \idxcmds@csuse{#2@base}{##2}%
+    \ltx@ifnextchar@nospace[% ]
+      {\idxcmds@csuse{#2@idx@optarg}{##1}{##2}}
+      {\idxcmds@csuse{#2@idx}{##1}{##2}{}}%
+  }%
+  \idxcmds@csdef{#2@idx@optarg}##1##2[##3]{%
+    \idxcmds@csuse{#2@idx}{##1}{##2}{##3}%
+  }%
+  \newrobustcmd*#2{%
+    \@ifstar
+      {\idxcmds@csuse{#2@star}}
+      {\idxcmds@csuse{#2@nostar}}%
+  }%
+  \idxcmds@newcommand*{#2idx}[2][]{%
+    \idxcmds@csuse{#2@idx}{##1}{##2}%
+  }%
+  \ltx@ifnextchar[% ]
+    {\idxcmds@appdef{#2}}
+    {\idxcmds@appdef{#2}[]}%
+}
+
+\endinput
+% --------------------------------------------------------------------------
+% HISTORY:
+2012/11/02 v0.1  - first working version
+2013/04/11 v0.1a - made \newidxcmd, \newsubmainidxcmd and \newsubidxcmd robust
+2013/04/16 v0.2  - added trailing optional argument to defined commands
+                   that allows appending stuff to the index entry at use-time
+2013/05/14 v0.2a - added \setidxcmds
+2013/08/31 v0.2b - added option `idx-cmd'
+2015/08/13 v0.2c - removed spurious space, minor code changes
diff --git a/macros/latex/contrib/idxcmds/idxcmds_en.pdf b/macros/latex/contrib/idxcmds/idxcmds_en.pdf
new file mode 100644
index 0000000000..77b42555e2
--- /dev/null
+++ b/macros/latex/contrib/idxcmds/idxcmds_en.pdf
diff --git a/macros/latex/contrib/idxcmds/idxcmds_en.tex b/macros/latex/contrib/idxcmds/idxcmds_en.tex
new file mode 100644
index 0000000000..5a1c0218c6
--- /dev/null
+++ b/macros/latex/contrib/idxcmds/idxcmds_en.tex
@@ -0,0 +1,320 @@
+% arara: pdflatex
+% arara: biber
+% arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the IDXCMDS package
+% 
+%   create commands for adding formatted index entries
+% 
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web:    http://www.mychemistry.eu/forums/forum/idxcmds/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2012-2015 Clemens Niederberger
+% 
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% 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.
+% 
+% This work has the LPPL maintenance status `maintained'.
+% 
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The idxcmds package consists of the files
+%  - idxcmds.sty
+%  - idxcmds_en.tex, idxcmds_en.pdf
+%  - README
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+\documentclass[load-preamble,add-index,scrartcl={DIV10}]{cnltx-doc}
+\usepackage[utf8]{inputenc}
+\usepackage{idxcmds}
+\setcnltx{
+  package  = {idxcmds} ,
+  authors  = Clemens Niederberger ,
+  email    = contact@mychemistry.eu ,
+  url      = http://www.mychemistry.eu/forums/forum/idxcmds/ ,
+  abstract = {%
+    create commands for adding formatted index entries%
+  } ,
+  add-cmds = {
+    newidxcmd,newsubidxcmd,newsubmainidxcmd
+  } ,
+  add-silent-cmds = {
+    acr,environ,file,hsnbg,KOMAScript,scientist,test,@ifstar,
+    cmd,cmd@base,cmd@idx,cmd@nostar,cmd@star,
+    indexentry
+  } ,
+  index-setup = { othercode=\footnotesize,noclearpage } ,
+  makeindex-setup = { columns=3, columnsep=1em , intoc , title=Package Index }
+}
+\usepackage{imakeidx}
+\makeindex[name=environments,title=Index of Environments,intoc,columns=2]
+\makeindex[name=\jobname-examples,title=Index of Examples,intoc,columns=3]
+
+\usepackage[
+backend=biber,
+style=cnltx,
+sortlocale=en_US,
+indexing=cite,
+useprefix]{biblatex}
+\addbibresource{cnltx.bib}
+
+\defbibheading{bibliography}{\addsec{References}}
+\usepackage{csquotes}
+
+\usepackage[biblatex]{embrac}[2012/06/29]
+\ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+
+% \setidxcmds{idx-cmd=\index[\jobname-examples]}
+
+\newidxcmd[{\index[\jobname-examples]}]\acr{\textsc{#1}}
+\newidxcmd[{\index[environments]}]\environ{\texttt{#1}}[ (Environment)]
+\newidxcmd[{\index[\jobname-examples]}]\scientist{\textsf{#1}}
+\newsubmainidxcmd[{\index[\jobname-examples]}]\file{\textsf{#1}}
+\newsubidxcmd[{\index[\jobname-examples]}]\test{Test}{\textcolor{red}{#1}}
+\newsubidxcmd*[{\index[\jobname-examples]}]\hsnbg{\scientist[Heisenberg]{Werner Heisenberg}}{#1}
+
+\begin{document}
+
+\section{Licence and Requirements}\label{sec:license}
+\license
+
+\idxcmds\ loads and needs the the packages \pkg{etoolbox}~\cite{pkg:etoolbox},
+\pkg{pgfopts}~\cite{pkg:pgfopts} and \pkg{ltxcmds}~\cite{pkg:ltxcmds}.
+
+\section{Motivation}
+When working on a larger document and designing and writing the macros for
+various bits and pieces I was going to use I found myself repeatedly writing
+the same kind of macros again and again that had some kind of semantic
+meaning, maybe some markup definitions that also created an index entry and
+had a star form for omitting the index entry.  They all had more or less the
+following structure:
+
+\begin{sourcecode}
+  \makeatletter
+  \newcommand*\cmd{\@ifstar\cmd@star\cmd@nostar}
+  \newcommand*\cmd@star[1]{\cmd@base{#1}}
+  \newcommand*\cmd@nostar[1]{\cmd@base{#1}\cmd@idx{#1}}
+  \newcommand*\cmd@base[1]{\textit{#1}}
+  \newcommand*\cmd@idx[1]{\index{#1@\cmd@base{#1}}}
+  \makeatother
+\end{sourcecode}
+
+After having copied and pasted this code for the fourth time I thought: you
+should have a command that does this for you.  That was when \cs{newidxcmd}
+was born.  This command soon enough got some extensions, \eg, giving
+the commands thus defined an optional argument that allowed specifying the
+sorting.  It wasn't long before I realized that I might want to use this
+\cs{newidxcmd} again in other documents which was when I wrote the first
+draft of this package.
+
+I added other commands, \cs{newsubmainidxcmd} and \cs{newsubidxcmd}, which I
+didn't (and still don't) really use or need but of which I thought they could
+be useful for others, and here we are.
+
+\section{Usage}\label{sec:usage}
+\subsection{Available Commands}
+\idxcmds\ provides these commands:
+\begin{commands}
+  \command{newidxcmd}[\oarg{index cs}\marg{cs}\marg{formatting specs}\oarg{append}]
+    Defines a command \meta{cs} that formats its argument according to
+    \meta{formatting specs} and creates an index entry with \meta{index cs}
+    that gets \meta{append} appended.  Refer to the argument of \meta{cs}
+    in \meta{formatting specs} with \code{\#1}.
+    
+    Also defines a command \cs*{\meta{cs}idx} that allows to only create an
+    index entry.  See section~\ref{sec:command:usage:newidxcmd} for examples
+    and further description of its functionality.  Default for \meta{index cs}
+    is \cs{index}.
+  \command{newsubidxcmd}[\sarg\oarg{index cs}\marg{cs}\marg{main
+    entry}\marg{form. specs}\oarg{append}]
+    Defines a command \meta{cs} that formats its argument according to
+    \meta{form. specs} and creates an index sub-entry to \meta{main entry}
+    with \meta{index cs} that gets \meta{append} appended.  Refer to the
+    argument of \meta{cs} in \code{form.\@ specs} with \code{\#1}.
+    
+    Also defines a command \cs*{\meta{cs}idx} that allows to only create an
+    index entry.  See section~\ref{sec:command:usage:newsubidxcmd} for further
+    description of its functionality. Default for \meta{index cs} is
+    \cs*{index}.
+  \command{newsubmainidxcmd}[\oarg{index cs}\marg{cs}\marg{form. specs}\oarg{append}]
+    Defines a command \meta{cs} that formats its argument according to
+    \meta{form. specs} and creates an index sub-entry to a main entry with
+    \meta{index cs} that gets \meta{append} appended.  Refer to the argument
+    of \meta{cs} in \meta{form. specs} with \code{\#1}.
+    
+    Also defines a command \cs*{\meta{cs}idx} that allows to only create an
+    index entry.  The main entry is specified at use time. See
+    section~\ref{sec:command:usage:newsubmainidxcmd} for examples and further
+    description of its functionality. Default for \meta{index cs} is
+    \cs*{index}.
+\end{commands}
+
+The commands \meta{cs} defined this way are robust but their formatting
+argument is not placed in a group.  Keep this in mind when you use
+\cs*{bfseries} or something in a definition.  \meta{cs} will be defined using
+\pkg{etoolbox}' \cs*{newrobustcmd} which means an error will be thrown if
+\meta{cs} is already defined.
+
+Of course these commands cannot cover all possible use cases for index entries
+but that is not the intention of this package, anyway.
+
+\subsection{Command Usage}\label{sec:command:usage}
+\subsubsection{\cs*{newidxcmd}}\label{sec:command:usage:newidxcmd}
+The command \cs{newidxcmd}\Marg{\cs*{foo}}\marg{formatting specs} will define
+a new command \cs*{foo} with the following syntax:
+\begin{commands}
+  \command*{foo}[\sarg\marg{text}]
+    format \meta{text} according to specifications, no index entry.
+  \command*{foo}[\oarg{sort idx}\marg{text}\oarg{append}]
+    format \meta{text} according to specifications, add formatted index
+    entry, sorted according to \meta{sort idx} or, if the optional argument
+    is left out, sorted according to \meta{text}.  \meta{append} is added to
+    the index entry if the trailing optional argument is used (this can be
+    useful for instance for getting formatted page numbers).
+  \command*{fooidx}[\oarg{sort idx}\marg{text}\oarg{append}]
+    add formatted index entry, sorted according to \meta{sort idx} or, if the
+    optional argument is left out, sorted according to \meta{text}.
+    \meta{append} is added to the index entry if the trailing optional
+    argument is used.
+\end{commands}
+
+Let's see an example:
+\begin{example}
+  % in the preamble, probably:
+  % \newidxcmd{\acr}{\textsc{#1}}
+  % \newidxcmd[{\index[environments]}]{\environ}{\texttt{#1}}[ (Environment)]
+  % \newidxcmd{\scientist}{\textsf{#1}}
+  \acr{cd}, \acr{id}
+  
+  \environ{center}, \environ{flushleft}
+ 
+  \scientist*{Albert Einstein}, \scientist[Heisenberg]{Werner Heisenberg}
+\end{example}
+You will find these examples in the index of examples or the index of
+environments, respectively.  The second set of examples shows the purpose of
+the first optional argument: if you have several indexes --~like this
+documentation has for demonstration purposes~-- you might need to specify the
+index command used\footnote{This document uses
+  \pkg{imakeidx}~\cite{pkg:imakeidx} for this purpose.}.  If you want to prove
+if the example worked: \scientist*{Albert Einstein} should not be found in the
+index and \scientist*{Werner Heisenberg} should be sorted under
+\emph{Heisenberg}.  Both \environ*{center} and \environ*{flushleft} ahould be
+found in the examples index.
+
+Now let's disect the example a bit.  The uses of \cs*{acr}\Marg{cd},
+\cs*{scientist}\sarg\Marg{Albert Einstein} and \cs*{environ}\Marg{center} will
+essentially expand to
+\begin{sourcecode}
+  % \acr{cd} =>
+  \textsc{cd}\index{cd@\textsc{cd}}
+  % and in \jobname.idx =>
+  \indexentry{cd@\textsc  {cd}}{3}
+ 
+  % \scientist*{Albert Einstein} =>
+  \textsf{Albert Einstein}
+ 
+  % \environ{center} =>
+  \texttt{center}\index[environments]{center@\texttt{center} (Environment)}
+  % and in examples.idx =>
+  \indexentry{center@\texttt  {center} (Environment)}{3}
+\end{sourcecode}
+
+\subsubsection{\cs*{newsubidxcmd}}\label{sec:command:usage:newsubidxcmd}
+The command \cs{newsubidxcmd}\sarg\Marg{\cs*{foo}}\marg{main entry}\marg{form.
+  specs} will define a new command \cs*{foo} with the same syntax as
+\cs{newidxcmd} does.  However, \cs{newsubidxcmd} has an additional argument
+that specifies the main index entry this group of sub entries belongs to.  For
+the unstarred variant this argument can be some arbitrary main entry.  For the
+starred variant it demands a command plus argument defined by \cs{newidxcmd}
+as argument.
+
+\begin{example}
+  % preamble:
+  % \newsubidxcmd{\test}{Test}{\textcolor{red}{#1}}
+  % \newsubidxcmd*{\hsnbg}{\scientist[Heisenberg]{Werner Heisenberg}}{#1}
+  \scientist[Heisenberg]{Werner Heisenberg} was born in
+  \hsnbg[Wuerzburg]{W\"urzburg (Germany)}. He worked as a
+  professor in \hsnbg{Leipzig (Germany)}. And this is a
+  \test{test}.
+\end{example}
+
+\subsubsection{\cs*{newsubmainidxcmd}}\label{sec:command:usage:newsubmainidxcmd}
+The command \cs{newsubmainidxcmd}\Marg{\cs*{foo}}\marg{form. specs} will define
+a new command \cs*{foo} similar to \cs{newsubidxcmd} but where the main
+index entry is specified for every use case in the running text.  \cs*{foo}
+will have the following syntax:
+\begin{commands}
+  \command*{foo}[\sarg\marg{text}]
+    format \meta{text} according to specifications, no index entry.
+  \command*{foo}[\oarg{sort idx}\marg{text}\marg{main entry}\oarg{append}]
+    format \meta{text} according to specifications, add formatted index
+    sub-entry to the main index entry \meta{main entry}, sorted according to
+    \meta{sort idx} or, if the optional argument is left out, sorted
+    according to \meta{text}.  \meta{append} is added to the index entry if
+    the trailing optional argument is used (this can be useful for instance
+    for getting formatted page numbers).
+  \command*{fooidx}[\oarg{sort idx}\marg{text}\marg{main entry}\oarg{append}]
+    add formatted index sub-entry to the main index entry \meta{main entry},
+    sorted according to \meta{sort idx} or, if the optional argument is left
+    out, sorted according to \meta{text}.  \meta{append} is added to the
+    index entry if the trailing optional argument is used.
+\end{commands}
+
+\begin{example}
+  % in the preamble, probably:
+  % \newsubmainidxcmd{\file}{\textsf{#1}}
+  \file{article}{classes} is a standard \LaTeX{} class.
+  \file{scrartcl}{KOMA-Script@\KOMAScript} is part of the \KOMAScript{} bundle.
+  \file*{test} is a dummy.
+\end{example}
+
+\subsection{Options}
+\idxcmds\ has the following options -- either setable as package option or with
+the setup command \cs{setidxcmds}\marg{options} which takes a comma separated
+list of options:
+\begin{options}
+  \keyval{sort-sep}{symbol}\Default{@}
+    set makeindex symbol to separate the index into sorting and typesetting
+    part as specified in the index style file.
+  \keyval{sub-sep}{symbol}\Default{!}
+    set makeindex symbol to add a sub entry as specified in the index style
+    file.
+  \keyval{idx-cmd}{cs}\Default{\cs*{index}}
+    \sinceversion{0.2b}The default indexing command that is used by \idxcmds.
+\end{options}
+
+% \end{document}
+
+\printbibliography
+
+% \section{Implementation}
+% In the following code the lines 1--32 have been omitted.  They only repeat the
+% license statement which has already been mentioned in
+% section~\ref{sec:license}.
+
+% \implementation[linerange={33-1000},firstnumber=33]
+
+
+\printindex[\jobname-examples]
+
+\printindex[environments]
+
+% \indexprologue{\noindent
+%   This index has some peculiar entries in addition to the ones you would
+%   normally expect.  But actually they are the corresponding entries to the
+%   examples shown in section~\ref{sec:usage}.%
+% }
+% \printindex
+
+\end{document}