summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/idxcmds
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/idxcmds
Initial commit
Diffstat (limited to 'macros/latex/contrib/idxcmds')
-rw-r--r--macros/latex/contrib/idxcmds/README33
-rw-r--r--macros/latex/contrib/idxcmds/idxcmds.sty308
-rw-r--r--macros/latex/contrib/idxcmds/idxcmds_en.pdfbin0 -> 409095 bytes
-rw-r--r--macros/latex/contrib/idxcmds/idxcmds_en.tex320
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
Binary files differ
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}