From c21ebb9036baa5784c2d059b7c40a00ec6a51bef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20Ke=C3=9Fler?= <git@maximilian-kessler.de>
Date: Sun, 23 Jan 2022 00:26:49 +0100
Subject: [PATCH] document public interface

---
 doc/environments/groupthm/groupthm.dtx | 227 ++++++++++---------------
 doc/environments/groupthm/groupthm.tdo |   7 +-
 2 files changed, 90 insertions(+), 144 deletions(-)

diff --git a/doc/environments/groupthm/groupthm.dtx b/doc/environments/groupthm/groupthm.dtx
index f3201ee..0841436 100644
--- a/doc/environments/groupthm/groupthm.dtx
+++ b/doc/environments/groupthm/groupthm.dtx
@@ -103,7 +103,7 @@
 % document development in a unique manner, by only having to change the
 % definition of the \mymeta{theorem group}, and not all \mymeta{theorem}s separately.
 % 
-% The properties. such a \mymeta{theorem group} can hold are as follows
+% The properties. Such a \mymeta{theorem group} can hold are as follows
 % 
 % 
 % \begin{description}
@@ -242,11 +242,11 @@
 % 
 % \begin{function}{\NewTheoremGroup, \RenewTheoremGroup, \ProvideTheoremGroup, \DeclareTheoremGroup}
 %   \begin{syntax}
-%     \cs{NewTheoremGroup}\oarg{keys}\marg{theorem group}
+%     \cs{NewTheoremGroup}\oarg{key=value list}\marg{theorem group}
 %   \end{syntax}
 %   
 %   This introduces a new \mymeta{theorem group} with the given name.
-%   The \mymeta{keys} available are the same as introduced in \autoref{sec:theorem-groups}:
+%   The \mymeta{key=value list} available are the same as introduced in \autoref{sec:theorem-groups}:
 % 
 %   \begin{description}
 %     \item
@@ -276,17 +276,19 @@
 % 
 %   \begin{texnote}
 %     The \kw{mapname} is expected to be a function of \cs{fun:n}.
-%     It is subject to an \kw{x}-type expansion prior to being passed further to \pkg{thmtools}.
+%     The function call is subject to an \kw{x}-type expansion prior
+%     to being passed further to \pkg{thmtools}.
 %   \end{texnote}
 % 
 % \end{function}
 % 
 % \subsection{Controlling theorem group precedence}
+% \label{subsec:theorem-group-precedence}
 % 
 % \begin{function}{\DeclareTheoremGroupRule}
 %     \begin{syntax}
 % \cs{DeclareTheoremGroupRule}\oarg{keyname}%
-% \marg{theorem group 1}\marg{relation}\marg{theorem group 2}
+% \marg{theorem group_1}\marg{relation}\marg{theorem group_2}
 %     \end{syntax}
 %   
 %   This declares some relation between the two theorem groups,
@@ -295,9 +297,9 @@
 % 
 %   The \mymeta{keyname} can be one of \kw{prefix}, \kw{suffix}, \kw{mapname}, \kw{thmtools}.
 %   If present, it declares the corresponding relation only for this subkey.
-%   This can lead to \mymeta{theorem group 1} overwriting \mymeta{theorem group 2} when given
-%   contradictory \pkg{thmtools} options, but the \kw{prefix} of \mymeta{theorem group 1}
-%   being applied after the one of \mymeta{theorem group 2}.
+%   This can lead to \mymeta{theorem group_} overwriting \mymeta{theorem group_2} when given
+%   contradictory \pkg{thmtools} options, but the \kw{prefix} of \mymeta{theorem group_}
+%   being applied after the one of \mymeta{theorem group_2}.
 %   When the \mymeta{keyname} is not given, this applies to all keywords.
 % 
 %   \begin{texnote}
@@ -315,13 +317,13 @@
 %   \begin{description}
 %     \item[\kw{higher} or \kw{after} or \kw{\string>}]
 %       
-%       \mymeta{theorem group 1} takes precedence over \mymeta{theorem group 2}.
-%       Its \kw{prefix} is applied after the one of \mymeta{theorem group 2}.
+%       \mymeta{theorem group_1} takes precedence over \mymeta{theorem group_2}.
+%       Its \kw{prefix} is applied after the one of \mymeta{theorem group_2}.
 % 
 %     \item[\kw{lower} or \kw{before} or \kw{\string<}]
 % 
