summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/thmtools/doc/thmtools-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/thmtools/doc/thmtools-manual.tex')
-rw-r--r--macros/latex/contrib/thmtools/doc/thmtools-manual.tex1166
1 files changed, 1166 insertions, 0 deletions
diff --git a/macros/latex/contrib/thmtools/doc/thmtools-manual.tex b/macros/latex/contrib/thmtools/doc/thmtools-manual.tex
new file mode 100644
index 0000000000..47f1235f5f
--- /dev/null
+++ b/macros/latex/contrib/thmtools/doc/thmtools-manual.tex
@@ -0,0 +1,1166 @@
+% !TeX program = pdflatex
+\documentclass[paper=a4, pagesize, DIV=20,
+ english,
+ headings=small,11pt,
+ titlepage=false,
+ numbers=noendperiod
+]{scrreprt}
+\addtokomafont{sectioning}{\rmfamily}
+
+\usepackage[T1]{fontenc}
+\usepackage[charter]{mathdesign}
+\usepackage{luximono}
+\usepackage[scaled]{helvet}
+
+\usepackage[dvipsnames]{xcolor}
+
+\usepackage{doc,shortvrb,xspace}
+\makeatletter
+% to be fixed at some point...
+\let\PrintDescribeMacro\@gobble
+\let \PrintDescribeEnv\@gobble
+\let \PrintMacroName\@gobble
+\let \PrintEnvName\@gobble
+\makeatother
+\CodelineNumbered
+
+\usepackage{listings}
+
+\usepackage{amsmath, amsthm}
+\usepackage{enumitem}
+\setlist[description, 1]{labelindent=2em, leftmargin=2em, rightmargin=2em, labelwidth=!}
+\usepackage{tikz}
+\usetikzlibrary{tikzmark}
+
+\usepackage{nameref}
+\usepackage{hyperref}
+\hypersetup{
+ colorlinks,
+ linkcolor=RoyalBlue,
+ linktocpage
+}
+\usepackage{cleveref}[2010/05/01]
+
+\usepackage{thmtools, thm-restate}
+\usepackage[unq]{unique}
+
+\providecommand\pkg[1]{\textsf{#1}}
+\providecommand\Thmtools{\pkg{Thmtools}\xspace}
+\providecommand\thmtools{\pkg{thmtools}\xspace}
+\providecommand\oarg[1]{\texttt{[}\textit{#1}\texttt{]}}
+\providecommand\marg[1]{\texttt{\{}\textit{#1}\texttt{\}}}
+
+
+\providecommand\clap{\makebox[0pt][c]}
+
+\newcommand\key[2][\keydefaultcontext]{%
+ % todo: create an index from this...
+ \paragraph*{\texttt{#2}}
+}
+
+\lstloadlanguages{[LaTeX]TeX}
+\lstset{language=[LaTeX]TeX,basicstyle=\small\ttfamily,keywordstyle=\mdseries,aboveskip=0pt}
+
+\lstnewenvironment{preamble}[1][]{%
+ \lstset{backgroundcolor=\color{Purple!15},#1}%
+}{%
+}
+\lstnewenvironment{body}[1][]{%
+ \lstset{backgroundcolor=\color{Yellow!30},#1}%
+}{%
+}
+
+\newenvironment{source}{%
+ \par\noindent\strut\minipage[t]{0.61\linewidth}
+}{%
+ \endminipage
+}
+\newenvironment{result}{%
+ \hfill\minipage[t]{0.37\linewidth}
+}{%
+ \endminipage\strut\par
+}
+%\MakeShortVerb{\|}
+\lstMakeShortInline{|}
+
+
+\declaretheorem{theorem}
+\declaretheorem[numberwithin=section]{theoremS}
+\declaretheorem[name=\"Ubung]{exercise}
+\declaretheorem[sibling=theorem]{lemma}
+\declaretheorem[numbered=no,
+ name=Euclid's Prime Theorem]{euclid}
+\declaretheorem[numbered=unless unique]{singleton}
+\declaretheorem[numbered=unless unique]{couple}
+\declaretheorem[style=remark]{remark}
+\declaretheorem{Theorem}
+
+\declaretheorem[shaded={bgcolor=Lavender,
+ textwidth=12em}]{BoxI}
+
+\declaretheorem[shaded={rulecolor=Lavender,
+ rulewidth=2pt, bgcolor={rgb}{1,1,1}}]{BoxII}
+
+ \declaretheorem[thmbox=L]{boxtheorem L}
+ \declaretheorem[thmbox=M]{boxtheorem M}
+ \declaretheorem[thmbox=S]{boxtheorem S}
+
+\declaretheoremstyle[
+ spaceabove=6pt, spacebelow=6pt,
+ headfont=\normalfont\bfseries,
+ notefont=\mdseries, notebraces={(}{)},
+ bodyfont=\normalfont,
+ postheadspace=1em,
+ qed=\qedsymbol
+ ]{mystyle}
+\declaretheorem[style=mystyle
+ ]{styledtheorem}
+
+\declaretheorem[name=Theorem, refname={theorem,theorems},
+ Refname={Theorem,Theorems}]{callmeal}
+
+
+\input{VERSION.tex}
+
+\title{\Thmtools Users' Guide}
+\author{Dr. Ulrich M. Schwarz -- ulmi@absatzen.de\thanks{%
+ who would like to thank the users for testing, encouragement, feature requests, and
+ bug reports. In particular, Denis Bitouz\'e prompted further improvement
+ when \thmtools got stuck in a ``good enough for me'' slump.}
+ \and
+ Yukai Chou -- muzimuzhi@gmail.com
+}
+\date{\VERSION}
+
+\begin{document}
+ \maketitle
+ \section*{\abstractname}
+
+ The \thmtools bundle is a collection of packages that is designed to
+ provide an easier interface to theorems, and to facilitate some more
+ advanced tasks.
+
+ If you are a first-time user and you don't think your requirements are out
+ of the ordinary, browse the examples in \autoref{cha:impatient}. If you're
+ here because the other packages you've tried so far just can't do what you
+ want, take inspiration from \autoref{cha:extravagant}. If you're a repeat
+ customer, you're most likely to be interested in the refence section in
+ \autoref{cha:reference}.
+
+ \begin{multicols}{2}[\section*{\contentsname}]
+ \makeatletter
+ \let\chapter\@gobbletwo
+ \tableofcontents
+ \end{multicols}
+ \clearpage
+
+ \chapter{\Thmtools for the impatient}\label{cha:impatient}
+
+ \section*{How to use this document}
+
+ This guide consists mostly of examples and their output, sometimes with a
+ few additional remarks. Since theorems are defined in the preamble and
+ used in the document, the snippets are two-fold:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ % Preamble code looks like this.
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem{theorem}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ % Document code looks like this.
+ \begin{theorem}[Euclid]
+ \label{thm:euclid}%
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, the list of primes,
+ \begin{equation}\label{eq:1}
+ 2,3,5,7,\dots
+ \end{equation}
+ is infinite.
+ \end{theorem}
+ \end{body}
+ \end{source}
+ \begin{result}
+ The result looks like this:
+% \begin{theorem}[Euclid]
+% For every prime $p$, there is a prime $p'>p$.
+% In particular, there are infinitely many primes.
+% \end{theorem}
+ \begin{restatable}[Euclid]{theorem}{firsteuclid}
+ \label{thm:euclid}%
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, the list of primes,
+ \begin{equation}\label{eq:1}
+ 2,3,5,7,\dots
+ \end{equation}
+ is infinite.
+ \end{restatable}
+ \end{result}
+
+ Note that in all cases, you will need a \emph{backend} to provide the
+ command |\newtheorem| with the usual behaviour. The \LaTeX\
+ kernel has a built-in backend which cannot do very much; the most common
+ backends these days are the \pkg{amsthm} and \pkg{ntheorem} packages.
+ Throughout this document, we'll use \pkg{amsthm}, and some of the features
+ won't work with \pkg{ntheorem}.
+
+ \section{Elementary definitions}
+
+ As you have seen above, the new command to define theorems is
+ |\declaretheorem|, which in its most basic form just takes the
+ name of the environment. All other options can be set through a key-val
+ interface:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[numberwithin=section]{theoremS}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{theoremS}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{theoremS}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{restatable}[Euclid]{theoremS}{euclidii}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{restatable}
+ \end{result}
+
+ Instead of |numberwithin=|, you can also use |parent=| and
+ |within=|. They're all the same, use the one you find easiest to
+ remember.
+
+ Note the example above looks somewhat bad: sometimes, the name of the environment,
+ with the first
+ letter uppercased, is not a good choice for the theorem's title.
+
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[name=\"Ubung]{exercise}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{exercise}
+ Prove Euclid's Theorem.
+ \end{exercise}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{exercise}
+ Prove Euclid's Theorem.
+ \end{exercise}
+ \end{result}
+
+ To save you from having to look up the name of the key every time, you can
+ also use ``title='' and ``heading='' instead of ``name=''; they do exactly
+ the same and hopefully one of these will be easy to remember for you.
+
+ Of course, you do not have to follow the abominal practice of numbering
+ theorems, lemmas, etc., separately:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[sibling=theorem]{lemma}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{lemma}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{lemma}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{lemma}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{lemma}
+ \end{result}
+
+ Again, instead of |sibling=|, you can also use |numberlike=| and
+ |sharecounter=|.
+
+ Some theorems have a fixed name and are not supposed to get a number.
+ To this end, \pkg{amsthm} provides |\newtheorem*|, which is
+ accessible through \thmtools:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[numbered=no,
+ name=Euclid's Prime Theorem]{euclid}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{euclid}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{euclid}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{euclid}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{euclid}
+ \end{result}
+
+ As a somewhat odd frill, you can turn off the number if there's only one
+ instance of the kind in the document. This might happen when you split and
+ join your papers into short conference versions and longer journal papers
+ and tech reports. Note that this doesn't combine well with the sibling
+ key: how do you count like somebody who suddenly doesn't count anymore?
+ Also, it takes an extra \LaTeX\ run to settle.
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \usepackage[unq]{unique}
+ \declaretheorem[numbered=unless unique]{singleton}
+ \declaretheorem[numbered=unless unique]{couple}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{couple}
+ Marc \& Anne
+ \end{couple}
+ \begin{singleton}
+ Me.
+ \end{singleton}
+ \begin{couple}
+ Buck \& Britta
+ \end{couple}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{couple}
+ Marc \& Anne
+ \end{couple}
+ \begin{singleton}
+ Me.
+ \end{singleton}
+ \begin{couple}
+ Buck \& Britta
+ \end{couple}
+ \end{result}
+
+ \section{Frilly references}
+
+ In case you didn't know, you should: \pkg{hyperref}, \pkg{nameref} and
+ \pkg{cleveref} offer ways of ``automagically'' knowing that
+ |\label{foo}| was inside a theorem, so that a reference adds the
+ string ``Theorem''. This is all done for you, but there's one catch: you
+ have to tell \thmtools\ what the name to add is. By default, it will use
+ the title of the theorem, in particular, it will be uppercased.
+ (This happens to match the guidelines of all
+ publishers I have encountered.) But there is an alternate spelling
+ available, denoted by a capital letter, and in any case, if you use
+ \pkg{cleveref}, you should give two values separated by a comma, because
+ it will generate plural forms if you reference many theorems in one
+ |\cite|.
+ \begin{source}
+ \begin{preamble}[gobble=6]
+ \usepackage{amsthm, thmtools}
+ \usepackage{
+ % nameref,%\nameref
+ % n.b. usually nameref is autoloaded by hyperref
+ hyperref,%\autoref
+ % n.b. \Autoref is defined by thmtools
+ cleveref,% \cref
+ % n.b. cleveref after! hyperref
+ }
+ \declaretheorem[name=Theorem,
+ refname={theorem,theorems},
+ Refname={Theorem,Theorems}]{callmeal}
+ \end{preamble}
+ \begin{body}[gobble=6]
+ \begin{callmeal}[Simon]\label{simon}
+ One
+ \end{callmeal}
+ \begin{callmeal}\label{garfunkel}
+ and another, and together,
+ \autoref{simon}, ``\nameref{simon}'',
+ and \cref{garfunkel} are referred
+ to as \cref{simon,garfunkel}.
+ \Cref{simon,garfunkel}, if you are at
+ the beginning of a sentence.
+ \end{callmeal}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{callmeal}[Simon]\label{simon}
+ One
+ \end{callmeal}
+ \begin{callmeal}\label{garfunkel}
+ and another, and together, \autoref{simon}, ``\nameref{simon}'',
+ and \cref{garfunkel} are referred to as \cref{simon,garfunkel}.
+ \Cref{simon,garfunkel}, if you are at the beginning of a sentence.
+ \end{callmeal}
+ \end{result}
+
+ \section{Styling theorems}
+ \label{sec:styling}
+
+ The major backends provide a command |\theoremstyle| to switch
+ between looks of theorems. This is handled as follows:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[style=remark]{remark}
+ \declaretheorem{Theorem}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{Theorem}
+ Note how it still retains the default style,
+ `plain'.
+ \end{Theorem}
+ \begin{remark}
+ This is a remark.
+ \end{remark}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{Theorem}
+ This is a theorem.
+ \end{Theorem}
+ \begin{remark}
+ Note how it still retains the default style, `plain'.
+ \end{remark}
+ \end{result}
+
+ Thmtools also supports the \pkg{shadethm} and \pkg{thmbox} packages:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \usepackage[dvipsnames]{xcolor}
+ \declaretheorem[shaded={bgcolor=Lavender,
+ textwidth=12em}]{BoxI}
+ \declaretheorem[shaded={rulecolor=Lavender,
+ rulewidth=2pt, bgcolor={rgb}{1,1,1}}]{BoxII}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{BoxI}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{BoxI}
+ \begin{BoxII}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{BoxII}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{BoxI}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{BoxI}
+ \begin{BoxII}
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{BoxII}
+ \end{result}
+
+ As you can see, the color parameters can take two forms: it's either the
+ name of a color that is already defined, without curly braces, or it can
+ start with a curly brace, in which case it is assumed that
+ |\definecolor{colorname}|$\langle$\textsl{what you said}$\rangle$ will be
+ valid \LaTeX\ code. In our case, we use the rbg model to manually specify
+ white. (|shadethm|'s default value is {\fboxsep=0pt \fcolorbox{black}[gray]{0.92}{\phantom{XX}}} |[gray]{0.92}|)
+
+ For the \pkg{thmbox} package, use the |thmbox| key:
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \usepackage{amsthm}
+ \usepackage{thmtools}
+ \declaretheorem[thmbox=L]{boxtheorem L}
+ \declaretheorem[thmbox=M]{boxtheorem M}
+ \declaretheorem[thmbox=S]{boxtheorem S}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{boxtheorem L}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem L}
+ \begin{boxtheorem M}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem M}
+ \begin{boxtheorem S}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem S}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{boxtheorem L}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem L}
+ \begin{boxtheorem M}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem M}
+ \begin{boxtheorem S}[Euclid]
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, there are infinitely many primes.
+ \end{boxtheorem S}
+ \end{result}
+
+ Note that for both |thmbox| and |shaded| keys, it's quite possible they will not
+ cooperate with a style key you give at the same time.
+
+ \subsection{Declaring new theoremstyles}
+
+ \Thmtools\ also offers a new command to define new theoremstyles. It is
+ partly a frontend to the |\newtheoremstyle| command of \pkg{amsthm} or
+ \pkg{ntheorem}, but it offers (more or less successfully) the settings of both to
+ either. So we are talking about the same things, consider the sketch in
+ \autoref{fig:params}. To get a result like that, you would use something
+ like
+ \begin{source}
+ \begin{preamble}[gobble=4]
+ \declaretheoremstyle[
+ spaceabove=6pt, spacebelow=6pt,
+ headfont=\normalfont\bfseries,
+ notefont=\mdseries, notebraces={(}{)},
+ bodyfont=\normalfont,
+ postheadspace=1em,
+ qed=\qedsymbol
+ ]{mystyle}
+ \declaretheorem[style=mystyle]{styledtheorem}
+ \end{preamble}
+ \begin{body}[gobble=4]
+ \begin{styledtheorem}[Euclid]
+ For every prime $p$\dots
+ \end{styledtheorem}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{styledtheorem}[Euclid]
+ For every prime $p$\dots
+ \end{styledtheorem}
+ \end{result}
+ Again, the defaults are reasonable and you don't
+ have to give values for everything.
+
+ There is one important thing you cannot see in this example: there are
+ more keys you can pass to |\declaretheoremstyle|: if \thmtools\ cannot
+ figure out at all what to do with it, it will pass it on to the
+ |\declaretheorem| commands that use that style. For example, you may use
+ the |boxed| and |shaded| keys here.
+
+ To change the order in which title, number and note appear, there is a key
+ |headformat|. Currently, the values ``margin'' and ``swapnumber'' are
+ supported. The daring may also try to give a macro here that uses the
+ commands |\NUMBER|, |\NAME| and |\NOTE|.
+ You cannot circumvent the fact
+ that |headpunct| comes at the end, though, nor the fonts and braces you
+ select with the other keys.
+
+ \begin{figure}
+ \centering
+ \fbox{%
+ \begin{tikzpicture}[
+ remember picture,
+ >=latex,
+ nodes={
+ font=\normalfont\sffamily\itshape\small,
+ RoyalBlue
+ },
+ every subnode/.style={
+ inner sep=0pt
+ },
+ tip/.style={|<->|}
+ ]
+ \node[black, font=\Large, text width=.618\textwidth, align=justify]
+ {%
+ which resulted in the following insight: \\
+ \subnode{space above}{\rule{0pt}{1.3\baselineskip}} \\
+ \subnode{head indent}{\strut\hspace*{4em}}
+ \textbf{%
+ \subnode{head}{Theorem} 1.2
+ \subnode{note brace}{(}%
+ \subnode{note}{\textit{Euclid}})%
+ \subnode{head punct}{.} %
+ }
+ \subnode{post head space}{\strut\hspace*{4.5em}}
+ For every prime~$p$, there is a prime~$p'>p$. In particular, the list
+ of primes, $2,3,5,7,\dots$, is infinite. \hfill
+ \subnode{qed}{$\Box$} \\
+ \subnode{space below}{\rule{0pt}{1.3\baselineskip}} \\
+ As a consequence, lorem ipsum dolor sit amet frob-%nicate foo
+ % paret.
+ };
+
+ \draw[tip] (space above.south west) -- node[right] {spaceabove} (space above.north west);
+ \draw[tip] (head indent.west) -- node[above] {headindent} (head indent.east);
+ \draw (head.center) -- +(0, 10pt) node[above] {headfont};
+ \draw (note brace.north) -- +(0, 20pt) node[above] {notebraces};
+ \draw (note.center) -- +(0, 10pt) node[above] {notefont};
+ \draw (head punct.base east) -- +(0, 28pt) node[above] {headpunct};
+ \draw[tip] (post head space.west) -- node[above] {postheadspace} (post head space.east);
+ \node at ([xshift=-12pt]qed.150) {qed};
+ \draw[tip] (space below.south west) -- node[right] {spacebelow} (space below.north west);
+ \end{tikzpicture}%
+ }
+ \caption{Settable parameters of a theorem style.}
+ \label{fig:params}
+ \end{figure}
+
+ \section{Repeating theorems}
+
+ Sometimes, you want to repeat a theorem you have given in full earlier,
+ for example you either want to state your strong result in the
+ introduction and then again in the full text, or you want to re-state a
+ lemma in the appendix where you prove it. For example, I lied about
+ \autoref{thm:euclid} on p.\,\pageref{thm:euclid}: the true code used was
+ \begin{source}
+ \begin{preamble}[gobble=6]
+ \usepackage{thmtools, thm-restate}
+ \declaretheorem{theorem}
+ \end{preamble}
+ \begin{body}[gobble=6]
+ \begin{restatable}[Euclid]{theorem}{firsteuclid}
+ \label{thm:euclid}%
+ For every prime $p$, there is a prime $p'>p$.
+ In particular, the list of primes,
+ \begin{equation}\label{eq:1}
+ 2,3,45,7,\dots
+ \end{equation}
+ is infinite.
+ \end{restatable}
+ \end{body}
+ and to the right, I just use
+ \begin{body}[gobble=6]
+ \firsteuclid*
+ \vdots
+ \firsteuclid*
+ \end{body}
+ \end{source}
+ \begin{result}
+ \firsteuclid*
+ \vdots
+ \firsteuclid*
+ \end{result}
+
+ Note that in spite of being a theorem-environment, it gets number one all
+ over again. Also, we get equation number~\eqref{eq:1} again. The star in
+ |\firsteuclid*| tells thmtools that it should redirect the label
+ mechanism, so that this reference: \autoref{thm:euclid} points to
+ p.\,\pageref{thm:euclid}, where the unstarred environment is used. (You can
+ also use a starred environment and an unstarred command, in which case the
+ behaviour is reversed.) Also, if you use \pkg{hyperref} (like you see in this manual), the links will lead you
+ to the unstarred occurence.
+
+ Just to demonstrate that we also handle more involved cases, I repeat
+ another theorem here, but this one was numbered within its section: note
+ we retain the section number which does not fit the current section:
+ \begin{source}
+ \begin{body}[gobble=6]
+ \euclidii*
+ \end{body}
+ \end{source}
+ \begin{result}
+ \euclidii*
+ \end{result}
+
+
+ \section{Lists of theorems}
+
+ To get a list of theorems with default formatting, just use
+ |\listoftheorems|:
+ \begin{source}
+ \begin{body}[gobble=6]
+ \listoftheorems
+ \end{body}
+ \end{source}
+ \begin{result}
+ \let\chapter\section
+ \let\clearpage\relax
+ \listoftheorems
+ \end{result}
+
+ Not everything might be of the same importance, so you can filter out
+ things by environment name:
+ \begin{source}
+ \begin{body}[gobble=6]
+ \listoftheorems[ignoreall,
+ show={theorem,Theorem,euclid}]
+ \end{body}
+ \end{source}
+ \begin{result}
+ \let\chapter\section
+ \let\clearpage\relax
+ \listoftheorems[ignoreall, show={theorem,Theorem,euclid}]
+ \end{result}
+
+ And you can also restrict to those environments that have an optional
+ argument given. Note that two theorems disappear compared to the previous
+ example. You could also say just |onlynamed|, in which case it will
+ apply to \emph{all} theorem environments you have defined.
+ \begin{source}
+ \begin{body}[gobble=6]
+ \listoftheorems[ignoreall,
+ onlynamed={theorem,Theorem,euclid}]
+ \end{body}
+ \end{source}
+ \begin{result}
+ \let\chapter\section
+ \let\clearpage\relax
+ \listoftheorems[ignoreall, onlynamed={theorem,Theorem,euclid}]
+ \end{result}
+
+ As might be expected, the heading given is defined in |\listtheoremname|.
+
+ \section{Extended arguments to theorem environments}
+
+ Usually, the optional argument of a theorem serves just to give a note
+ that is shown in the theorem's head. \Thmtools\ allows you to have a
+ key-value list here as well. The following keys are known right now:
+ \begin{description}
+ \item[name] This is what used to be the old argument. It usually holds
+ the name of the theorem, or a source. This key also accepts an
+ \emph{optional} argument, which will go into the list of theorems. Be
+ aware that since we already are within an optional argument, you have to
+ use an extra level of curly braces:
+ |\begin{theorem}[name={[Short name]A long name,...]}|
+
+ \item[label] This will issue a |\label| command after the head. Not very
+ useful, more of a demo.
+
+ \item[continues] Saying |continues=foo| will cause the number that is
+ given to be changed to |\ref{foo}|, and a text is added to the note.
+ (The exact text is given by the macro |\thmcontinues|, which takes the
+ label as its argument.)
+
+ \item[restate] Saying |restate=foo| will hopefully work like
+ wrapping this theorem in a restatable environment. (It probably still fails
+ in cases that I didn't think of.) This key also accepts an optional
+ argument: when restating, the restate key is replaced by this argument,
+ for example, |restate=[name=Boring rehash]foo| will result in a
+ different name. (Be aware that it is possible to give the same key
+ several times, but I don't promise the results. In case of the name key,
+ the names happen to override one another.)
+ \end{description}
+ \begin{source}
+ \begin{body}[gobble=6]
+ \begin{theorem}[name=Keyed theorem,
+ label=thm:key]
+ This is a
+ key-val theorem.
+ \end{theorem}
+ \begin{theorem}[continues=thm:key]
+ And it's spread out.
+ \end{theorem}
+ \end{body}
+ \end{source}
+ \begin{result}
+ \begin{theorem}[name=Keyed theorem,
+ label=thm:key]
+ This is a key-val theorem.
+ \end{theorem}
+ \begin{theorem}[continues=thm:key]
+ And it's spread out.
+ \end{theorem}
+ \end{result}
+
+
+
+ \chapter{\Thmtools for the extravagant}\label{cha:extravagant}
+
+ This chapter will go into detail on the slightly more technical offerings
+ of this bundle. In particular, it will demonstrate how to use the general
+ hooks provided to extend theorems in the way you want them to behave.
+ Again, this is done mostly by some examples.
+
+ \section{Understanding \thmtools' extension mechanism}
+
+ \Thmtools\ draws most of its power really only from one feature:
+ the |\newtheorem| of the backend will, for example, create
+ a theorem environment, i.e. the commands |\theorem| and
+ |\endtheorem|. To add functionality, four places immediately
+ suggest themselves: ``immediately before'' and ``immediately after'' those
+ two.
+
+ There are two equivalent ways of adding code there: one is to call
+ |\addtotheorempreheadhook| and its brothers and sisters
+ |...postheadhook|, |...prefoothook|
+ and |...postfoothook|.
+ All of these take an \emph{optional} argument, the name of the
+ environment, and the new code as a mandatory argument. The name of environment is
+ optional because there is also a set of ``generic'' hooks added to every
+ theorem that you define.
+
+ The other way is to use the keys |preheadhook| et al. in your
+ |\declaretheorem|. (There is no way of accessing the generic
+ hook in this way.)
+
+ The hooks are arranged in the following way: first the specific prehead,
+ then the generic one. Then, the original |\theorem| (or
+ whatever) will be called. Afterwards, first the specific posthead again,
+ then the generic one. (This means that you cannot wrap the head alone in
+ an environment this way.) At the end of the theorem, it is the other way
+ around: first the generic, then the specific, both before and after that
+ |\endtheorem|. This means you can wrap the entire theorem
+ easily by adding to the prehead and the postfoot hooks. Note that
+ \thmtools\ does not look inside |\theorem|, so you cannot get
+ inside the head formatting, spacing, punctuation in this way.
+
+ In many situations, adding static code will not be enough. Your code can
+ look at |\thmt@envname|, |\thmt@thmname| and
+ |\thmt@optarg|, which will contain the name of the environment,
+ its title, and, if present, the optional argument (otherwise, it is
+ |\@empty|).
+ \emph{However}, you should not make assumptions about the optional
+ argument in the preheadhook: it might still be key-value, or it might
+ already be what will be placed as a note. (This is because the key-val
+ handling itself is added as part of the headkeys.)
+
+
+ \section{Case in point: the \texttt{shaded} key}
+
+ Let us look at a reasonably simple example: the |shaded| key, which we've
+ already seen in the first section. You'll observe that we run into a
+ problem similar to the four-hook mess: your code may either want to modify
+ parameters that need to be set beforehand, or it wants to modify the
+ environment after it has been created. To hide this from the user, the
+ code you define for the key is actually executed twice, and
+ |\thmt@trytwice{A}{B}| will execute A on the first pass, and B
+ on the second. Here, we want to add to the hooks, and the hooks are only
+ there in the second pass.
+
+ \DocInput{thmdef-shaded.dtx}
+
+ \section{Case in point: the thmbox key}
+
+ \DocInput{thmdef-thmbox.dtx}
+
+ \section{Case in point: the mdframed key}
+ \DocInput{thmdef-mdframed.dtx}
+
+ \section{How \thmtools\ finds your extensions}
+
+ Up to now, we have discussed how to write the code that adds functionality
+ to your theorems, but you don't know how to activate it yet.
+ Of course, you can put it in your preamble, likely embraced by
+ |\makeatletter| and |\makeatother|, because you are
+ using internal macros with @ in their name (viz.,
+ |\thmt@envname| and friends). You can also put them into a
+ package (then, without the |\makeat...|),
+ which is simply a file ending in |.sty| put somewhere that \LaTeX\ can find
+ it, which can then be loaded with |\usepackage|.
+ To find out where exactly that is, and if you'd need to update
+ administrative helper files such as a filename database FNDB,
+ please consult the documentation of your \TeX\ distribution.
+
+ Since you most likely want to add keys as well, there is a shortcut that
+ \thmtools\ offers you: whenever you use a key |key| in a
+ |\declaretheorem| command, and \thmtools\ doesn't already know
+ what to do with it, it will try to |\usepackage{thmdef-key}| and
+ evaluate the key again. (If that doesn't work, \thmtools\ will cry
+ bitterly.)
+
+ For example, there is no provision in \thmtools\ itself that make the
+ |shaded| and |thmbox| keys described above special:
+ in fact, if you want to use a different package to create frames, you just
+ put a different |thmdef-shaded.sty| into a preferred texmf tree.
+ Of course, if your new package doesn't offer the old keys, your old
+ documents might break!
+
+ The behaviour for the keys in the style definition is slightly different:
+ if a key is not known there, it will be used as a ``default key'' to every
+ theorem that is defined using this style. For example, you can give the
+ |shaded| key in a style definition.
+
+ Lastly, the key-val arguments to the theorem environments themselves need
+ to be loaded manually, not least because inside the document it's too late
+ to call |\usepackage|.
+
+ \chapter{\Thmtools for the completionist}\label{cha:reference}
+
+ This will eventually contain a reference to all known keys, commands, etc.
+
+
+ \section{Known keys to \texttt{\textbackslash declaretheoremstyle}}
+ \def\keydefaultcontext{declaretheoremstyle}
+
+ N.b. implementation for \pkg{amsthm} and \pkg{ntheorem} is separate for
+ these, so if it doesn't work for \pkg{ntheorem}, try if it works with
+ \pkg{amsthm}, which in general supports more things.
+
+ Also, all keys listed as known to |\declaretheorem| are valid.
+
+ \key{spaceabove} Value: a length. Vertical space above the theorem,
+ possibly discarded if the theorem is at the top of the page.
+
+ \key{spacebelow} Value: a length. Vertical space after the theorem,
+ possibly discarded if the theorem is at the top of the page.
+
+ \key{headfont} Value: \TeX\ code. Executed just before the head of the
+ theorem is typeset, inside a group. Intended use it to put font switches here.
+
+ \key{notefont}
+ Value: \TeX\ code. Executed just before the note in the head is typeset, inside a group.
+ Intended use it to put font switches here. Formatting also applies to
+ the braces around the note.
+ Not supported by \pkg{ntheorem}.
+
+ \key{bodyfont}
+ Value: \TeX\ code. Executed before the begin part of the theorem ends,
+ but before all afterheadhooks. Intended use it to put font switches here.
+
+ \key{headpunct}
+ Value: \TeX\ code, usually a single character. Put at the end of the
+ theorem's head, prior to linebreaks or indents.
+
+ \key{notebraces}
+ Value: Two characters, the opening and closing symbol to use around a
+ theorem's note.
+ (Not supported by \pkg{ntheorem}.)
+
+ \key{postheadspace}
+ Value: a length. Horizontal space inserted after the entire head of the
+ theorem, before the body. Does probably not apply (or make sense) for
+ styles that have a linebreak after the head.
+
+ \key{headformat}
+ Value: \LaTeX\ code using the special placeholders |\NUMBER|, |\NAME|
+ and |\NOTE|, which correspond to the (formatted, including the braces
+ for |\NOTE| etc.) three parts of a theorem's head. This can be used to
+ override the usual style ``1.1 Theorem (Foo)'', for example to let the
+ numbers protude in the margin or put them after the name.
+
+ Additionally, a number of keywords are allowed here instead of \LaTeX\
+ code:
+ \begin{description}
+ \item[margin] Lets the number protrude in the (left) margin.
+
+ \item[swapnumber] Puts the number before the name. Currently
+ not working so well for unnumbered theorems.
+ \item[] \emph{This list is likely to grow}
+ \end{description}
+
+ \key{headindent}
+ Value: a length. Horizontal space inserted before the head. Some
+ publishers like |\parindent| here for remarks, for example.
+
+
+ \section{Known keys to \texttt{\textbackslash declaretheorem}}
+ \def\keydefaultcontext{declaretheorem}
+
+ \key{parent}
+ Value: a counter name. The theorem will be reset whenever that counter
+ is incremented. Usually, this will be a sectioning level, |chapter| or
+ |section|.
+
+ \key{numberwithin}
+ (Same as |parent|.)
+
+ \key{within}
+ (Same as |parent|.)
+
+
+ \key{sibling}
+ Value: a counter name. The theorem will use this counter for numbering.
+ Usually, this is the name of another theorem environment.
+
+ \key{numberlike}
+ (Same as |sibling|.)
+
+ \key{sharenumber}
+ (Same as |sibling|.)
+
+
+ \key{title}
+ Value: \TeX\ code. The title of the theorem. Default is the name of the
+ environment, with |\MakeUppercase| prepended. You'll have to give
+ this if your title starts with an accented character, for example.
+
+ \key{name}
+ (Same as title.)
+
+ \key{heading}
+ (Same as title.)
+
+ \key{numbered}
+ Value: one of the keywords |yes|, |no| or |unless unique|. The theorem
+ will be numbered, not numbered, or only numbered if it occurs more than
+ once in the document. (The latter requires another \LaTeX\ run and will
+ not work well combined with |sibling|.)
+
+ \key{style}
+ Value: the name of a style defined with |\declaretheoremstyle| or
+ |\newtheoremstyle|. The theorem will use the settings of this style.
+
+ \key{preheadhook}
+ Value: \LaTeX\ code. This code will be executed at the beginning of the
+ environment, even before vertical spacing is added and the head is
+ typeset. However, it is already within the group defined by the
+ environment.
+
+ \key{postheadhook}
+ Value: \LaTeX\ code. This code will be executed after the call to the
+ original begin-theorem code. Note that all backends seem to delay
+ typesetting the actual head, so code here should probably enter
+ horizontal mode to be sure it is after the head, but this will change
+ the spacing/wrapping behaviour if your body starts with another list.
+
+ \key{prefoothook}
+ Value: \LaTeX\ code. This code will be executed at the end of the body
+ of the environment.
+
+ \key{postfoothook}
+ Value: \LaTeX\ code. This code will be executed at the end of the
+ environment, even after eventual vertical spacing, but still within the
+ group defined by the environment.
+
+ \key{refname}
+ Value: one string, or two strings separated by a comma (no spaces). This
+ is the name of the theorem as used by |\autoref|, |\cref| and friends. If it is
+ two strings, the second is the plural form used by |\cref|. Default
+ value is the value of |name|, i.e. usually the environment name, with
+ |\MakeUppercase| prepended.
+
+ \key{Refname}
+ Value: one string, or two strings separated by a comma (no spaces). This
+ is the name of the theorem as used by |\Autoref|, |\Cref| and friends. If it is
+ two strings, the second is the plural form used by |\Cref|. This can be
+ used for alternate spellings, for example if your style requests no
+ abbreviations at the beginning of a sentence. No default.
+
+
+ \key{shaded}
+ Value: a key-value list, where the following keys are possible:
+ \begin{description}
+ \item[textwidth]
+ The linewidth within the theorem.
+ \item[bgcolor]
+ The color of the background of the theorem. Either a color name or a
+ color spec as accepted by |\definecolor|, such as |{gray}{0.5}|.
+ \item[rulecolor]
+ The color of the box surrounding the theorem. Either a color name or
+ a color spec.
+ \item[rulewidth]
+ The width of the box surrounding the theorem.
+ \item[margin]
+ The length by which the shade box surrounds the text.
+ \end{description}
+
+ \key{thmbox}
+ Value: one of the characters |L|, |M| and |S|; see examples in \autoref{sec:styling}.
+
+
+ \section{Known keys to in-document theorems}
+ \def\keydefaultcontext{theorem}
+
+ \key{label} Value: a legal |\label| name.
+ Issues a |\label| command after the theorem's head.
+
+ \key{name} Value: \TeX\ code that will be typeset.
+ What you would have put in the optional argument in the
+ non-keyval style, i.e. the note to the head. This is \emph{not} the same
+ as the |name| key to |\declaretheorem|, you cannot override that from within
+ the document.
+
+ \key{listhack} Value: doesn't matter. (But put something to trigger
+ key-val behaviour, maybe |listhack=true|.) Linebreak styles in \pkg{amsthm}
+ don't linebreak if they start with another list, like an |enumerate|
+ environment. Giving the |listhack| key fixes that. \emph{Don't} give this
+ key for non-break styles, you'll get too little vertical space! (Just use
+ |\leavevmode| manually there.)
+ An all-around |listhack| that handles both situations might come in a
+ cleaner rewrite of the style system.
+
+ \section{Restatable -- hints and caveats}
+
+ TBD.
+ \begin{itemize}
+ \item Some counters are saved so that the same values appear when you
+ re-use them. The list of these counters is stored in the macro
+ |\thmt@innercounters| as a comma-separated list without spaces; default: |equation|.
+
+ \item To preserve the influence of other counters (think: equation
+ numbered per section and recall the theorem in another section), we need
+ to know all macros that are used to turn a counter into printed output.
+ Again, comma-separated list without spaces, without leading backslash, stored as
+ |\thmt@counterformatters|. Default:
+ |@alph,@Alph,@arabic,@roman,@Roman,@fnsymbol|.
+ All these only take
+ the \LaTeX\ counter |\c@foo| as arguments. If you bypass this and use
+ |\romannumeral|, your numbers go wrong and you get what you deserve.
+ Important if you have very strange numbering, maybe using greek letters
+ or somesuch.
+
+ \item I think you cannot have one stored counter within another one's
+ typeset representation. I don't think that ever occurs in reasonable
+ circumstances, either. Only one I could think of: multiple subequation
+ blocks that partially overlap the theorem. Dude, that doesn't even nest.
+ You get what you deserve.
+
+ \item |\label| and \pkg{amsmath}'s |\ltx@label| are disabled inside the
+ starred execution. Possibly, |\phantomsection| should be disabled as
+ well?
+ \end{itemize}
+
+ \appendix
+
+
+ \chapter{\Thmtools for the morbidly curious}\label{cha:sourcecode}
+
+ This chapter consists of the implementation of \thmtools, in case you
+ wonder how this or that feature was implemented. Read on if you want a
+ look under the bonnet, but you enter at your own risk, and bring an oily
+ rag with you.
+
+ \section{Core functionality}
+
+ \subsection{The main package}
+ \DocInput{thmtools.dtx}
+
+ \subsection{Adding hooks to the relevant commands}
+ \DocInput{thm-patch.dtx}
+
+ \subsection{The key-value interfaces}
+ \DocInput{thm-kv.dtx}
+
+ \subsection{Lists of theorems}
+ \DocInput{thm-listof.dtx}
+
+ \subsection{Re-using environments}
+ \DocInput{thm-restate.dtx}
+
+ \subsection{Fixing \texttt{autoref} and friends}
+ \DocInput{thm-autoref.dtx}
+
+ \section{Glue code for different backends}
+
+ \subsection{\texttt{amsthm}}
+ \DocInput{thm-amsthm.dtx}
+
+ \subsection{\texttt{beamer}}
+ \DocInput{thm-beamer.dtx}
+
+ \subsection{\texttt{ntheorem}}
+ \DocInput{thm-ntheorem.dtx}
+
+ \section{Generic tools}
+
+ \subsection{A generalized argument parser}
+ \DocInput{parseargs.dtx}
+
+ \subsection{Different counters sharing the same register}
+ \DocInput{aliasctr.dtx}
+
+ \subsection{Tracking occurrences: none, one or many}
+ \DocInput{unique.dtx}
+
+
+
+
+\end{document}