latex/latex-packages
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

start writing documentation

Browse source
This commit is contained in:
Maximilian Keßler 2022-01-17 12:13:09 +01:00
parent 77c8dc4717
commit 5bd70271e7
2 changed files with 276 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/.gitignore vendored Normal file
View file

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

262
doc/environments/groupthm/groupthm.tex Normal file
View file

@ -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}