-%       \mymeta{theorem group 2} takes precedence over \mymeta{theorem group 1}.
-%       Its \kw{prefix} is applied after the one of \mymeta{theorem group 1}.
+%       \mymeta{theorem group_2} takes precedence over \mymeta{theorem group_1}.
+%       Its \kw{prefix} is applied after the one of \mymeta{theorem group_1}.
 % 
 %   \end{description}
 % 
@@ -340,36 +342,38 @@
 % \subsection{Inheritance of theorem groups}
 % \begin{function}{\AddTheoremGroupParent}
 %   \begin{syntax}
-%     \cs{AddTheoremGroupParent}\marg{theorem group 1}\marg{theorem group 2}
+%     \cs{AddTheoremGroupParent}\marg{theorem group_1}\marg{theorem group_2}
 %   \end{syntax}
-%   Declares \mymeta{theorem group 1} to \enquote{inherit} all properties
-%   of \mymeta{theorem group 2}.
-%   In other words, \mymeta{theorem group 2} is a parent of \mymeta{theorem group 1}
+%   Declares \mymeta{theorem group_1} to \enquote{inherit} all properties
+%   of \mymeta{theorem group_2}.
+%   In other words, \mymeta{theorem group_2} is a parent of \mymeta{theorem group_1}
 %   in a usual inheritance graph.
 % 
 %   The definitions of the groups themselves are unchanged,
-%   but each new theorem defined with \mymeta{theorem group 1} will also
-%   have the properties of \mymeta{theorem group 2}.
+%   but each new theorem defined with \mymeta{theorem group_1} will also
+%   have the properties of \mymeta{theorem group_2}.
 % 
 %   Inheritance is transitive, when defining a new theorem, we just flatten out the
 %   inheritance graph and apply all properties.
 % 
-%   Inheritance is subject to the usual theorem group hierarchies as discussed in \todoref.
-%   This can even yield to situations, where \mymeta{theorem group 1} inherits
-%   from \mymeta{theorem group 2}, but \mymeta{theorem group 2} overwrites
-%   \mymeta{theorem group 1}.
+%   Inheritance is subject to the usual theorem group hierarchies as discussed in
+%   \autoref{subsec:theorem-group-precedence}.
+%   This can even yield situations, where \mymeta{theorem group_1} inherits
+%   from \mymeta{theorem group_2}, but \mymeta{theorem group_2} overwrites
+%   \mymeta{theorem group_1}.
 % \end{function}
 % 
 % \subsection{Appending to theorem groups}
 % \begin{function}{\AppendToTheoremGroup}
 %   \begin{syntax}
-%     \cs{AppendToTheoremGroup}\oarg{keys}\marg{theorem group}
+%     \cs{AppendToTheoremGroup}\oarg{key=value list}\marg{theorem group}
 %   \end{syntax}
-%   Adds the properties given as \mymeta{keys} to the theorem group.
-%   The syntax for the \mymeta{keys} is the same as in \cs{NewTheoremGroup}.
+%   Adds the properties given as \mymeta{key=value list} to the theorem group.
+%   The syntax for the \mymeta{key=value list} is the same as in \cs{NewTheoremGroup}.
 % \end{function}
 % 
 % \subsection{Default theorem groups}
+% \label{subsec:default-theorem-groups}
 % 
 % There are a number of theorem groups that \pkg{groupthm} will initially declare
 % and that have certain special treatment in some places.
@@ -444,9 +448,9 @@
 % 
 % \begin{function}{\NewGroupedTheorem, \ProvideGroupedTheorem}
 %   \begin{syntax}
-%     \cs{NewGroupedTheorem}\oarg{keys}\marg{theorem name}
+%     \cs{NewGroupedTheorem}\oarg{key=value list}\marg{grouped theorem}
 %   \end{syntax}
-%   This defines \mymeta{theorem name}  as a new theorem environment.
+%   This defines \mymeta{grouped theorem} and \meta{grouped theorem*} as new theorem environments.
 %   Its properties can be set by the following keys:
 % 
 %   \begin{description}
