A central thing in \LaTeX is the usage of \enquote{theorems}.
With \enquote{theorems} we actually mean \enquote{environments} that typically
have a title, some style applied to their contents and are numbered throughout
the document, often later referenced by number and / or name.
Mechanisms for generating such environments are packages like
\pkg{amsthm}, \pkg{ntheorem}, \pkg{thmtools}.
While the mechanism in \pkg{thmtools} are pretty versatile and suffice
for almost all needs, it is pretty time-consuming to largely change
the behavior of environments, or have small variants of these.
This package aims at both providing a versatile mechanism, \meta{theorem group}s,
to structure theorems into groups that can subsequently easily altered,
as well as a mechanism for easily generating \meta{theorem families}.
As the author is of the opinion that of the mentioned theorem controlling packages
\pkg{thmtools} provides the most versatile interface, the \pkg{groupthm}
will be working on top of \pkg{thmtools} and use this as a backend for declaring
the \meta{theorem}s themselves.
Thus, any styles supported by \pkg{thmtools} will be supported by \pkg{groupthm}
as well, by passing them to \pkg{thmtools}.
\section{Concepts}
\subsection{Theorem groups}
\label{sec:theorem-groups}
A \meta{theorem group} is some named group holding some properties for
the \meta{theorem}s that are contained in this group.
Each \meta{theorem} can, when declared, be part of arbitrarily many \meta{theorem group}s,
and will be subject to the styles these groups defined.
This enables to group similar \meta{theorem}s and alter them at a late stage of
document development in a unique manner, by only having to change the
definition of the \meta{theorem group}, and not all \meta{theorem}s separately.
The properties. such a \meta{theorem group} can hold are as follows
\begin{description}
\item[\kw{prename}] A prefix (any \meta{token list}) that will be inserted
before the theorem name of each member of this \meta{theorem group}.
\item[\kw{postname}] A suffix (any \meta{token list}) that will be
inserted before the theorem name for each member of this \meta{theorem group}.
This could be e.g.~some \enquote{$\star$} appended to the name to indicate
variants of environments.
\item[\kw{mapname}] A \meta{function} (some macro that takes exactly one argument)
that is applied to the \kw{name}.
\item[\kw{thmtools}] A \meta{clist} of key-value pairs that are passed to the underlying
\pkg{thmtools} backend of the \meta{theorem}.
This allows e.g.~to set the \kw{topskip} of a certain class of \meta{theorem}s.
\end{description}
The most versatile key here is certainly the \kw{thmtools} key,
providing the most customization to an end user (like you).
As mentioned, each \meta{theorem} can be member of arbitrary many \meta{theorem group}s,
and will posses their corresponding properties.
To adjust finer controlling of these \meta{theorem group}s, \meta{theorem group}s can inherit from each other, and \meta{theorem group}s are subject to a hierarchy that controls precedence in case
of conflicting properties of different \meta{theorem group}s a \meta{theorem} may be part of.
This hierarchy can of course be controlled by the user.
\subsection{Theorem families}
Often, one needs some small \meta{theorem variant}s of some \meta{theorem}, the most typical
example being \vocab{starred} version of \meta{theorem}s that are not numbered
in contrast to their counterparts.
\begin{verbatim}
\begin{theorem}
This theorem is numbered.
\end{theorem}
\begin{theorem*}
This theorem is not numbered.
Probably because we do not want a reference to it.
\end{theorem*}
\end{verbatim}
\todo{insert code example output}
\pkg{groupthm} extends this idea and provides a versatile mechanism to define a
\meta{theorem family}, which is based on some \meta{theorem name} and
parses additional arguments / syntax to control the \meta{theorem groups}
that this environment is a part of.
So, in addition the name of a \meta{theorem}, the corresponding environment will
accept some options and toggle the membership of certain \meta{theorem groups},
thus further customizing its appearance.
This can lead e.g.~to usages like the following:
\begin{verbatim}
\begin{theorem}*
This theorem has a visual * at its name.
\end{theorem}
\end{verbatim}
\todo{code}
Providing this consists of two parts:
declaring the \meta{theorem family} by listing the groups that can be toggled
by this \meta{theorem family}, and declaring the actual option parsing
of the \meta{theorem family}, which then controls the membership in these groups
(and of course prior to this the definition of the desired \meta{theorem group}s).
