summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/thmtools/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-07-18 03:01:08 +0000
committerNorbert Preining <norbert@preining.info>2020-07-18 03:01:08 +0000
commit63c4f21a5716ebbed11926d0bfbb26d656a766ea (patch)
treec02159e6ceb2453208664129ccda8ff306147328 /macros/latex/contrib/thmtools/doc
parent4ea983e3d411ade406c09b30ece9139457516b6f (diff)
CTAN sync 202007180301
Diffstat (limited to 'macros/latex/contrib/thmtools/doc')
-rw-r--r--macros/latex/contrib/thmtools/doc/COPYING416
-rw-r--r--macros/latex/contrib/thmtools/doc/VERSION.tex1
-rw-r--r--macros/latex/contrib/thmtools/doc/changes.txt12
-rw-r--r--macros/latex/contrib/thmtools/doc/thmtools-manual.pdfbin0 -> 227619 bytes
-rw-r--r--macros/latex/contrib/thmtools/doc/thmtools-manual.tex1166
5 files changed, 1595 insertions, 0 deletions
diff --git a/macros/latex/contrib/thmtools/doc/COPYING b/macros/latex/contrib/thmtools/doc/COPYING
new file mode 100644
index 0000000000..2244313901
--- /dev/null
+++ b/macros/latex/contrib/thmtools/doc/COPYING
@@ -0,0 +1,416 @@
+The LaTeX Project Public License
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+LPPL Version 1.3c 2008-05-04
+
+Copyright 1999 2002-2008 LaTeX3 Project
+ Everyone is allowed to distribute verbatim copies of this
+ license document, but modification of it is not allowed.
+
+
+PREAMBLE
+========
+
+The LaTeX Project Public License (LPPL) is the primary license under
+which the LaTeX kernel and the base LaTeX packages are distributed.
+
+You may use this license for any work of which you hold the copyright
+and which you wish to distribute. This license may be particularly
+suitable if your work is TeX-related (such as a LaTeX package), but
+it is written in such a way that you can use it even if your work is
+unrelated to TeX.
+
+The section `WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE',
+below, gives instructions, examples, and recommendations for authors
+who are considering distributing their works under this license.
+
+This license gives conditions under which a work may be distributed
+and modified, as well as conditions under which modified versions of
+that work may be distributed.
+
+We, the LaTeX3 Project, believe that the conditions below give you
+the freedom to make and distribute modified versions of your work
+that conform with whatever technical specifications you wish while
+maintaining the availability, integrity, and reliability of
+that work. If you do not see how to achieve your goal while
+meeting these conditions, then read the document `cfgguide.tex'
+and `modguide.tex' in the base LaTeX distribution for suggestions.
+
+
+DEFINITIONS
+===========
+
+In this license document the following terms are used:
+
+ `Work'
+ Any work being distributed under this License.
+
+ `Derived Work'
+ Any work that under any applicable law is derived from the Work.
+
+ `Modification'
+ Any procedure that produces a Derived Work under any applicable
+ law -- for example, the production of a file containing an
+ original file associated with the Work or a significant portion of
+ such a file, either verbatim or with modifications and/or
+ translated into another language.
+
+ `Modify'
+ To apply any procedure that produces a Derived Work under any
+ applicable law.
+
+ `Distribution'
+ Making copies of the Work available from one person to another, in
+ whole or in part. Distribution includes (but is not limited to)
+ making any electronic components of the Work accessible by
+ file transfer protocols such as FTP or HTTP or by shared file
+ systems such as Sun's Network File System (NFS).
+
+ `Compiled Work'
+ A version of the Work that has been processed into a form where it
+ is directly usable on a computer system. This processing may
+ include using installation facilities provided by the Work,
+ transformations of the Work, copying of components of the Work, or
+ other activities. Note that modification of any installation
+ facilities provided by the Work constitutes modification of the Work.
+
+ `Current Maintainer'
+ A person or persons nominated as such within the Work. If there is
+ no such explicit nomination then it is the `Copyright Holder' under
+ any applicable law.
+
+ `Base Interpreter'
+ A program or process that is normally needed for running or
+ interpreting a part or the whole of the Work.
+
+ A Base Interpreter may depend on external components but these
+ are not considered part of the Base Interpreter provided that each
+ external component clearly identifies itself whenever it is used
+ interactively. Unless explicitly specified when applying the
+ license to the Work, the only applicable Base Interpreter is a
+ `LaTeX-Format' or in the case of files belonging to the
+ `LaTeX-format' a program implementing the `TeX language'.
+
+
+
+CONDITIONS ON DISTRIBUTION AND MODIFICATION
+===========================================
+
+1. Activities other than distribution and/or modification of the Work
+are not covered by this license; they are outside its scope. In
+particular, the act of running the Work is not restricted and no
+requirements are made concerning any offers of support for the Work.
+
+2. You may distribute a complete, unmodified copy of the Work as you
+received it. Distribution of only part of the Work is considered
+modification of the Work, and no right to distribute such a Derived
+Work may be assumed under the terms of this clause.
+
+3. You may distribute a Compiled Work that has been generated from a
+complete, unmodified copy of the Work as distributed under Clause 2
+above, as long as that Compiled Work is distributed in such a way that
+the recipients may install the Compiled Work on their system exactly
+as it would have been installed if they generated a Compiled Work
+directly from the Work.
+
+4. If you are the Current Maintainer of the Work, you may, without
+restriction, modify the Work, thus creating a Derived Work. You may
+also distribute the Derived Work without restriction, including
+Compiled Works generated from the Derived Work. Derived Works
+distributed in this manner by the Current Maintainer are considered to
+be updated versions of the Work.
+
+5. If you are not the Current Maintainer of the Work, you may modify
+your copy of the Work, thus creating a Derived Work based on the Work,
+and compile this Derived Work, thus creating a Compiled Work based on
+the Derived Work.
+
+6. If you are not the Current Maintainer of the Work, you may
+distribute a Derived Work provided the following conditions are met
+for every component of the Work unless that component clearly states
+in the copyright notice that it is exempt from that condition. Only
+the Current Maintainer is allowed to add such statements of exemption
+to a component of the Work.
+
+ a. If a component of this Derived Work can be a direct replacement
+ for a component of the Work when that component is used with the
+ Base Interpreter, then, wherever this component of the Work
+ identifies itself to the user when used interactively with that
+ Base Interpreter, the replacement component of this Derived Work
+ clearly and unambiguously identifies itself as a modified version
+ of this component to the user when used interactively with that
+ Base Interpreter.
+
+ b. Every component of the Derived Work contains prominent notices
+ detailing the nature of the changes to that component, or a
+ prominent reference to another file that is distributed as part
+ of the Derived Work and that contains a complete and accurate log
+ of the changes.
+
+ c. No information in the Derived Work implies that any persons,
+ including (but not limited to) the authors of the original version
+ of the Work, provide any support, including (but not limited to)
+ the reporting and handling of errors, to recipients of the
+ Derived Work unless those persons have stated explicitly that
+ they do provide such support for the Derived Work.
+
+ d. You distribute at least one of the following with the Derived Work:
+
+ 1. A complete, unmodified copy of the Work;
+ if your distribution of a modified component is made by
+ offering access to copy the modified component from a
+ designated place, then offering equivalent access to copy
+ the Work from the same or some similar place meets this
+ condition, even though third parties are not compelled to
+ copy the Work along with the modified component;
+
+ 2. Information that is sufficient to obtain a complete,
+ unmodified copy of the Work.
+
+7. If you are not the Current Maintainer of the Work, you may
+distribute a Compiled Work generated from a Derived Work, as long as
+the Derived Work is distributed to all recipients of the Compiled
+Work, and as long as the conditions of Clause 6, above, are met with
+regard to the Derived Work.
+
+8. The conditions above are not intended to prohibit, and hence do not
+apply to, the modification, by any method, of any component so that it
+becomes identical to an updated version of that component of the Work as
+it is distributed by the Current Maintainer under Clause 4, above.
+
+9. Distribution of the Work or any Derived Work in an alternative
+format, where the Work or that Derived Work (in whole or in part) is
+then produced by applying some process to that format, does not relax or
+nullify any sections of this license as they pertain to the results of
+applying that process.
+
+10. a. A Derived Work may be distributed under a different license
+ provided that license itself honors the conditions listed in
+ Clause 6 above, in regard to the Work, though it does not have
+ to honor the rest of the conditions in this license.
+
+ b. If a Derived Work is distributed under a different license, that
+ Derived Work must provide sufficient documentation as part of
+ itself to allow each recipient of that Derived Work to honor the
+ restrictions in Clause 6 above, concerning changes from the Work.
+
+11. This license places no restrictions on works that are unrelated to
+the Work, nor does this license place any restrictions on aggregating
+such works with the Work by any means.
+
+12. Nothing in this license is intended to, or may be used to, prevent
+complete compliance by all parties with all applicable laws.
+
+
+NO WARRANTY
+===========
+
+There is no warranty for the Work. Except when otherwise stated in
+writing, the Copyright Holder provides the Work `as is', without
+warranty of any kind, either expressed or implied, including, but not
+limited to, the implied warranties of merchantability and fitness for a
+particular purpose. The entire risk as to the quality and performance
+of the Work is with you. Should the Work prove defective, you assume
+the cost of all necessary servicing, repair, or correction.
+
+In no event unless required by applicable law or agreed to in writing
+will The Copyright Holder, or any author named in the components of the
+Work, or any other party who may distribute and/or modify the Work as
+permitted above, be liable to you for damages, including any general,
+special, incidental or consequential damages arising out of any use of
+the Work or out of inability to use the Work (including, but not limited
+to, loss of data, data being rendered inaccurate, or losses sustained by
+anyone as a result of any failure of the Work to operate with any other
+programs), even if the Copyright Holder or said author or said other
+party has been advised of the possibility of such damages.
+
+
+MAINTENANCE OF THE WORK
+=======================
+
+The Work has the status `author-maintained' if the Copyright Holder
+explicitly and prominently states near the primary copyright notice in
+the Work that the Work can only be maintained by the Copyright Holder
+or simply that it is `author-maintained'.
+
+The Work has the status `maintained' if there is a Current Maintainer
+who has indicated in the Work that they are willing to receive error
+reports for the Work (for example, by supplying a valid e-mail
+address). It is not required for the Current Maintainer to acknowledge
+or act upon these error reports.
+
+The Work changes from status `maintained' to `unmaintained' if there
+is no Current Maintainer, or the person stated to be Current
+Maintainer of the work cannot be reached through the indicated means
+of communication for a period of six months, and there are no other
+significant signs of active maintenance.
+
+You can become the Current Maintainer of the Work by agreement with
+any existing Current Maintainer to take over this role.
+
+If the Work is unmaintained, you can become the Current Maintainer of
+the Work through the following steps:
+
+ 1. Make a reasonable attempt to trace the Current Maintainer (and
+ the Copyright Holder, if the two differ) through the means of
+ an Internet or similar search.
+
+ 2. If this search is successful, then enquire whether the Work
+ is still maintained.
+
+ a. If it is being maintained, then ask the Current Maintainer
+ to update their communication data within one month.
+
+ b. If the search is unsuccessful or no action to resume active
+ maintenance is taken by the Current Maintainer, then announce
+ within the pertinent community your intention to take over
+ maintenance. (If the Work is a LaTeX work, this could be
+ done, for example, by posting to comp.text.tex.)
+
+ 3a. If the Current Maintainer is reachable and agrees to pass
+ maintenance of the Work to you, then this takes effect
+ immediately upon announcement.
+
+ b. If the Current Maintainer is not reachable and the Copyright
+ Holder agrees that maintenance of the Work be passed to you,
+ then this takes effect immediately upon announcement.
+
+ 4. If you make an `intention announcement' as described in 2b. above
+ and after three months your intention is challenged neither by
+ the Current Maintainer nor by the Copyright Holder nor by other
+ people, then you may arrange for the Work to be changed so as
+ to name you as the (new) Current Maintainer.
+
+ 5. If the previously unreachable Current Maintainer becomes
+ reachable once more within three months of a change completed
+ under the terms of 3b) or 4), then that Current Maintainer must
+ become or remain the Current Maintainer upon request provided
+ they then update their communication data within one month.
+
+A change in the Current Maintainer does not, of itself, alter the fact
+that the Work is distributed under the LPPL license.
+
+If you become the Current Maintainer of the Work, you should
+immediately provide, within the Work, a prominent and unambiguous
+statement of your status as Current Maintainer. You should also
+announce your new status to the same pertinent community as
+in 2b) above.
+
+
+WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE
+======================================================
+
+This section contains important instructions, examples, and
+recommendations for authors who are considering distributing their
+works under this license. These authors are addressed as `you' in
+this section.
+
+Choosing This License or Another License
+----------------------------------------
+
+If for any part of your work you want or need to use *distribution*
+conditions that differ significantly from those in this license, then
+do not refer to this license anywhere in your work but, instead,
+distribute your work under a different license. You may use the text
+of this license as a model for your own license, but your license
+should not refer to the LPPL or otherwise give the impression that
+your work is distributed under the LPPL.
+
+The document `modguide.tex' in the base LaTeX distribution explains
+the motivation behind the conditions of this license. It explains,
+for example, why distributing LaTeX under the GNU General Public
+License (GPL) was considered inappropriate. Even if your work is
+unrelated to LaTeX, the discussion in `modguide.tex' may still be
+relevant, and authors intending to distribute their works under any
+license are encouraged to read it.
+
+A Recommendation on Modification Without Distribution
+-----------------------------------------------------
+
+It is wise never to modify a component of the Work, even for your own
+personal use, without also meeting the above conditions for
+distributing the modified component. While you might intend that such
+modifications will never be distributed, often this will happen by
+accident -- you may forget that you have modified that component; or
+it may not occur to you when allowing others to access the modified
+version that you are thus distributing it and violating the conditions
+of this license in ways that could have legal implications and, worse,
+cause problems for the community. It is therefore usually in your
+best interest to keep your copy of the Work identical with the public
+one. Many works provide ways to control the behavior of that work
+without altering any of its licensed components.
+
+How to Use This License
+-----------------------
+
+To use this license, place in each of the components of your work both
+an explicit copyright notice including your name and the year the work
+was authored and/or last substantially modified. Include also a
+statement that the distribution and/or modification of that
+component is constrained by the conditions in this license.
+
+Here is an example of such a notice and statement:
+
+ %% pig.dtx
+ %% Copyright 2005 M. Y. Name
+ %
+ % This work may be distributed and/or modified under the
+ % conditions of the LaTeX Project Public License, either version 1.3
+ % of this license or (at your option) any later version.
+ % The latest version of this license is in
+ % http://www.latex-project.org/lppl.txt
+ % and version 1.3 or later is part of all distributions of LaTeX
+ % version 2005/12/01 or later.
+ %
+ % This work has the LPPL maintenance status `maintained'.
+ %
+ % The Current Maintainer of this work is M. Y. Name.
+ %
+ % This work consists of the files pig.dtx and pig.ins
+ % and the derived file pig.sty.
+
+Given such a notice and statement in a file, the conditions
+given in this license document would apply, with the `Work' referring
+to the three files `pig.dtx', `pig.ins', and `pig.sty' (the last being
+generated from `pig.dtx' using `pig.ins'), the `Base Interpreter'
+referring to any `LaTeX-Format', and both `Copyright Holder' and
+`Current Maintainer' referring to the person `M. Y. Name'.
+
+If you do not want the Maintenance section of LPPL to apply to your
+Work, change `maintained' above into `author-maintained'.
+However, we recommend that you use `maintained', as the Maintenance
+section was added in order to ensure that your Work remains useful to
+the community even when you can no longer maintain and support it
+yourself.
+
+Derived Works That Are Not Replacements
+---------------------------------------
+
+Several clauses of the LPPL specify means to provide reliability and
+stability for the user community. They therefore concern themselves
+with the case that a Derived Work is intended to be used as a
+(compatible or incompatible) replacement of the original Work. If
+this is not the case (e.g., if a few lines of code are reused for a
+completely different task), then clauses 6b and 6d shall not apply.
+
+
+Important Recommendations
+-------------------------
+
+ Defining What Constitutes the Work
+
+ The LPPL requires that distributions of the Work contain all the
+ files of the Work. It is therefore important that you provide a
+ way for the licensee to determine which files constitute the Work.
+ This could, for example, be achieved by explicitly listing all the
+ files of the Work near the copyright notice of each file or by
+ using a line such as:
+
+ % This work consists of all files listed in manifest.txt.
+
+ in that place. In the absence of an unequivocal list it might be
+ impossible for the licensee to determine what is considered by you
+ to comprise the Work and, in such a case, the licensee would be
+ entitled to make reasonable conjectures as to which files comprise
+ the Work.
+
diff --git a/macros/latex/contrib/thmtools/doc/VERSION.tex b/macros/latex/contrib/thmtools/doc/VERSION.tex
new file mode 100644
index 0000000000..9bfeb6f890
--- /dev/null
+++ b/macros/latex/contrib/thmtools/doc/VERSION.tex
@@ -0,0 +1 @@
+\def\VERSION{2020/07/16 v69}
diff --git a/macros/latex/contrib/thmtools/doc/changes.txt b/macros/latex/contrib/thmtools/doc/changes.txt
new file mode 100644
index 0000000000..c16fb63e78
--- /dev/null
+++ b/macros/latex/contrib/thmtools/doc/changes.txt
@@ -0,0 +1,12 @@
+2019-12-22 Frank Mittelbach <Frank.Mittelbach@latex-project.org>
+
+ * thm-kv.dtx:
+ removed dependency on etexcmds package
+
+2020-07-16 Yukai Chou <muzimuzhi@gmail.com>
+
+ * thm-restate.dtx:
+ made compatible with cleveref's \label[]{} syntax
+
+ * thmtools-manual.tex (and comment part of dtx files):
+ refined manual
diff --git a/macros/latex/contrib/thmtools/doc/thmtools-manual.pdf b/macros/latex/contrib/thmtools/doc/thmtools-manual.pdf
new file mode 100644
index 0000000000..8d9ff5fc01
--- /dev/null
+++ b/macros/latex/contrib/thmtools/doc/thmtools-manual.pdf
Binary files differ
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}