diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..db9bc6e --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,14 @@ +*.aux +*.fdb_latexmk +*.fls +*.log +*.pdf +wip/proof/.skip +*.out +*.idx +*.ilg +*.ind +*.cnt +*.glo +*.hd +*.toc diff --git a/doc/environments/groupthm/groupthm.tex b/doc/environments/groupthm/groupthm.tex new file mode 100644 index 0000000..84a6f2a --- /dev/null +++ b/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}