@@ -455,7 +459,7 @@
 % 
 %       \kw{name} $=$ \mymeta{displayed name}.
 %       If given, this is the displayed name of the environment in the document.
-%       If not present, the \mymeta{theorem name} is also used as the \mymeta{displayed name}
+%       If not present, the \mymeta{grouped theorem} is also used as the \mymeta{displayed name}
 %       in capitalized form.
 % 
 %     \item
@@ -474,55 +478,43 @@
 %       Passes these option to the \pkg{thmtools} environment that is declared internally.
 %     
 %   \end{description}
+%
+%   The \meta{grouped theorem*} behaves the same as the \meta{grouped theorem},
+%   but additionally will be a member of the \texttt{starred} theorem group,
+%   see \autoref{subsec:default-theorem-groups}.
+%   
+%   \begin{danger}
+%     If you don't wish the \meta{grouped theorem*} variant to be generated,
+%     you can pass the additional option \texttt{starred version = false}.
+%     If you are not sure about this, you are probably fine without this option.
+%   \end{danger}
+%
+% 
 % \end{function}
 % 
 % \begin{function}{\NewGroupedTheorem*,\ProvideGroupedTheorem*}
 %   \begin{syntax}
-%     \cs{NewGroupedTheorem*}\oarg{keys}\marg{theorem name}
+%     \cs{NewGroupedTheorem*}\oarg{key=value list}\marg{grouped theorem}
 %   \end{syntax}
 %   Behaves the same as \cs{NewGroupedTheorem},
-%   but also adds the theorem to the default \kw{unnumbered} group,
+%   but also adds the theorem(s) to the default \kw{unnumbered} group,
 %   thus resulting in the environment not being numbered.
 % 
 %   This is thus equivalent to using \cs{NewGroupedTheorem} and adding the
 %   \kw{unnumbered} group.
 % \end{function}
 % 
-% \begin{function}{\NewTheorem, \ProvideTheorem}
-%   \begin{syntax}
-%     \cs{NewTheorem}\oarg{keys}\marg{theorem name}
-%   \end{syntax}
-% 
-%   This behaves essentially the same as \cs{NewGroupedTheorem},
-%   but will define two grouped theorems, namely \mymeta{theorem name} and \mymeta{theorem name*}.
-% 
-%   The \mymeta{theorem name*} environment has the same properties as the \mymeta{theorem name},
-%   but will be member of the \kw{starred} theorem group.
-%   It is thus not recommended to call \cs{NewTheorem}
-%   with an actual \enquote{*} in the environment name, since both environments
-%   will be generated.
-% \end{function}
-% 
-% \begin{function}{\NewTheorem*, \ProvideTheorem*}
-%   \begin{syntax}
-%     \cs{NewTheorem}\oarg{keys}\marg{theorem name}
-%   \end{syntax}
-%   Combines the behavior of \cs{NewGroupedTheorem*} and \cs{NewTheorem}, thus
-%   declaring \mymeta{theorem} to (additionally) be member of the \kw{unnumbered}
-%   and \mymeta{theorem*} to (additionally) be member of the \kw{starred} group.
-% 
-%   As mentioned in \todoref, by default both environments will behave the same.
-% \end{function}
 % 
 % \subsection{Defining families of grouped theorems}
 % 
+%
 % \begin{function}{\NewGroupedTheoremFamily, \ProvideGroupedTheoremFamily}
 %   \begin{syntax}
-%     \cs{NewTheoremFamily}\oarg{keys}\marg{theorem name}
+%     \cs{NewTheoremFamily}\oarg{key=value list}\marg{theorem family}
 %   \end{syntax}
 % 
 %   Defines a family of grouped theorems.
-%   The \mymeta{keys} accept the same arguments as the \cs{NewGroupedTheorem} macro.
+%   The \mymeta{key=value list} accept the same arguments as the \cs{NewGroupedTheorem} macro.
 %   However, for each \emph{subset} of the given groups,
 %   a grouped theorem is defined.
 % 
