262 lines
9.1 KiB
TeX
262 lines
9.1 KiB
TeX
\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}
|