summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex')
-rw-r--r--macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex112
1 files changed, 95 insertions, 17 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex
index ff9a02f154..9934cd5c86 100644
--- a/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex
+++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex
@@ -18,7 +18,6 @@ This also loads
the library \mylib{skins}, see \Vref{sec:skins},
the library \mylib{raster}, see \Vref{sec:raster},
the library \mylib{listings}, see \Vref{sec:listings},
-the library \mylib{xparse}, see \Vref{sec:xparse},
and a bunch of packages, namely
|makeidx|, |marginnote|, |refcount|, and |hyperref|.
The packages |pifont| and |marvosym| should be installed for some symbols, but
@@ -73,10 +72,9 @@ For |minted| \cite{poore:minted} support, load:
\end{docCommand}
\end{dispExample}
\begin{dispExample}
-\begin{docCommand}[color definition=blue]{foomakedocSubKey*}%
- {\marg{name}\marg{key path}}
- Creates a new environment \meta{name} based on \refEnv{docKey} for the
- documentation of keys with the given \meta{key path}.
+\begin{docCommand}[doc no index,color definition=blue]{section}%
+ {\sarg\marg{title}}
+ Starts a section. The star variant is unnumbered.
\end{docCommand}
\end{dispExample}
\end{docEnvironment}
@@ -98,14 +96,12 @@ For |minted| \cite{poore:minted} support, load:
\begin{dispExample}
\begin{docCommands}[
doc no index, % no index entries for this example
- doc name = newtheorem,
- doc parameter = \marg{envname},
+ doc name = newtheorem
]
{
- { },
+ { doc parameter = \sarg\marg{envname} },
{ doc parameter = \marg{envname}\oarg{numbered within} },
- { doc parameter = \oarg{numbered like}\marg{envname} },
- { doc name = newtheorem* },
+ { doc parameter = \oarg{numbered like}\marg{envname} }
}
example
\end{docCommands}
@@ -352,7 +348,7 @@ The macro \docAuxCommand{fooaux} holds some interesting data.
}
Documents an auxiliary or minor \LaTeX\ environment with given \meta{name}.
The given \meta{options} are set with \refCom{tcbset}.
- This macro is automatically indexed indexed for \refCom{docAuxEnvironment}
+ This macro is automatically indexed for \refCom{docAuxEnvironment}
and has no index entry for \refCom{docAuxEnvironment*}.
\begin{dispExample}
The environment \docAuxEnvironment{fooauxenv} holds some interesting data.
@@ -452,7 +448,7 @@ This is a \cs{foocommand}.
\end{docCommand}
\begin{docCommand}{meta}{\marg{text}}
- Macro from |doc| \cite{mittelbach:2011a} to typeset a meta \meta{text}.
+ Macro from |doc| \cite{mittelbach:doc} to typeset a meta \meta{text}.
The library overwrites the original macro.
\begin{dispExample}
This is a \meta{text}.
@@ -564,10 +560,11 @@ heading line. Optionally, such a box can be split in an upper and a lower part.
\end{docEnvironment}
\clearpage
-\begin{docCommand}[doc updated=2020-04-22]{tcbmakedocSubKey}{\marg{name}\marg{key path}}
+\begin{docCommand}[doc updated=2023-12-01]{tcbmakedocSubKey}{\oarg{options}\marg{name}\marg{key path}}
Creates a new environment \meta{name} based on \refEnv{docKey} for the
documentation of keys with the given \meta{key path} as root.
The new environment \meta{name} takes the same para\-meters as \refEnv{docKey} itself.
+ The given \meta{options} are prepended to options of the \meta{name} environment.
A second starred environment \meta{name} is also created, which is identical
to \meta{name} but without index entry.
\begin{dispExample}
@@ -584,10 +581,12 @@ Some key (not indexed).
\end{docCommand}
-\begin{docCommand}[doc new=2020-04-22]{tcbmakedocSubKeys}{\marg{name}\marg{key path}}
+\begin{docCommand}[doc new and updated={2020-04-22}{2023-12-01}]{tcbmakedocSubKeys}{\oarg{options}\marg{name}\marg{key path}}
Creates a new environment \meta{name} based on \refEnv{docKeys} for the
documentation of keys with the given \meta{key path} as root.
The new environment \meta{name} takes the same para\-meters as \refEnv{docKeys} itself.
+ The given \meta{options} are prepended to options of the \meta{name} environment
+ (see \refKey{/tcb/index key formatter} for an example).
\begin{dispExample}
\tcbmakedocSubKeys{docFooKeys}{foo}
@@ -826,6 +825,85 @@ with another note.
\clearpage
+\begin{docTcbKeys}[
+ doc new = {2023-12-01},
+ doc name = doc key prefix,
+ doc parameter = {=\meta{key prefix}},
+ doc description = {no default, initially |/|},
+ ]{}
+ Sets the \meta{key prefix} (root path) of the key to document.
+ This prefix is prepended to \refKey{/tcb/doc keypath}, if
+ \refKey{/tcb/doc keypath} is not empty.
+ The default |/| setting is intended for |pgfkeys|.
+ For |l3keys|, setting \refKey{/tcb/doc key prefix} to be empty is more
+ appropriate, since their path starts with a module name without |/|.
+\begin{dispExample}
+\begin{docKeys}[
+ doc no index, % no index entries for this example
+ doc key prefix = ,
+ doc keypath = tcobox,% module name
+ doc name = my_l3_key,
+ doc parameter = {=\meta{some value}},
+ doc description = example,
+ ] {}
+ Documentation of a key using |l3keys|.
+\end{docKeys}
+\end{dispExample}
+\end{docTcbKeys}
+
+
+
+\begin{docTcbKeys}[
+ doc new = {2023-12-01},
+ doc parameter = \colOpt{=\meta{macro}},
+ doc description = {no default, initially empty},
+ ]{
+ {
+ doc name = index key formatter,
+ },
+ {
+ doc name = index keys formatter,
+ }
+ }
+Sets \meta{macro} as formatter for the text given by
+\refKey{/tcb/doclang/key} or
+\refKey{/tcb/doclang/keys} inside the index.
+The \meta{macro} has to take one mandatory
+argument (the language text).
+The intended purpose is to differentiate between different sorts of
+keys, if necessary, e.g.\ between |pgfkeys| and |l3keys|.
+If these options are used without value, the formatters are reset to
+their standard behavior.
+
+\begin{dispExample}
+% See index of this documentation to recognize the effect
+\newcommand{\myFormatPgfkeysIndex}[1]{#1 (\textsf{pgfkeys})}
+\newcommand{\myFormatExplkeysIndex}[1]{#1 (\textsf{l3keys})}
+
+\tcbmakedocSubKey[
+ index key formatter=\myFormatPgfkeysIndex,
+ index keys formatter=\myFormatPgfkeysIndex
+ ]{docFooPgfkey}{foopgf}
+\tcbmakedocSubKey[
+ doc key prefix=,
+ index key formatter=\myFormatExplkeysIndex,
+ index keys formatter=\myFormatExplkeysIndex
+ ]{docFooExplkey}{fooexpl}
+
+\begin{docFooPgfkey}{foo pgf}{=\meta{name}}{no default, initially empty}
+ content
+\end{docFooPgfkey}
+
+\begin{docFooExplkey}{foo expl}{=\meta{name}}{no default, initially empty}
+ content
+\end{docFooExplkey}
+\end{dispExample}
+\end{docTcbKeys}
+
+
+
+\clearpage
+
\begin{docTcbKey}{doc description}{=\meta{description}}{no default, initially empty}
Sets a (short!) additional \meta{description} for
\refEnv{docCommand}, \refEnv{docEnvironment}, or \refEnv{docPathOperation}.
@@ -871,7 +949,7 @@ hand side if too long. Linebreaks can be used inside the \meta{text}.
\begin{docTcbKey}[][doc new={2020-04-23}]{doc sort index}{=\meta{text}}{no default, initially unset}
If used inside the option list of \refEnv{docCommand}, \refEnv{docEnvironment},
\refEnv{docKey}, etc, then \meta{text} is used
- for as sort key for the index instead of the name of the definition.
+ as sort key for the index instead of the name of the definition.
\begin{dispListing}
\begin{docCommands}[
doc name = l_tcobox_example_tl,
@@ -907,7 +985,7 @@ which is commented by a note inside the margin.
\end{docTcbKey}
\begin{docTcbKey}[][doc new=2014-09-19]{doc new}{=\meta{date}}{style, no default}
- Adds a a marginnote with a \enquote{New: \meta{date}} message at the beginning of
+ Adds a marginnote with a \enquote{New: \meta{date}} message at the beginning of
the upper box part. The intended use is inside the option list of
\refEnv{docCommand}, \refEnv{docEnvironment}, etc.
\makeatletter\renewcommand*{\tcbdocnew}[1]{\kvtcb@text@new: #1}\makeatother%
@@ -1096,7 +1174,7 @@ The is an example text.
\tcbset{doc head key={boxsep=4pt,arc=4pt,boxrule=0.6pt,
frame style=fill,interior style=fill,colframe=green!50!black}}
-\begin{docKey}{/foo/myKey}{}{no value}
+\begin{docKey}[foo]{myKey}{}{no value}
This is the documentation of \refKey{/foo/myKey}.
\end{docKey}
\end{dispExample}