@@ -530,6 +522,14 @@
 %   so we omit their actual (internal) names here.
 %   To call these, some \kw{GroupedTheoremFamilyOptions} have to specified,
 %   see \cs{NewGroupedTheoremFamilyOptions}.
+%
+%   Also, to the given groups, the \texttt{starred} group is added automatically.
+% 
+%  \begin{danger}
+%   If you do not wish the \texttt{starred} versions,
+%   you can set the key \texttt{starred version = false}.
+% \end{danger}
+%
 % \end{function}
 % 
 % \begin{function}{\NewGroupedTheoremFamily*, \ProvideGroupedTheoremFamily*}
@@ -542,23 +542,6 @@
 %   where the \kw{unnumbered} group is not present.
 % \end{function}
 % 
-% \begin{function}{\NewTheoremFamily, \ProvideTheoremFamily}
-%   This behaves essentially the same as \cs{NewGroupedTheoremFamily},
-%   but will add the \kw{starred} group to the list of groups and also generate variants
-%   for these.
-% 
-%   It is thus not recommended to call \cs{NewTheoremFamily} with the \kw{starred}
-%   group explicitly given, since this is added anyways.
-% \end{function}
-% 
-% \begin{function}{\NewTheoremFamily*, \ProvideTheoremFamily*}
-%   Combines the behavior of \cs{NewGroupedTheoremFamily*} and \cs{NewTheoremFamily}, thus
-%   declaring all variants to (additionally) be member of the \kw{unnumbered}
-%   group, and also generates definitions with and without the \kw{starred} group.
-% 
-%   As mentioned in \todoref, by default both environments will behave the same.
-% \end{function}
-% 
 % 
 % \begin{function}{\AddTheoremToGroup}
 %   \begin{syntax}
@@ -577,24 +560,25 @@
 %   \ProvideGroupedTheoremFamilyOptions, \DeclareGroupedTheoremFamilyOptions
 % }
 % \begin{syntax}
-%   \cs{NewGroupedTheoremFamilyOptions}\marg{theorem name}\marg{argument specifiation}%
+%   \cs{NewGroupedTheoremFamilyOptions}\marg{theorem family}\marg{argument specifiation}%
 %   \marg{selection body}
 % \end{syntax}
 % 
-% Defines a new environment with options, given by \mymeta{theorem name}.
+% Defines two new environment with options, given by \mymeta{theorem family}
+% and \meta{theorem family*}.
 % The \mymeta{argument specification} can be any valid \pkg{xparse} argument specification.
 % 
 % The \mymeta{selection body} is there to process the options of
-% the \mymeta{argument specification} and select which variant of the \mymeta{theorem name}
+% the \mymeta{argument specification} and select which variant of the \mymeta{theorem family}
 % to enter.
 % The arguments are available as usual with \pkg{xparse} by \kw{\#1}, \kw{\#2}, \ldots
 % 
 % The body may also call any number of \cs{AddTheoremToGroup} calls,
-% which enables the corresponding groups.
+% which the enables the corresponding groups to be toggled.
 % 
 % When the environment is called within the document, the options are parsed
 % as with \pkg{xparse} and the \mymeta{selection body} is executed.
-% Immediately after, the theorem variant of \mymeta{theorem name} with the specified groups
+% Immediately after, the theorem variant of \mymeta{theorem family} with the specified groups
 % by \cs{AddTheoremToGroup} is called.
 % 
 % At the end of the environment, the \mymeta{selection body} is executed again and the
@@ -603,6 +587,10 @@
 % The possible theorem variants that the newly declared environment will call
 % \emph{have to be generated subsequently} by a call to the \cs{NewGroupedTheoremFamily}
 % function.
+\begin{danger}
+  As always, if you do not wish the \meta{theorem family*} version to be generated,
+  you can pass \texttt{starred version = false} as an additional key.
+\end{danger}
 %   
 % \end{function}
 % 
@@ -612,7 +600,7 @@
 %     \ProvideGroupedTheoremFamilyOptions*, \DeclareGroupedTheoremFamilyOptions*
 %   }
 %   \begin{syntax}
