start writing documentation

doc/.gitignore

@@ -0,0 +1,14 @@
+*.aux
+*.fdb_latexmk
+*.fls
+*.log
+*.pdf
+wip/proof/.skip
+*.out
+*.idx
+*.ilg
+*.ind
+*.cnt
+*.glo
+*.hd
+*.toc

doc/environments/groupthm/groupthm.tex

@@ -0,0 +1,262 @@
+\documentclass[full]{l3doc}
+
+\usepackage{mkessler-todo}
+
+\title{%
+   The \pkg{groupthm} package \\
+   Theorem Groups and Families
+}
+
+\author{%
+          Maximilian Keßler
+}
+
+\date{Released 2022-01-17}
+
+\NewDocumentCommand{\kw}{m}
+{%
+  \texttt{#1}%
+}
+
+\NewDocumentCommand{\vocab}{m}
+{%
+  \emph{#1}%
+}
+
+\begin{document}
+\maketitle
+
+\section{test}
+\begin{documentation}
+
+\tableofcontents
+  
+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).
+
+
+\section{End user interface}
+
+\subsection{Defining theorem groups}
+
+\begin{function}{\NewTheoremGroup, \RenewTheoremGroup, \ProvideTheoremGroup, \DeclareTheoremGroup}
+  \begin{syntax}
+    \cs{NewTheoremGroup}[\meta{keys}]\{\meta{theorem group}\}
+  \end{syntax}
+  
+  This introduces a new \meta{theorem group} with the given name.
+  The \meta{keys} available are the same as introduced in \autoref{sec:theorem-groups}:
+
+  \begin{description}
+    \item
+
+      \kw{prename} = \meta{token list}.
+      Insert the \meta{token list} in front of the theorem name.
+
+    \item
+
+      \kw{postname} = \meta{token list}.
+      Insert the \meta{token list} after the theorem name.
+
+    \item
+
+      \kw{mapname} = \meta{function}.
+      Apply this \meta{function} to the theorem name.
+
+    \item
+
+      \kw{thmtools} = $\{$\meta{clist}$\}$.
+      Pass these options to \pkg{thmtools}.
+
+  \end{description}
+
+  For uniqueness of the given options, the \meta{clist} given to the \kw{thmtools} key
+  has to be surrounded by a pair of braces.
+
+  \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}.
+  \end{texnote}
+
+  As in the \pkg{xparse} package, the behavior of the prefixes is as follows:
+  \begin{description}
+    \item[\cs{NewTheoremGroup}]
+
+      Defines the theorem group if not defined already.
+      This emits an error in case the theorem group is already defined.
+
+    \item[\cs{RenewTheoremGroup}]
+
+      Defines the theorem group although defined already.
+      This emits an error in case the theorem group has not been defined yet.
+
+    \item[\cs{ProviedTheoremGroup}]
+
+      Defines the theorem group if it is not defined already.
+      This does not emit an error if the group is already defined
+      (and has no effect in this case).
+      Typically used to ensure that some group exists, whilst not overwriting prior
+      (potentially more custom) definitions of the group.
+
+    \item[\cs{DeclareTheoremGroup}]
+
+      Defines the theorem group in disregard of any
+      existing definitions. An old definition will be overwritten.
+  \end{description}
+
+  \subsection{Controlling theorem group precedence}
+
+  \begin{function}{\DeclareTheoremGroupRule}
+    \begin{syntax}
+\cs{DeclareTheoremGroupRule}[\meta{keyname}]%
+\{\meta{theorem group 1}\}\{\meta{relation}\}\{\meta{theorem group 2}\}
+    \end{syntax}
+  \end{function}
+  
+  This declares some relation between the two theorem groups,
+  controlling their order of application in case a theorem is member
+  of both groups.
+
+  The \meta{keyname} can be one of \kw{prename}, \kw{postname}, \kw{mapname}, \kw{thmtools}.
+  If present, it declares the corresponding relation only for this subkey.
+  This can lead to \meta{theorem group 1} overwriting \meta{theorem group 2} when given
+  contradictory \pkg{thmtools} options, but the \kw{prename} of \meta{theorem group 1}
+  being applied after the one of \meta{theorem group 2}.
+  When the \meta{keyname} is not given, this applies to all keywords.
+
+  \begin{texnote}
+    The \meta{keyname} is just passed to the corresponding argument
+    of the \kw{lthooks} package.
+    If the option argument is not present, \kw{??} is used, this has the described effect.
+  \end{texnote}
+
+  The behavior of the relations is based on the \cs{DeclareHookRule} command
+  from the \pkg{xparse} package, and all respective keys are in fact available,
+  but typically not needed, so the reader of this manual is referred to the
+  \todoref{lthooks} packages documentation for a list of the full keys.
+  For us, the following list will suffice:
+
+  \begin{description}
+    \item[\kw{higher} or \kw{after} or \k{>}]
+      
+      \meta{theorem group 1} takes precedence over \meta{theorem group 2}.
+      Its \kw{prename} is applied after the one of \meta{theorem group 2}.
+
+    \item[\k{lower} or \kw{before} or \k{<}]
+
+      \meta{theorem group 2} takes precedence over \meta{theorem group 1}.
+      Its \kw{prename} is applied after the one of \meta{theorem group 1}.
+
+  \end{description}
+
+\end{function}
+
+%\section{\LaTeX3 interface}
+
+\end{documentation}
+
+\PrintIndex
+\end{document}