diff options
Diffstat (limited to 'macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex')
| -rw-r--r-- | macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex | 331 |
1 files changed, 174 insertions, 157 deletions
diff --git a/macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex b/macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex index bb7c34d5e5..42c22187fd 100644 --- a/macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex +++ b/macros/latex/contrib/keytheorems/doc/keytheorems-doc.tex @@ -1,26 +1,29 @@ -% !TeX program = txs:///pdflatex/[--shell-escape] | txs:///makeindex | txs:///pdflatex/[--shell-escape] | txs:///view-pdf +% !TeX program = txs:///lualatex | txs:///makeindex | txs:///lualatex | txs:///view-pdf \PassOptionsToPackage{hyperindex}{hyperref} \PassOptionsToPackage{dvipsnames}{xcolor} \documentclass{ltxdoc} \usepackage{geometry} \geometry{margin=1in} \usepackage{tcolorbox} +\PassOptionsToPackage{highlightmode=immediate}{minted} \tcbuselibrary{documentation,minted} \tcbset{ listing engine=minted, minted language=latex, } -\ifTUTeX\else +\ifTUTeX +\usepackage{newcomputermodern} +\else \usepackage{lmodern} \usepackage[T1]{fontenc} +\usepackage{amssymb} \fi \usetikzlibrary{cd} \usepackage{booktabs} \usepackage{keytheorems} \usepackage{cleveref} -\usepackage{amssymb} -\def\version{0.1.4} +\def\version{0.1.5} \title{% \pkg{keytheorems} package \\[1ex] @@ -169,6 +172,8 @@ A \LaTeX{} kernel no older than 2023-06-01 is required; if older than 2024-06-01 Every key in this section can be given as a package option with \cs{usepackage}\bracks{\meta{options}}\ttbraces{keytheorems} or in \cs{keytheoremset}\marg{options}, with the exception that \refKey{continues-code} can only be used in the latter. \end{docCommand} +\subsection{Compatibility options} + \begin{docKey}{overload} {} {initially unset} @@ -180,40 +185,37 @@ This is automatically set by \refKey{thmtools-compat}. {} {initially unset} For compatibility with \pkg{thmtools} syntax. -Currently defines the commands in the left column below. +For most documents, \cs{usepackage}\bracks{thmtools-compat}\ttbraces{keytheorems} should be a drop-in replacement for \cs{usepackage}\ttbraces{amsthm,thmtools}. +The option defines the commands in the left column below. The right column lists the corresponding \pkg{keytheorems} replacement that should be used in new documents. \begin{center} -\begin{tabular}{cc} -\pkg{thmtools} command & \pkg{keytheorems} replacement \\ +\begin{tabular}{rcl} +\multicolumn{1}{c}{\pkg{thmtools} command} & & \multicolumn{1}{c}{\pkg{keytheorems} replacement} \\ \toprule -\docAuxCommand*{declaretheorem} & \refCom{newkeytheorem} \\ -\docAuxCommand*{declaretheoremstyle} & \refCom{newkeytheoremstyle} \\ -\docAuxCommand*{listoftheorems} & \refCom{listofkeytheorems} \\ -\begin{tabular}{c} +\docAuxCommand*{declaretheorem} & $\rightarrow$ & \refCom{newkeytheorem} \\ +\docAuxCommand*{declaretheoremstyle} & $\rightarrow$ & \refCom{newkeytheoremstyle} \\ +\docAuxCommand*{listoftheorems} & $\rightarrow$ & \refCom{listofkeytheorems} \\ +\docAuxCommand*{listtheoremname} & $\rightarrow$ & \refKey{title} key \\ +\begin{tabular}{r@{}} \docAuxCommand*{addtotheorempreheadhook}\\ \docAuxCommand*{addtotheorempostheadhook}\\ \docAuxCommand*{addtotheoremprefoothook}\\ \docAuxCommand*{addtotheorempostfoothook}\\ -\end{tabular} & \refCom{addtotheoremhook} \\ -\docAuxEnvironment*{restatable} environment & \refKey{store} key \\ -\docAuxEnvironment*{restatable*} environment & \refKey[store*]{store} key +\end{tabular} & $\rightarrow$ & \refCom{addtotheoremhook} \\ +\docAuxEnvironment*{restatable} environment & $\rightarrow$ & \refKey{store} key \\ +\docAuxEnvironment*{restatable*} environment & $\rightarrow$ & \refKey[store*]{store} key \end{tabular} \end{center} Also defined are the \docAuxKey*{shaded} and \docAuxKey*{thmbox} keys, implemented internally with \pkg{tcolorbox} rather than the \pkg{shadethm} and \pkg{thmbox} packages, respectively. \end{docKey} -\begin{docKey}{store-all} - {} - {initially unset} -Tells \pkg{keytheorems} to grab the body of each theorem so it can later be printed with the \refKey{print-body} option of \refCom{listofkeytheorems}. -Note that this means a theorem body \emph{cannot} contain verbatim material. -\end{docKey} +\subsection{Other global options} -\begin{docKey}{restate-counters} - {=\marg{comma-list of counters}} - {initially \ttbraces{equation}} -Additional counters whose values are preserved when a theorem is restated. -This key does not reset the list, so you don't need to include |equation| in \meta{comma-list}. +\begin{docKey}{auto-translate} + {\colOpt{=true\textbar false}} + {default |true|, initially |true|} +If |false|, \pkg{keytheorems} does not automatically translate the title text for \refCom{listofkeytheorems} and the note produced by the \refKey{continues} key. +These texts can be manually customized with the \refKey{title} and \refKey{continues-code} keys, respectively. \end{docKey} \begin{docKey}{continues-code} @@ -230,14 +232,21 @@ Currently (likely inaccurate!) translations exist for French, German, Italian, P Redefines \cs{qedsymbol} to be \meta{symbol}. \end{docKey} -\begin{docKey}{auto-translate} - {\colOpt{=true\textbar false}} - {default |true|, initially |true|} -If |false|, \pkg{keytheorems} does not automatically translate the title text for \refCom{listofkeytheorems} and the note produced by the \refKey{continues} key. -These texts can be manually customized with the \refKey{title} and \refKey{continues-code} keys, respectively. +\begin{docKey}{restate-counters} + {=\marg{comma-list of counters}} + {initially \ttbraces{equation}} +Additional counters whose values are preserved when a theorem is restated. +This key does not reset the list, so you don't need to include |equation| in \meta{comma-list}. +\end{docKey} + +\begin{docKey}{store-all} + {} + {initially unset} +Tells \pkg{keytheorems} to grab the body of each theorem so it can later be printed with the \refKey{print-body} option of \refCom{listofkeytheorems}. +Note that this means a theorem body \emph{cannot} contain verbatim material. \end{docKey} -\begin{docKey}{store-sets-translate} +\begin{docKey}{store-sets-label} {} {initially unset} Defines the \refKey{store} key to also set \refKey{label}, i.e. it makes |store=|\meta{tag} equivalent to |store=|\meta{tag}|,label=|\meta{tag}. Similarly for \refKey[store*]{store}. @@ -424,7 +433,7 @@ Adds the theorem to a custom sequence \meta{name} that can then be listed with \ See \refKey{listof/seq} for more details. \end{docKey} -\subsection{Keys inherited from \pkg{thmtools}} \label{thm-thmtools-keys} +\subsection{Keys also defined in \pkg{thmtools}} \label{thm-thmtools-keys} These are the \oarg{options} available to \cs{newkeytheorem}. Except for \refKey{thm/name} and \refKey{style}, each key below can also be used in \refCom{newkeytheoremstyle}. @@ -433,7 +442,7 @@ For more description, see the \href{https://ctan.org/pkg/thmtools}{\pkg{thmtools \begin{docKey}[][doc label=thm/name]{name} {=\meta{display name}} {initially title-cased \meta{env name}} -Aliases \docAuxKey{title} and \docAuxKey{heading}. +Aliases \docAuxKey{heading} and \docAuxKey{title}. \begin{tcbwritetemp} \newkeytheorem{mythm}[name=Some Name] @@ -545,6 +554,28 @@ Some text \end{docKeys} +\begin{docKey}{qed} + {\colOpt{=\meta{symbol}}} + {default \cs{openbox}, initially unset} +Adds \colOpt{\meta{symbol}} to the end of the theorem body. +If no value is given, the symbol \openbox\ is used. + +\begin{tcbwritetemp} +\newkeytheorem{example}[qed] +\newkeytheorem{solution}[qed=$\clubsuit$] +\end{tcbwritetemp} + +\begin{keythmscode}[withpreamble] +\begin{example} +Some text +\end{example} +\begin{solution} +Some more text +\end{solution} +\end{keythmscode} + +\end{docKey} + \begin{docKey}{refname} {=\meta{ref name} \textrm{or} \brackets{\meta{singular name},\meta{plural name}}} {initially \meta{display name}} @@ -582,28 +613,6 @@ Consider \cref{abc,def}. \end{docKey} -\begin{docKey}{qed} - {\colOpt{=\meta{symbol}}} - {default \cs{openbox}, initially unset} -Adds \colOpt{\meta{symbol}} to the end of the theorem body. -If no value is given, the symbol \openbox\ is used. - -\begin{tcbwritetemp} -\newkeytheorem{example}[qed] -\newkeytheorem{solution}[qed=$\clubsuit$] -\end{tcbwritetemp} - -\begin{keythmscode}[withpreamble] -\begin{example} -Some text -\end{example} -\begin{solution} -Some more text -\end{solution} -\end{keythmscode} - -\end{docKey} - \subsection{Keys added by \pkg{keytheorems}} \label{thm-added-keys} \begin{docKey}{tcolorbox} @@ -631,7 +640,7 @@ The theorem head is typeset as a tcolorbox title; to avoid this see \refKey{tcol \begin{corollary} Some text \end{corollary} -\begin{definition} +\begin{definition}[A nice definition] Some more text \end{definition} \end{keythmscode} @@ -704,57 +713,55 @@ The defined style can be used with either the \refKey{style} key or the traditio For the AMS classes \cls{amsart}, \cls{amsbook}, and \cls{amsproc}, as well as the \cls{amsart}-based \cls{acmart}, the initial key values are slightly different than what's below in order to match those class's defaults. \end{notebox} -\subsection{Keys inherited from \pkg{thmtools}} +\subsection{Keys also defined in \pkg{thmtools}} The following keys have the same meaning and syntax as the corresponding \pkg{thmtools} keys. In addition to the list below, most of the keys available to \refCom{newkeytheorem} can be used in \cs{newkeytheoremstyle}. -\begin{docKey}{spaceabove} - {=\meta{length}} - {initially \cs{topsep}} +\begin{docKey}{bodyfont} + {=\meta{font declarations}} + {initially \cs{itshape}} \end{docKey} -\begin{docKey}{spacebelow} - {=\meta{length}} - {initially \cs{topsep}} - +\begin{docKey}{break} + {} + {initially unset} +Do not use this with the \refKey{postheadspace} key. \end{docKey} -\begin{docKey}{bodyfont} +\begin{docKey}{headfont} {=\meta{font declarations}} - {initially \cs{itshape}} + {initially \cs{bfseries}} + +\end{docKey} +\begin{docKey}{headformat} + {=\docValue{margin}\textbar\docValue{swapnumber}\textbar\meta{code using \cs{NAME}, \cs{NUMBER}, and \cs{NOTE}\,}} + {} +Alias \docAuxKey{headstyle}. Within \meta{code}, the commands \docAuxCommand{NAME}, \docAuxCommand{NUMBER}, and \docAuxCommand{NOTE} correspond to the formatted parts of the theorem head. \end{docKey} +\begin{notebox} +In \refKey{headformat}, you may also use the traditional \pkg{amsthm} commands \cs{thmname}, \cs{thmnumber}, and \cs{thmnote}, where |#1| is the theorem name, |#2| the number, and |#3| the note. \pkg{keytheorems} expands the head spec inside |\text_expand:n| so for these commands to work properly, the package adds them to |\l_text_expand_exclude_tl|. Note also that if you use these lower-level commands, the style keys \refKey{notebraces}, \refKey{notefont}, \refKey{noteseparator}, and \refKey{numberfont} will have no effect (of course, you can manually control these things inside the commands' arguments). +\end{notebox} + \begin{docKey}{headindent} {=\meta{length}} {initially |0pt|} \end{docKey} -\begin{docKey}{headfont} - {=\meta{font declarations}} - {initially \cs{bfseries}} - -\end{docKey} - \begin{docKey}{headpunct} {=\meta{code}} {initially \ttbraces{.}} \end{docKey} -\begin{docKey}{postheadspace} - {=\meta{length}} - {initially |5pt plus 1pt minus 1pt|} -Do not use this with the \refKey{break} key. -\end{docKey} +\begin{docKey}{notebraces} + {=\marg{left brace}\marg{right brace}} + {initially \ttbraces{(}\ttbraces{)}} -\begin{docKey}{break} - {} - {initially unset} -Do not use this with the \refKey{postheadspace} key. \end{docKey} \begin{docKey}{notefont} @@ -763,20 +770,33 @@ Do not use this with the \refKey{postheadspace} key. \end{docKey} -\begin{docKey}{notebraces} - {=\marg{left brace}\marg{right brace}} - {initially \ttbraces{(}\ttbraces{)}} +\begin{docKey}{postheadspace} + {=\meta{length}} + {initially |5pt plus 1pt minus 1pt|} +Do not use this with the \refKey{break} key. +\end{docKey} + +\begin{docKey}{spaceabove} + {=\meta{length}} + {initially \cs{topsep}} \end{docKey} -\begin{docKey}{headformat} - {=\docValue{margin}\textbar\docValue{swapnumber}\textbar\meta{code using \cs{NAME}, \cs{NUMBER}, and \cs{NOTE}}} - {} -Alias \docAuxKey{headstyle}. Within \meta{code}, the commands \docAuxCommand{NAME}, \docAuxCommand{NUMBER}, and \docAuxCommand{NOTE} correspond to the formatted parts of the theorem head. +\begin{docKey}{spacebelow} + {=\meta{length}} + {initially \cs{topsep}} + \end{docKey} \subsection{Keys added by \pkg{keytheorems}} +\begin{docKey}{inherit-style} + {=\meta{style name}} + {initially unset} +Inherit the keys of any style declared with \refCom{newkeytheoremstyle}. +Additionally, the three styles predefined by \pkg{amsthm} are possible values: \docValue{plain}, \docValue{definition}, and \docValue{remark}. +\end{docKey} + \begin{docKey}{noteseparator} {=\meta{code}} {initially \textvisiblespace} @@ -789,13 +809,6 @@ The code inserted before the note, and printed only if there is a note. This is For almost all theorem styles, it is recommended that you \emph{do not} change this setting. \end{docKey} -\begin{docKey}{inherit-style} - {=\meta{style name}} - {initially unset} -Inherit the keys of any style declared with \refCom{newkeytheoremstyle}. -Additionally, the three styles predefined by \pkg{amsthm} are possible values: \docValue{plain}, \docValue{definition}, and \docValue{remark}. -\end{docKey} - \section{Restating theorems} When a theorem is given the \refKey{store} key, the contents of the theorem are saved and written to a |.thlist| file. @@ -868,30 +881,12 @@ For other classes, manual adjustments to \refKey{numwidth} and \refKey{indent} m \subsection{Keys inherited from \pkg{thmtools}} -\begin{docKey}{numwidth} - {=\meta{length}} - {initially |2.3em|} -For the AMS classes, this is initially |1.5pc|. -\end{docKey} - \begin{docKey}{ignore} {=\marg{comma-list of env names}} {initially unset} \end{docKey} -\begin{docKey}{show} - {=\marg{comma-list of env names}} - {initially all theorems} - -\end{docKey} - -\begin{docKey}{onlynamed} - {\colOpt{=\marg{comma-list of env names}}} - {initially unset} - -\end{docKey} - \begin{docKey}{ignoreall} {} {initially unset} @@ -906,12 +901,36 @@ For the AMS classes, this is initially |1.5pc|. \end{docKey} +\begin{docKey}{numwidth} + {=\meta{length}} + {initially |2.3em|} +For the AMS classes, this is initially |1.5pc|. +\end{docKey} + +\begin{docKey}{onlynamed} + {\colOpt{=\marg{comma-list of env names}}} + {initially unset} + +\end{docKey} + +\begin{docKey}{show} + {=\marg{comma-list of env names}} + {initially all theorems} + +\end{docKey} + \begin{docKey}{showall} {} {initially set} \end{docKey} +\begin{docKey}{swapnumber} + {\colOpt{=true\textbar false}} + {initially |false|} + +\end{docKey} + \begin{docKey}{title} {=\meta{text}} {initially \cs{GetTranslation}\ttbraces{keythms\string_listof\string_title}} @@ -920,14 +939,14 @@ Currently French, German, Italian, Portuguese, and Spanish have (likely inaccura A translation can be added with a GitHub pull request or manually with \cs{DeclareTranslation}\marg{lang}\ttbraces{keythms\string_listof\string_title}\marg{text}. \end{docKey} -\begin{docKey}{swapnumber} - {\colOpt{=true\textbar false}} - {initially |false|} +\subsection{Keys added by \pkg{keytheorems}} +\begin{docKey}{format-code} + {=\meta{code with \textup{\texttt{\#1}}, \textup{\texttt{\#2}}, and \textup{\texttt{\#3}}}} + {initially \cs{numberline}\texttt{\{\#2\}\#1\#3}} +Allows full control over the format for list entries. The theorem name is |#1|, the number is |#2|, and the (formatted) note is |#3|. The note formatting is still controlled by \refKey{note-code}. \end{docKey} -\subsection{Keys added by \pkg{keytheorems}} - \begin{docKey}{indent} {=\meta{length}} {initially |1.5em|} @@ -936,25 +955,23 @@ For \cls{memoir} and the AMS classes, the indent is initially |0pt|. It is not recommended to change this unless your class has different defaults not already covered. \end{docKey} -\begin{docKey}{onlynumbered} - {\colOpt{=\marg{comma-list of env names}}} - {initially unset} -Similar to \refKey{onlynamed}, but lists only those theorems which are numbered. -This is useful if you'd like to exclude things like unnumbered definitions and remarks from the list of theorems. +\begin{docKey}{no-chapter-skip} + {\colOpt{=true\textbar false}} + {initially |false|} +By default a small vertical space is inserted between each chapter's chunk of theorems. +Setting this key to |true| removes this space. \end{docKey} -\begin{docKey}[][doc label=listof/seq]{seq} - {=\meta{name}} - {initially unset} -Used to list only the theorems added to the custom sequence \meta{name} with the \refKey{thm/seq} theorem key. -This is the only way to fully customize which theorems appear in the list of theorems. -Unlike with \refKey{show}, you do not need to use \refKey{ignoreall} to prevent theorems not in \meta{name} from being printed. +\begin{docKey}{chapter-skip-length} + {=\meta{dimension}} + {initially |10pt|} +Controls the amount of space inserted between chunks. \end{docKey} -\begin{docKey}{title-code} - {=\meta{code with \textup{\texttt{\#1}}}} - {initially \cs{section*}\ttbraces{\#1}} -If \cs{chapter} is defined, then initially this is instead \cs{chapter*}\ttbraces{\#1}. This key has no effect if used with an AMS class because these classes hard-code the section heading into \cs{@starttoc}. +\begin{docKey}{no-continues} + {\colOpt{=true\textbar false}} + {initially |false|} +Suppresses the printing of theorems given the \refKey{continues} key in the list of theorems. \end{docKey} \begin{docKey}{no-title} @@ -971,12 +988,25 @@ Useful for custom ordering of the list. \end{docKey} +\begin{docKey}{no-toc} + {\colOpt{=true\textbar false}} + {initially false} +With the standard classes, lists of figures/tables are not added to the table of contents by default. The same is true for \cs{listofkeytheorems}, and with those classes this key does nothing. However some classes, notably \cls{memoir} and the AMS classes, do add lists to the table of contents. With these classes, this key suppresses the addition of the list of theorems to the table of contents. +\end{docKey} + \begin{docKey}{note-code} {=\meta{code with \textup{\texttt{\#1}}}} {initially \ttbraces{ (\#1)}} Formats the optional note in the list of theorems. \end{docKey} +\begin{docKey}{onlynumbered} + {\colOpt{=\marg{comma-list of env names}}} + {initially unset} +Similar to \refKey{onlynamed}, but lists only those theorems which are numbered. +This is useful if you'd like to exclude things like unnumbered definitions and remarks from the list of theorems. +\end{docKey} + \begin{docKey}{print-body} {} {initially unset} @@ -984,29 +1014,18 @@ Instead of listing the theorem headings, the theorems are restated with their bo Not very useful without the \refKey{store-all} load-time option. \end{docKey} -\begin{docKey}{no-continues} - {\colOpt{=true\textbar false}} - {initially |false|} -Suppresses the printing of theorems given the \refKey{continues} key in the list of theorems. -\end{docKey} - -\begin{docKey}{no-chapter-skip} - {\colOpt{=true\textbar false}} - {initially |false|} -By default a small vertical space is inserted between each chapter's chunk of theorems. -Setting this key to |true| removes this space. -\end{docKey} - -\begin{docKey}{chapter-skip-length} - {=\meta{dimension}} - {initially |10pt|} -Controls the amount of space inserted between chunks. +\begin{docKey}[][doc label=listof/seq]{seq} + {=\meta{name}} + {initially unset} +Used to list only the theorems added to the custom sequence \meta{name} with the \refKey{thm/seq} theorem key. +This is the only way to fully customize which theorems appear in the list of theorems. +Unlike with \refKey{show}, you do not need to use \refKey{ignoreall} to prevent theorems not in \meta{name} from being printed. \end{docKey} -\begin{docKey}{no-toc} - {\colOpt{=true\textbar false}} - {initially false} -With the standard classes, lists of figures/tables are not added to the table of contents by default. The same is true for \cs{listofkeytheorems}, and with those classes this key does nothing. However some classes, notably \cls{memoir} and the AMS classes, do add lists to the table of contents. With these classes, this key suppresses the addition of the list of theorems to the table of contents. +\begin{docKey}{title-code} + {=\meta{code with \textup{\texttt{\#1}}}} + {initially \cs{section*}\ttbraces{\#1}} +If \cs{chapter} is defined, then initially this is instead \cs{chapter*}\ttbraces{\#1}. This key has no effect if used with an AMS class because these classes hard-code the section heading into \cs{@starttoc}. \end{docKey} \subsection{Adding code to list of theorems} @@ -1064,9 +1083,7 @@ As in \pkg{thmtools}, the order of hooks is as follows: The \hook{restated} hook is applied at the start of theorems retrieved with \cs{getkeytheorem}, before the \hook{prehead} hook. This can be useful for disabling commands such as \cs{footnote} in the restated theorems, e.g. \begin{dispListing} -\addtotheoremhook{restated}{% - \renewcommand\footnote[2][]{}% - } +\addtotheoremhook{restated}{\renewcommand\footnote[2][]{}} \end{dispListing} By default, \pkg{keytheorems} disables the \cs{label} and \cs{RecordProperties} commands in restated theorems. |