-%   \cs{NewGroupedTheoremFamilyOptions*}\marg{theorem name}\marg{argument specifiation}%
+%   \cs{NewGroupedTheoremFamilyOptions*}\marg{theorem family}\marg{argument specifiation}%
 %   \marg{selection body}
 %   \end{syntax}
 %   
@@ -624,45 +612,6 @@
 % 
 % \end{function}
 % 
-% \begin{function}
-%   {
-%     \NewTheoremFamilyOptions, \RenewTheoremFamilyOptions,
-%     \ProvideTheoremFamilyOptions, \DeclareTheoremFamilyOptions
-%   }
-%   \begin{syntax}
-%     \cs{NewTheoremFamilyOptions}\marg{theorem name}\marg{argument specifiation}%
-%     \marg{selection body}
-%   \end{syntax}
-% 
-%   This behaves essentially the same as \cs{NewGroupedTheoremFamilyOptions},
-%   but also declares the environment \mymeta{theorem name*},
-%   which behaves the same but calls the theorem variants with the additional \kw{starred}
-%   subgroup.
-% 
-%   The possible theorem variants have to be generated with the \cs{NewTheoremFamily}
-%   command before.
-%   
-% \end{function}
-% 
-% \begin{function}
-%   {
-%     \NewTheoremFamilyOptions*, \RenewTheoremFamilyOptions*,
-%     \ProvideTheoremFamilyOptions*, \DeclareTheoremFamilyOptions*
-%   }
-%   \begin{syntax}
-%     \cs{NewTheoremFamilyOptions*}\marg{theorem name}\marg{argument specifiation}%
-%     \marg{selection body}
-%   \end{syntax}
-% 
-%   Combines the behavior of \cs{NewGroupedTheoremFamilyOptions*} and \cs{NewTheoremFamilyOptions},
-%   thus declaring both \mymeta{theorem name} and \mymeta{theorem name*} environments,
-%   the latter calling the \kw{starred} variants of the theorem family,
-%   and both of them calling \kw{unnumbered} variants of the family.
-% 
-%   The possible theorem variants have to be generated with the \cs{NewTheoremFamily*}
-%   command before.
-% 
-% \end{function}
 % 
 % \section{\LaTeX3 interface}
 %
@@ -694,10 +643,10 @@
 %     where the \mymeta{mandatory args} list the mandatory args of the \LaTeX2e
 %     interface, and the \mymeta{optional args} list the optional args
 %     of the key-value interface, but requiring them mandatory as well.
-%   \item \cs{groupthm_new_foo_from_keys:mmm}\marg{keys}\mymeta{mandatory args}
+%   \item \cs{groupthm_new_foo_from_keys:mmm}\marg{key=value list}\mymeta{mandatory args}
 %     where we pass a \texttt{clist} as the first argument and all mandatory args
 %     as further mandatory arguments.
-%   \item \cs{NewFoo}\oarg{keys}\mymeta{mandatory args},
+%   \item \cs{NewFoo}\oarg{key=value list}\mymeta{mandatory args},
 %     where the keys can be passed optionally.
 % \end{itemize}
 % 
@@ -712,7 +661,7 @@
 %   \groupthm_declare_group:nn
 % }
 %   \begin{syntax}
-%     \cs{groupthm_new_group:nn}\marg{keys}\marg{theorem group}
+%     \cs{groupthm_new_group:nn}\marg{key=value list}\marg{theorem group}
 %   \end{syntax}
 %
 %    \LaTeX3 versions of \cs{NewTheoremGroup}, \cs{RenewTheoremGroup},
@@ -753,8 +702,8 @@
 %
 % \begin{function}{\groupthm_declare_group_rule:nnnn}
 %    \begin{syntax}
-%       \cs{groupthm_declare_group_rule:nnnn}\marg{keyname}\marg{theorem group 1}
-%       \marg{relation}\marg{theorem group 2}
+%       \cs{groupthm_declare_group_rule:nnnn}\marg{keyname}\marg{theorem group_1}
+%       \marg{relation}\marg{theorem group_2}
 %    \end{syntax}
 %
 %  \LaTeX3 version of \cs{DeclareTheoremGroupRule}
@@ -766,7 +715,7 @@
 %
 % \begin{function}{\groupthm_new_grouped_theorem_from_keys:nn, \groupthm_provide_grouped_theorem_from_keys:nn}
 %    \begin{syntax}
-%       \cs{groupthm_provide_grouped_theorem_from_keys:nn}\marg{keys}\marg{environment name}
+%       \cs{groupthm_provide_grouped_theorem_from_keys:nn}\marg{key=value list}\marg{environment name}
 %    \end{syntax}
 %   
 %   \LaTeX3 version of \cs{NewGroupedTheorem}, \cs{ProvideGroupedTheorem}
@@ -780,7 +729,7 @@
 %   \groupthm_provide_grouped_theorem_star_from_keys:nn
 % }
 %    \begin{syntax}
-%       \cs{groupthm_new_grouped_theorem_star_from_keys:nn}\marg{keys}\marg{environment name}
+%       \cs{groupthm_new_grouped_theorem_star_from_keys:nn}\marg{key=value list}\marg{environment name}
 %    \end{syntax}
 %
 % 
@@ -793,7 +742,7 @@
 %
 % \begin{function}{\groupthm_new_theorem_from_keys:nn, \groupthm_provide_theorem_from_keys:nn}
 %    \begin{syntax}
-%       \cs{groupthm_provide_theorem_from_keys:nn}\marg{keys}\marg{environment name}
+%       \cs{groupthm_provide_theorem_from_keys:nn}\marg{key=value list}\marg{environment name}
 %    \end{syntax}
 %   
 %   \LaTeX3 version of \cs{NewTheorem}, \cs{ProvideTheorem}
@@ -803,7 +752,7 @@
 %
 % \begin{function}{\groupthm_new_theorem_star_from_keys:nn, \groupthm_provide_theorem_star_from_keys:nn}
 %    \begin{syntax}
-%       \cs{groupthm_new_theorem_star_from_keys:nn}\marg{keys}\marg{environment name}
+%       \cs{groupthm_new_theorem_star_from_keys:nn}\marg{key=value list}\marg{environment name}
 %    \end{syntax}
 %
 %   \LaTeX3 version of \cs{NewTheorem*}, \cs{ProvideTheorem*}
@@ -841,7 +790,7 @@
 %     \groupthm_provide_grouped_theorem_family_from_keys:nn
 %   }
 %   \begin{syntax}
-%     \cs{groupthm_new_grouped_theorem_family_from_keys:nn}\marg{keys}\marg{theorem family}
+%     \cs{groupthm_new_grouped_theorem_family_from_keys:nn}\marg{key=value list}\marg{theorem family}
 %   \end{syntax}
 %
 %   The \LaTeX3 versions of \cs{NewGroupedTheoremFamily} and \cs{ProvideGroupedTheoremFamily}
@@ -856,7 +805,7 @@
 %     \groupthm_provide_grouped_theorem_family_star_from_keys:nn
 %   }
 %   \begin{syntax}
-%     \cs{groupthm_new_grouped_theorem_family_star_from_keys:nn}\marg{keys}\marg{theorem family}
+%     \cs{groupthm_new_grouped_theorem_family_star_from_keys:nn}\marg{key=value list}\marg{theorem family}
 %   \end{syntax}
 %
 %   The \LaTeX3 versions of \cs{NewGroupedTheoremFamily*} and \cs{ProvideGroupedTheoremFamily*}
@@ -871,7 +820,7 @@
 %     \groupthm_provide_theorem_family_from_keys:nn
 %   }
 %   \begin{syntax}
-%     \cs{groupthm_new_theorem_family_from_keys:nn}\marg{keys}\marg{theorem family}
+%     \cs{groupthm_new_theorem_family_from_keys:nn}\marg{key=value list}\marg{theorem family}
 %   \end{syntax}
 %
 %   The \LaTeX3 versions of \cs{NewTheoremFamily} and \cs{ProvideTheoremFamily}
@@ -886,7 +835,7 @@
 %     \groupthm_provide_theorem_family_star_from_keys:nn
 %   }
 %   \begin{syntax}
-%     \cs{groupthm_new_theorem_family_star_from_keys:nn}\marg{keys}\marg{theorem family}
+%     \cs{groupthm_new_theorem_family_star_from_keys:nn}\marg{key=value list}\marg{theorem family}
 %   \end{syntax}
 %
 %   The \LaTeX3 versions of \cs{NewTheoremFamily*} and \cs{ProvideTheoremFamily*}
@@ -1086,7 +1035,7 @@
 %
 % \begin{macro}{\hook_gset_rule:nnVn}
 %    \begin{syntax}
-%       \cs{hook_gset_rule:nnVn}\marg{hook}\marg{label 1}\marg{relation}\marg{label 2}
+%       \cs{hook_gset_rule:nnVn}\marg{hook}\marg{label_1}\marg{relation}\marg{label_2}
 %    \end{syntax}
 %
 %		 Just a variant of the usual \cs{hook_gset_rule:nnnn} macro that we use.
@@ -1242,7 +1191,7 @@
 %
 % \begin{macro}{\@@_set_normalized_keys:nnn}
 %    \begin{syntax}
-%       \cs{@@_set_normalized_keys:nnn}\marg{keys}\marg{key group}\marg{fallback name}
+%       \cs{@@_set_normalized_keys:nnn}\marg{key=value list}\marg{key group}\marg{fallback name}
 %    \end{syntax}
 %		 
 % Sets the packages keys and normalizes the retrieved values, that is,
@@ -1773,7 +1722,7 @@
 %     \groupthm_declare_group:nn
 %   }
 %    \begin{syntax}
-%       \cs{groupthm_new_group:nn}\marg{keys}\marg{theorem group}
+%       \cs{groupthm_new_group:nn}\marg{key=value list}\marg{theorem group}
 %    \end{syntax}
 %		 
 %    \begin{macrocode}
@@ -1846,8 +1795,8 @@
 %
 % \begin{macro}{\groupthm_declare_group_rule:nnnn}
 %    \begin{syntax}
-%       \cs{groupthm_declare_group_rule:nnnn}\marg{keyname}\marg{theorem group 1}
-%       \marg{relation}\marg{theorem group 2}
+%       \cs{groupthm_declare_group_rule:nnnn}\marg{keyname}\marg{theorem group_1}
+%       \marg{relation}\marg{theorem group_2}
 %    \end{syntax}
 %		 
 % We have to normalize the arguments a little bit, namely replacing \texttt{higher}
@@ -2311,7 +2260,7 @@
 %     \ProvideGroupedTheorem, \ProvideGroupedTheorem*
 %   }
 %    \begin{syntax}
-%       \cs{NewGroupedTheorem}\oarg{keys}\marg{theorem name}
+%       \cs{NewGroupedTheorem}\oarg{key=value list}\marg{theorem name}
 %    \end{syntax}
 %
 %    \begin{macrocode}
@@ -2461,7 +2410,7 @@
 %     \ProvideGroupedTheoremFamily, \ProvideGroupedTheoremFamily*
 %   }
 %    \begin{syntax}
-%       \cs{NewGroupedTheoremFamily}\oarg{keys}\marg{family name}
+%       \cs{NewGroupedTheoremFamily}\oarg{key=value list}\marg{family name}
 %    \end{syntax}
 %
 %    \begin{macrocode}
diff --git a/doc/environments/groupthm/groupthm.tdo b/doc/environments/groupthm/groupthm.tdo
index 31f02cd..34830b1 100644
--- a/doc/environments/groupthm/groupthm.tdo
+++ b/doc/environments/groupthm/groupthm.tdo
@@ -1,8 +1,5 @@
 \contentsline {todo}{\color@fb@x {}{black}{}{orange}{\leavevmode {\color {orange}o}}\ insert code example output}{4}{section*.3}%
 \contentsline {todo}{\color@fb@x {}{black}{}{orange}{\leavevmode {\color {orange}o}}\ code}{4}{section*.4}%
 \contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{7}{section*.5}%
-\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{7}{section*.6}%
-\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{8}{section*.7}%
-\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{9}{section*.8}%
-\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{10}{section*.9}%
-\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{18}{section*.10}%
+\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{8}{section*.6}%
+\contentsline {todo}{\color@fb@x {}{black}{}{red!40}{\leavevmode {\color {red!40}o}}\ Add reference.}{18}{section*.7}%