% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Library \mylib{documentation}}\label{sec:documentation}%
\tcbset{external/prefix=external/documentation_}%
This library has the single purpose to support \LaTeX\ package documentations
like this one. Actually, the visual nature follows the approach from
Till Tantau's \refPkg{pgf} \cite{tantau:tikz_and_pgf} documentation.
Typically, this library is assumed to be used in conjunction with the
class \refPkg{ltxdoc} or alike.
Denis Bitouz\'e, Yukai Chou, and many others provided very valuable input for this library.

The library is loaded by a package option or inside the preamble by:
\begin{dispListing}
\tcbuselibrary{documentation}
\end{dispListing}
This also loads
the library \mylib{skins}, see \zvref{sec:skins},
the library \mylib{raster}, see \zvref{sec:raster},
the library \mylib{listings}, see \zvref{sec:listings},
and a bunch of packages, namely
\refPkg{makeidx}, \refPkg{marginnote}, \refPkg{refcount}, and \refPkg{hyperref}.
The packages \refPkg{pifont} and \refPkg{marvosym} should be installed for some symbols, but
need not to be loaded.

\begin{marker}
The package \refPkg{makeidx} is loaded only, if \docAuxCommand*{printindex} is
\emph{not} already defined. Therefore, one can include an alternative to \refPkg{makeidx} like
\refPkg{imakeidx} \emph{before} the library \mylib{documentation} is used.
\end{marker}
\begin{marker}
The package \refPkg{marginnote} is loaded only, if \docAuxCommand*{marginnote} is
\emph{not} already defined.
\end{marker}
\begin{marker}
In contrast to other |tcolorbox| options, the option
settings for \mylib{documentation} are typically not
getting reset by \refKey{/tcb/reset}, i.\,e., they keep their
values for embedded boxes.
\end{marker}
\begin{marker}
In combination with DocStrip, \refKey{/tcb/verbatim ignore percent} may be helpful.
\end{marker}

For UTF-8 support load (ignore this when using Xe\LaTeX):
\begin{dispListing}
\tcbuselibrary{listingsutf8,documentation}
\end{dispListing}

For \refPkg{minted} \cite{poore:minted} support, load:
\begin{dispListing}
\tcbuselibrary{documentation,minted}
\tcbset{listing engine=minted}
\end{dispListing}


%\clearpage
%-------------------------------------------------------------------------------
\subsection{Macros of the Library}

\begin{docEnvironment}[doclang/environment content=command description,doc updated=2020-04-22]
    {docCommand}{\oarg{options}\marg{name}\marg{parameters}}
  Documents a \LaTeX\ macro with given \meta{name} where \meta{name} is
  written without backslash. The given \meta{options} are set with \refCom{tcbset}.
  This macro takes mandatory or optional \meta{parameters}.
  It is automatically indexed and can be referenced with
  \refCom{refCom}\marg{name}.
\begin{dispExample}
\begin{docCommand}{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}.
\end{docCommand}
\end{dispExample}
\begin{dispExample}
\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}


\begin{docEnvironment}[doclang/environment content=command description,doc updated=2020-04-22]
    {docCommand*}{\oarg{options}\marg{name}\marg{parameters}}
  Identical to \refEnv{docCommand}, but without index entry.
\end{docEnvironment}


\begin{docEnvironment}[doclang/environment content=command description,doc new=2020-04-22]
    {docCommands}{\oarg{options}\brackets{\marg{variant1},\marg{variant2},...}}
  Documents several (similar) \LaTeX\ macro variants simultaneously.
  The given \meta{options} are set with \refCom{tcbset} and are valid for
  all variants and the documentation text.
  Every variant is described by an option set \meta{variant1}, \meta{variant2}, and so on.
  The most crucial options are \refKey{/tcb/doc name} and \refKey{/tcb/doc parameter}.
\begin{dispExample}
\begin{docCommands}[
    doc no index,  %  no index entries for this example
    doc name      = newtheorem
  ]
  {
    { doc parameter = \sarg\marg{envname} },
    { doc parameter = \marg{envname}\oarg{numbered within} },
    { doc parameter = \oarg{numbered like}\marg{envname} }
  }
  example
\end{docCommands}
\end{dispExample}
\end{docEnvironment}



\clearpage
{\let\xdocEnvironment\docEnvironment
\let\endxdocEnvironment\enddocEnvironment
\begin{xdocEnvironment}[doclang/environment content=environment description,doc updated=2020-04-22]
    {docEnvironment}{\oarg{options}\marg{name}\marg{parameters}}
  Documents a \LaTeX\ environment with given \meta{name}.
  The given \meta{options} are set with \refCom{tcbset}.
  This environment takes mandatory or optional \meta{parameters}.
  It is automatically indexed and can be referenced with
  \refCom{refEnv}\marg{name}.
\begin{dispExample}
\begin{docEnvironment}{foocolorbox}{\oarg{options}}
  This is the main environment to create an accentuated colored text box with
  rounded corners and, optionally, two parts.
\end{docEnvironment}
\end{dispExample}
\begin{dispExample}
\begin{docEnvironment}%
    [doclang/environment content=My content text]%
    {foocolorbox*}{\oarg{options}}
  This is the main environment to create an accentuated colored text box with
  rounded corners and, optionally, two parts.
\end{docEnvironment}
\end{dispExample}
\end{xdocEnvironment}}

{\let\xdocEnvironment\docEnvironment
\let\endxdocEnvironment\enddocEnvironment
\begin{xdocEnvironment}[doclang/environment content=environment description,doc updated=2020-04-22]
    {docEnvironment*}{\oarg{options}\marg{name}\marg{parameters}}
  Identical to \refEnv{docEnvironment}, but without index entry.
\end{xdocEnvironment}}


\clearpage
{\let\xdocEnvironment\docEnvironment
\let\endxdocEnvironment\enddocEnvironment
\begin{xdocEnvironment}[doclang/environment content=environment description,doc new=2020-04-22]
    {docEnvironments}{\oarg{options}\brackets{\marg{variant1},\marg{variant2},...}}
  Documents several (similar) \LaTeX\ environment variants simultaneously.
  The given \meta{options} are set with \refCom{tcbset} and are valid for
  all variants and the documentation text.
  Every variant is described by an option set \meta{variant1}, \meta{variant2}, and so on.
  The most crucial options are \refKey{/tcb/doc name} and \refKey{/tcb/doc parameter}.
\begin{dispExample}
\begin{docEnvironments}[
    doc no index,   %  no index entries for this example
    doc parameter = \oarg{options}\marg{title},
    doclang/environment content = box content,
  ]
  {
    {
      doc name        = redbox,
      doc description = a red colored box,
    },
    {
      doc name        = greenbox,
      doc description = a green colored box,
    },
    {
      doc name        = bluebox,
      doc description = a blue colored box,
    },
    {
      doc name        = custombox,
      doc parameter   = \oarg{options}\marg{color}\marg{title},
      doc description = a colored box,
    },
  }
  example
\end{docEnvironments}
\end{dispExample}
\end{xdocEnvironment}}


\clearpage
\begin{docEnvironment}[doclang/environment content=key description,doc updated=2020-04-22]
    {docKey}{\oarg{key path}\oarg{options}\marg{name}\marg{parameters}\marg{description}}
  Documents a key with given \meta{name} and an optional \meta{key path}.
  The given \meta{options} are set with \refCom{tcbset}.
  This key takes mandatory or optional \meta{parameters} as value
  with a short \meta{description}.
  It is automatically indexed and can be referenced with
  \refCom{refKey}\marg{name}.
\begin{dispExample}
\begin{docKey}[foo]{footitle}{=\meta{text}}{no default, initially empty}
  Creates a heading line with \meta{text} as content.
\end{docKey}
\end{dispExample}
\end{docEnvironment}


\begin{docEnvironment}[doclang/environment content=key description,doc updated=2020-04-22]
    {docKey*}{\oarg{key path}\oarg{options}\marg{name}\marg{parameters}\marg{description}}
  Identical to \refEnv{docKey}, but without index entry.
\end{docEnvironment}


\begin{docEnvironment}[doclang/environment content=key description,doc new=2020-04-22]
    {docKeys}{\oarg{options}\brackets{\marg{variant1},\marg{variant2},...}}
  Documents several (similar) key variants simultaneously.
  The given \meta{options} are set with \refCom{tcbset} and are valid for
  all variants and the documentation text.
  Every variant is described by an option set \meta{variant1}, \meta{variant2}, and so on.
  The most crucial options are
  \refKey{/tcb/doc keypath}, \refKey{/tcb/doc name}, \refKey{/tcb/doc parameter},
  and \refKey{/tcb/doc description}.
\begin{dispExample}
\begin{docKeys}[
    doc no index,   %  no index entries for this example
    doc keypath   = mykeyroot,
    doc parameter = {=\meta{length}},
  ]
  {
    {
      doc name        = width,
      doc description = initially \texttt{10cm},
    },
    {
      doc name        = height,
      doc description = initially \texttt{7cm},
    },
  }
  example
\end{docKeys}
\end{dispExample}
\end{docEnvironment}


\clearpage
\begin{docEnvironment}[doclang/environment content=operation description,
    doc new and updated={2019-09-18}{2020-04-22}]{docPathOperation}{\oarg{options}\marg{name}\marg{parameters}}
  Documents a \tikzname\ path operation with given \meta{name}.
  The given \meta{options} are set with \refCom{tcbset}.
  This \tikzname\ path operation takes mandatory or optional \meta{parameters}.
  It is automatically indexed and can be referenced with
  \refCom{refPathOperation}\marg{name}.
\begin{dispExample}
\begin{docPathOperation}{fooop}{\oarg{opt}(\meta{name})\colOpt{at(\meta{coord})}}
  Imaginary path operation for illustration.
\end{docPathOperation}
\end{dispExample}
\end{docEnvironment}


\begin{docEnvironment}[doclang/environment content=command description,
    doc new and updated={2019-09-18}{2020-04-22}]{docPathOperation*}{\oarg{options}\marg{name}\marg{parameters}}
  Identical to \refEnv{docPathOperation}, but without index entry.
\end{docEnvironment}


\begin{docEnvironment}[doclang/environment content=command description,
    doc new={2020-04-22}]{docPathOperations}{\oarg{options}\brackets{\marg{variant1},\marg{variant2},...}}
  Documents several (similar) \tikzname\ path operation variants simultaneously.
  The given \meta{options} are set with \refCom{tcbset} and are valid for
  all variants and the documentation text.
  Every variant is described by an option set \meta{variant1}, \meta{variant2}, and so on.
  The most crucial options are \refKey{/tcb/doc name} and \refKey{/tcb/doc parameter}.
\begin{dispExample}
\begin{docPathOperations}[
    doc no index,   %  no index entries for this example
  ]
  {
    {
      doc name      = rectangle,
      doc parameter = \meta{corner or cycle},
    },
    {
      doc name      = circle,
      doc parameter = \oarg{options},
    },
    {
      doc name      = ellipse,
      doc parameter = \oarg{options},
    },
  }
  example
\end{docPathOperations}
\end{dispExample}
\end{docEnvironment}


\clearpage
\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name = docValue,
      doc updated=2020-04-23,
    },
    {
      doc name = docValue*,
    },
  }
  Documents a value with given \meta{name}. Typically, this is a value for a key.
  The given \meta{options} are set with \refCom{tcbset}.
  This value is automatically indexed for \refCom{docValue}
  and has no index entry for \refCom{docValue*}.
\begin{dispExample}
A feasible value for \refKey{/foo/footitle} is \docValue*{foovalue}.
\end{dispExample}
\end{docCommands}



\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name    = docAuxCommand,
      doc updated = 2020-04-23,
    },
    {
      doc name = docAuxCommand*,
    },
  }
  Documents an auxiliary or minor \LaTeX\ macro with given \meta{name}
  where \meta{name} is written without backslash.
  The given \meta{options} are set with \refCom{tcbset}.
  This macro is automatically indexed for \refCom{docAuxCommand}
  and has no index entry for \refCom{docAuxCommand*}.
\begin{dispExample}
The macro \docAuxCommand{fooaux} holds some interesting data.
\end{dispExample}
\end{docCommands}



\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name    = docAuxEnvironment,
      doc updated = 2020-04-23,
    },
    {
      doc name = docAuxEnvironment*,
    },
  }
  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 for \refCom{docAuxEnvironment}
  and has no index entry for \refCom{docAuxEnvironment*}.
\begin{dispExample}
The environment \docAuxEnvironment{fooauxenv} holds some interesting data.
\end{dispExample}
\end{docCommands}


\begin{docCommands}[doc parameter=\oarg{key path}\oarg{options}\marg{name}]
  {
    {
      doc name    = docAuxKey,
      doc updated = 2020-04-23,
    },
    {
      doc name = docAuxKey*,
    },
  }
  Documents an auxiliary key with given \meta{name} and an optional \meta{key path}.
  The given \meta{options} are set with \refCom{tcbset}.
  It is automatically indexed for \refCom{docAuxKey}
  and has no index entry for \refCom{docAuxKey*}.
\begin{dispExample}
The key \docAuxKey[foo]{fooaux} holds some interesting data.
\end{dispExample}
\end{docCommands}



\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name    = docCounter,
      doc updated = 2020-04-23,
    },
    {
      doc name = docCounter*,
    },
  }
  Documents a counter with given \meta{name}.
  The given \meta{options} are set with \refCom{tcbset}.
  The counter is automatically indexed for \refCom{docCounter}
  and has no index entry for \refCom{docCounter*}.
\begin{dispExample}
The counter \docCounter{foocounter} can be used for computation.
\end{dispExample}
\end{docCommands}


\clearpage
\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name    = docLength,
      doc updated = 2020-04-23,
    },
    {
      doc name = docLength*,
    },
  }
  Documents a length with given \meta{name}.
  The given \meta{options} are set with \refCom{tcbset}.
  The length is automatically indexed for \refCom{docLength}
  and has no index entry for \refCom{docLength*}.
\begin{dispExample}
The length \docLength{foolength} can be used for computation.
\end{dispExample}
\end{docCommands}


\begin{docCommands}[doc parameter=\oarg{options}\marg{name}]
  {
    {
      doc name    = docColor,
      doc updated = 2020-04-23,
    },
    {
      doc name = docColor*,
    },
  }
  Documents a color with given \meta{name}.
  The given \meta{options} are set with \refCom{tcbset}.
  The color is automatically indexed for \refCom{docColor}
  and has no index entry for \refCom{docColor*}.
\begin{dispExample}
The color \docColor{foocolor} is available.
\end{dispExample}
\end{docCommands}



\begin{docCommand}{cs}{\marg{name}}
  Macro from \refPkg{ltxdoc} \cite{carlisle:ltxdoc} to typeset a command word \meta{name}
  where the backslash is prefixed. The library overwrites the original macro.
\begin{dispExample}
This is a \cs{foocommand}.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{meta}{\marg{text}}
  Macro from \refPkg{doc} \cite{mittelbach:doc} to typeset a meta \meta{text}.
  The library overwrites the original macro.
\begin{dispExample}
This is a \meta{text}.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{marg}{\marg{text}}
  Macro from \refPkg{ltxdoc} \cite{carlisle:ltxdoc} to typeset a \meta{text} with
  curly brackets as a mandatory argument. The library overwrites the original macro.
\begin{dispExample}
This is a mandatory \marg{argument}.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{oarg}{\marg{text}}
  Macro from \refPkg{ltxdoc} \cite{carlisle:ltxdoc} to typeset a \meta{text} with
  square brackets as an optional argument. The library overwrites the original macro.
\begin{dispExample}
This is an optional \oarg{argument}.
\end{dispExample}
\end{docCommand}

\clearpage

\begin{docCommand}[doc new={2025-05-28}]{pbarg}{\marg{text}}
  Renamed macro from the \refPkg{beamer} \cite{tantau:beamer} documentation to
  typeset a \meta{text} with pointed brackets as a mandatory argument.
\begin{dispExample}
This is a |beamer| \pbarg{argument}.
\end{dispExample}
\end{docCommand}


\begin{docCommand}[doc new=2023-02-16]{sarg}{}
  Macro to typeset \sarg{} as an optional star.
\begin{dispExample}
This is an optional \sarg.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{brackets}{\marg{text}}
  Sets the given \meta{text} with curly brackets.
\begin{dispExample}
  Here we use \brackets{some text}.
\end{dispExample}
\end{docCommand}


{\let\xdispExample\dispExample
  \let\endxdispExample\enddispExample
\begin{docEnvironment}[doc updated=2014-10-10]{dispExample}{}
  Creates a colored box based on a \refEnv{tcolorbox}.
  It displays the environment content as source code in the upper part
  and as compiled text in the lower part of the box.
  The appearance is controlled by \refKey{/tcb/documentation listing style}
  and the style \refKey{/tcb/docexample}. It may be
  changed by redefining this style.
{
%\tcbset{before lower app={\tcbset{docexample/.style={docexample original}}}}
%\tcbset{docexample/.style={docexample original}}%
\begin{xdispExample}
\begin{dispExample}
This is a \LaTeX\ example.
\end{dispExample}
\end{xdispExample}
}
\end{docEnvironment}}


{\let\xdispExample\dispExample
  \let\endxdispExample\enddispExample
\begin{docEnvironment}[doc updated=2014-10-10]{dispExample*}{\marg{options}}
  The starred version of \refEnv{dispExample} takes \refEnv{tcolorbox} \meta{options}
  as parameter. These \meta{options} are executed after \refKey{/tcb/docexample}.
\begin{xdispExample}
\begin{dispExample*}{sidebyside}
This is a \LaTeX\ example.
\end{dispExample*}
\end{xdispExample}
\end{docEnvironment}}


\clearpage
\begin{docEnvironment}{dispListing}{}
  Creates a colored box based on a \refEnv{tcolorbox}.
  It displays the environment content as source code.
  The appearance is controlled by \refKey{/tcb/documentation listing style}
  and the style \refKey{/tcb/docexample}. It may be
  changed by redefining this style.
\begin{dispExample}
\begin{dispListing}
This is a \LaTeX\ example.
\end{dispListing}
\end{dispExample}
\end{docEnvironment}

\begin{docEnvironment}{dispListing*}{\marg{options}}
  The starred version of \refEnv{dispListing} takes \refEnv{tcolorbox} \meta{options}
  as parameter. These \meta{options} are executed after \refKey{/tcb/docexample}.
\begin{dispExample}
\begin{dispListing*}{title=My listing}
This is a \LaTeX\ example.
\end{dispListing*}
\end{dispExample}
\end{docEnvironment}


\begin{docEnvironment}{absquote}{}
  Used to typeset an abstract as quoted and small text.
\begin{dispExample}
\begin{absquote}
|tcolorbox| provides an environment for colored and framed text boxes with a
heading line. Optionally, such a box can be split in an upper and a lower part.
\end{absquote}
\end{dispExample}
\end{docEnvironment}

\clearpage
\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}
\tcbmakedocSubKey{docFooKey}{foo}

\begin{docFooKey}{foodummy}{=\meta{nothing}}{no default, initially empty}
Some key.
\end{docFooKey}

\begin{docFooKey*}{foo another dummy}{=\meta{nothing}}{no default, initially empty}
Some key (not indexed).
\end{docFooKey*}
\end{dispExample}
\end{docCommand}


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

\begin{docFooKeys}[
    doc parameter   = {=\meta{nothing}},
    doc description = {no default, initially empty},
  ]
  {
    {
      doc name = foodummy 2,
    },
    {
      doc name = foo another dummy 2,
      doc no index,
    }
  }
Some description.
\end{docFooKeys}
\end{dispExample}
\end{docCommand}


\clearpage

\begin{docCommand}{refCom}{\marg{name}}
  References a documented \LaTeX\ macro with given \meta{name} where \meta{name} is
  written without backslash. The page reference is suppressed if it links
  to the same page.
\begin{dispExample}
We have created \refCom{foomakedocSubKey} as an example.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{refCom*}{\marg{name}}
  References a documented \LaTeX\ macro with given \meta{name} where \meta{name} is
  written without backslash. There is no page reference.
\begin{dispExample}
We have created \refCom*{foomakedocSubKey} as an example.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{refEnv}{\marg{name}}
  References a documented \LaTeX\ environment with given \meta{name}.
  The page reference is suppressed if it links to the same page.
\begin{dispExample}
We have created \refEnv{foocolorbox} as an example.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{refEnv*}{\marg{name}}
  References a documented \LaTeX\ environment with given \meta{name}.
  There is no page reference.
\begin{dispExample}
We have created \refEnv*{foocolorbox} as an example.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{refKey}{\marg{name}}
  References a documented key with given \meta{name} where \meta{name}
  is the full path name of the key.
  The page reference is suppressed if it links to the same page.
\begin{dispExample}
We have created \refKey{/foo/footitle} as an example.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{refKey*}{\marg{name}}
  References a documented key with given \meta{name} where \meta{name}
  is the full path name of the key.
  There is no page reference.
\begin{dispExample}
We have created \refKey*{/foo/footitle} as an example.
\end{dispExample}
\end{docCommand}

\clearpage

\begin{docCommand}[doc new=2019-09-17]{refPathOperation}{\marg{name}}
  References a documented \tikzname\ path operation with given \meta{name}.
  The page reference is suppressed if it links to the same page.
\begin{dispExample}
We have created \refPathOperation{fooop} as an example.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc new=2019-09-17]{refPathOperation*}{\marg{name}}
  References a documented \tikzname\ path operation with given \meta{name}.
  There is no page reference.
\begin{dispExample}
We have created \refPathOperation*{fooop} as an example.
\end{dispExample}
\end{docCommand}



\begin{docCommand}[doc updated=2020-02-11]{refAux}{\marg{name}}
  References some auxiliary environment, key, value, or color.
  The \meta{name} is colored according to \refKey{/tcb/color hyperlink},
  if \refPkg{hyperref} colorlinks are set, but there is no real link.
\begin{dispExample}
Some pages back, one can see \refAux{/foo/footitle} as an example.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc updated=2020-02-11]{refAuxcs}{\marg{name}}
  References some auxiliary macro \meta{name} where \meta{name} is
  written without backslash.
  The \meta{name} is colored according to \refKey{/tcb/color hyperlink},
  if \refPkg{hyperref} colorlinks are set, but there is no real link.
\begin{dispExample}
Some pages back, one can see \refAuxcs{fooaux} as an example.
\end{dispExample}
\end{docCommand}


\begin{docCommand}[doc new and updated={2024-09-18}{2024-11-29}]{refPkg}{\oarg{ctanname}\marg{name}}
  References a package \meta{name} on \href{https://ctan.org}{CTAN} with
  hyperlink \mbox{|https://ctan.org/pkg/|\meta{name}}.
  Using the option \meta{ctanname} creates the hyperlink
  \mbox{|https://ctan.org/pkg/|\meta{ctanname}}.
  The appearance of the \href{https://ctan.org}{CTAN} text can be
  customized by \refKey{/tcb/ctan formatter}.
\begin{dispExample}
\tcbset{ctan formatter=\texttt}
Hyperlinks are created with help of the \refPkg{hyperref} package.\par
The package \refPkg[frankenstein]{dialogue} is part of the
\refPkg{frankenstein} bundle of packages.
\end{dispExample}
\end{docCommand}


\clearpage

\begin{docCommand}{colDef}{\marg{text}}
Sets \meta{text} with the command color, see \refKey{/tcb/color command}.
\begin{dispExample}
This is my \colDef{text}.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{colOpt}{\marg{text}}
  Sets \meta{text} with the option color, see \refKey{/tcb/color option}.
\begin{dispExample}
This is my \colOpt{text}.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc new=2019-09-18]{colFade}{\marg{text}}
  Sets \meta{text} with the fade color, see \refKey{/tcb/color fade}.
\begin{dispExample}
This is my \colFade{text}.
\end{dispExample}
\end{docCommand}


\begin{docCommand}[doc new=2014-09-19]{tcbdocmarginnote}{\oarg{options}\marg{text}}
  Creates a |tcolorbox| note with the given \meta{text} inside the margin using
  the \refPkg{marginnote} package. The style of the |tcolorbox| is predefined and can be
  altered by \refKey{/tcb/doc marginnote} and the given \meta{options}.
\begin{dispExample}
Some text\tcbdocmarginnote{Note A}
which is commented by a note inside the margin.
Alternatively to |\tcbdocmarginnote|, you can always use
|\marginnote| with a |tcolorbox| directly.\par
This is further text%
\tcbdocmarginnote[colframe=blue!50!white,colback=blue!5!white]{Note B}
with another note.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc new=2014-09-19]{tcbdocnew}{\marg{date}}
  Auxiliary macro which typesets the \refKey{/tcb/doclang/new} text with
  the given \meta{date}. It may be redefined for customization.
  \makeatletter\renewcommand*{\tcbdocnew}[1]{\kvtcb@text@new: #1}\makeatother%
\begin{dispExample*}{sidebyside}
\tcbdocnew{1981-10-29}.
% Next one is displayed in the margin:
\tcbdocmarginnote{\tcbdocnew{1978-02-09}}
\end{dispExample*}
\end{docCommand}

\begin{docCommand}[doc new=2014-09-19]{tcbdocupdated}{\marg{date}}
  Auxiliary macro which typesets the \refKey{/tcb/doclang/updated} text with
  the given \meta{date}. It may be redefined for customization.
  \makeatletter\renewcommand*{\tcbdocupdated}[1]{\kvtcb@text@updated: #1}\makeatother%
\begin{dispExample*}{sidebyside}
\tcbdocupdated{2014-09-19}.
\end{dispExample*}
\end{docCommand}


\clearpage
%-------------------------------------------------------------------------------
\subsection{Lists of Choices for Key Documentation}

\enlargethispage*{10mm}
\begin{docCommands}[doc parameter=\marg{comma separated list of choices}]
  {
    {
      doc name = docKeyChoices,
      doc new  = 2025-09-25,
    },
    {
      doc name = docKeyChoices*,
    },
  }
  Inside the parameter list of \refEnv{docKey}, \refEnv{docKey*}, or \refEnv{docKeys}
  to document a key, this macro can be used to give
  a \meta{comma separated list of choices}.
  These choices are typeset with one leading |=| and \refKey{/tcb/doc key choices separator}
  as separator between every value. Long lists are broken automatically at a width
  which is configured by \refKey{/tcb/doc head left width} or \refKey{/tcb/doc head left ratio}.\par
  The star variant is for optional values and uses \refCom{colOpt}.
  \begin{marker}
  Usage of \refCom{docKeyChoices} outside the parameter list of a key
  documentation is not intended and is not supported.
  \end{marker}
\begin{dispExample}
\begin{docKey}[foo]{fooexam1}{\docKeyChoices{one,two,three}}
    {no default, initially \texttt{one}}
  Example for mandatory choices.
\end{docKey}
\end{dispExample}
\begin{dispExample}
\begin{docKey}[foo]{fooexam2}{\docKeyChoices*{
  zero,one,two,three,four,five,six,seven,eight,nine,ten,eleven,twelve,
  thirteen,fourteen,fiveteen,sixteen,seventeen,eightteen,nineteen,twenty }}
    {default \texttt{one}, initially \texttt{zero}}
  Example for optional choices.
\end{docKey}
\end{dispExample}
\begin{dispExample}
\begin{docKey}[foo][doc head left ratio=0.8]{fooexam3}{\docKeyChoices*{
  zero,one,two,three,four,five,six,seven,eight,nine,ten,eleven,twelve,
  thirteen,fourteen,fiveteen,sixteen,seventeen,eightteen,nineteen,twenty }}
    {default \texttt{one},\\ initially \texttt{zero}}
\end{docKey}
\end{dispExample}
\begin{dispExample}
\begin{docKey}[foo][doc head left ratio=1.0]{fooexam4}{\docKeyChoices*{
  zero,one,two,three,four,five,six,seven,eight, \\ nine,ten,eleven,twelve,
  thirteen,fourteen,fiveteen,sixteen,seventeen,eightteen,nineteen,twenty }}
    {default \texttt{one}, initially \texttt{zero}}
\end{docKey}
\end{dispExample}
\end{docCommands}

\clearpage
\enlargethispage*{10mm}

\begin{docTcbKeys}[
    doc parameter   = {=\meta{comma separated list of choices}},
    doc description = {style, no default},
  ]{
    {
      doc new         = {2025-09-25},
      doc name        = doc key choices,
    },
    {
      doc name        = doc key choices*,
    },
  }
  These options are shortcuts for setting \refKey{/tcb/doc parameter} with
  \refCom{docKeyChoices} or \refCom{docKeyChoices*} respectively, i.\,e.,
  to have a \meta{comma separated list of choices}
  inside the parameter list of \refEnv{docKeys}.\par
  The star variant is for optional values and uses \refCom{colOpt}.
\begin{dispExample}
\begin{docKeys}[
    doc keypath      = foo,
    doc name         = fooexam5,
    doc key choices* = {true,false},
    doc description  = {default \texttt{true}, initially \texttt{true}},
  ]{}
\end{docKeys}
\end{dispExample}
\begin{dispExample}
\begin{docKeys}[
    doc keypath     = foo,
    doc name        = fooexam6,
    doc key choices = {
      zero,one,two,three,four,five,six,seven,eight,nine,ten,eleven,twelve,
      thirteen,fourteen,fiveteen,sixteen,seventeen,eightteen,nineteen,twenty },
    doc head left ratio = 0.6,
    doc description = {no default, initially \texttt{zero}},
  ]{}
\end{docKeys}
\end{dispExample}
\end{docTcbKeys}

\begin{docTcbKeys}[
    doc new         = {2025-09-25},
    doc name        = doc key choices separator,
    doc parameter   = {=\meta{separator}},
    doc description = {no default, initially \texttt{\textbackslash textbar}},
  ]{}
  Sets the \meta{separator} sign which used for typsetting lists of choices
  from \refCom{docKeyChoices}, \refKey{/tcb/doc key choices}, and friends.
\begin{dispExample}
\begin{docKeys}[
    doc key choices separator = \textbullet,
    doc keypath      = foo,
    doc name         = fooexam7,
    doc key choices* = {true,false,maybe,unlikely},
    doc description  = {default \texttt{true}, initially \texttt{true}},
  ]{}
\end{docKeys}
\end{dispExample}
\end{docTcbKeys}


\begin{docTcbKeys}[
    doc new         = {2025-09-25},
    doc name        = doc head left width,
    doc parameter   = {=\meta{length}},
    doc description = {no default, initially \texttt{0.7\textbackslash columnwidth}},
  ]{}
  The given \meta{length} is the maximal width of a box consisting of
  key name, |=| sign, and a list of choices. See also \refKey{/tcb/doc head left ratio}.
\end{docTcbKeys}


\begin{docTcbKeys}[
    doc new         = {2025-09-25},
    doc name        = doc head left ratio,
    doc parameter   = {=\meta{number}},
    doc description = {style, initially \texttt{0.7}},
  ]{}
  The given rational \meta{number} should be in the range between |0.0| and |1.0|.
  This option sets \refKey{/tcb/doc head left width} to
  \texttt{\meta{number}\textbackslash columnwidth}.
  See examples of \refCom{docKeyChoices} and \refKey{/tcb/doc key choices}.
\end{docTcbKeys}



\clearpage
%-------------------------------------------------------------------------------
\subsection{Entry Content Option Keys}


\begin{docTcbKey}[][doc new={2020-04-22}]{doc name}{=\meta{name}}{no default, initially empty}
  Sets the \meta{name} of the entry to document, i.\,e., the \meta{name} of the
  command, environment, key, etc. For \refEnv{docCommand}, \refEnv{docEnvironment}, etc.
  the \meta{name} is set by a mandatory parameter, but can also be set
  by \refKey{/tcb/doc name}.
  \refKey{/tcb/doc name} also sets \meta{name} to
  \refKey{/tcb/doc label}, \refKey{/tcb/doc index},
  and \refKey{/tcb/doc sort index}.
\begin{dispExample}
\begin{docCommands}[
    doc no index,  %  no index entries for this example
    doc name      = bfseries,
  ] {}
  Font setting to bold face.
\end{docCommands}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new={2020-04-22}]{doc parameter}{=\meta{parameters}}{no default, initially empty}
  Sets the \meta{parameters} of the entry to document, i.\,e., the \meta{parameters} of the
  command, environment, key, etc. For \refEnv{docCommand}, \refEnv{docEnvironment}, etc.
  the \meta{parameters} is set by a mandatory option, but can also be set
  by \refKey{/tcb/doc parameter}.
\begin{dispExample}
\begin{docCommands}[
    doc no index,  %  no index entries for this example
    doc name      = textbf,
    doc parameter = \marg{text},
  ] {}
  Sets \meta{text} in bold face.
\end{docCommands}
\end{dispExample}
\end{docTcbKey}



\begin{docTcbKey}[][doc new={2020-04-22}]{doc keypath}{=\meta{key path}}{no default, initially empty}
  Sets the \meta{key path} of the key to document. For \refEnv{docKey}
  and \refEnv{docKey*} the \meta{key path}  is set by a specialized option,
  but can also be set by \refKey{/tcb/doc keypath}.
\begin{dispExample}
\begin{docKeys}[
    doc no index,  %  no index entries for this example
    doc keypath     = tikz,
    doc name        = fill,
    doc parameter   = \colOpt{=\meta{color}},
    doc description = default is scope's color setting,
  ] {}
  This option causes the path to be filled.
\end{docKeys}
\end{dispExample}
\end{docTcbKey}

\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 \refPkg{pgfkeys}.
  For \refPkg[l3kernel]{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 \refPkg{pgfkeys} and \refPkg[l3kernel]{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}.
  Such a description is
  mandatory for \refEnv{docKey}.
\begin{dispExample}
\begin{docCommand*}[doc description=my description]{myCommandF}{\marg{argument}}
  This is the documentation of \refCom{myCommandF} which takes one \meta{argument}.
  \refCom{myCommandF} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\begin{marker}
Note that the description \meta{text} may overlap with the text on the left
hand side if too long. Linebreaks can be used inside the \meta{text}.
\end{marker}
\end{docTcbKey}


\begin{docTcbKey}[][doc new={2019-09-18}]{doc label}{=\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 labeling instead of the name of the definition.
\begin{dispExample}
\begin{docPathOperation*}[doc label=pathline]{-{}-}{\meta{coordinate or cycle}}
  This is the documentation of \refPathOperation{pathline}.
\end{docPathOperation*}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}[][doc new={2020-01-07}]{doc 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 the index instead of the name of the definition.
\begin{dispExample}
\begin{docPathOperation}[doc index=foo path (horizontal then vertical),
    doc label=pathline2]{-\textbar}{\meta{coordinate or cycle}}
  This is the documentation of \refPathOperation{pathline2}.
\end{docPathOperation}
\end{dispExample}
\end{docTcbKey}


\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
  as sort key for the index instead of the name of the definition.
\begin{dispListing}
\begin{docCommands}[
    doc name        = l_tcobox_example_tl,
    doc sort index  = example_tl,  % sorted under e like example
  ]{}
\end{docCommands}
\end{dispListing}
\end{docTcbKey}

\clearpage

\begin{docTcbKey}{doc into index}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
  If set to |false|, no index entries are written for the main documentation
  environments. The same effect is achieved by using e.\,g.\ \refEnv{docCommand*}
  instead of \refEnv{docCommand}.
\end{docTcbKey}


\begin{docTcbKey}[][doc new={2020-04-22}]{doc no index}{}{style, initially unset}
  If set, no index entries are written for the main documentation
  environments. This is a shortcut for using \refKey{/tcb/doc into index}|=false|.
\end{docTcbKey}



\begin{docTcbKey}[][doc new=2014-09-19]{doc marginnote}{=\meta{options}}{no default, initially empty}
  Sets style \meta{options} for the displayed box of the \refCom{tcbdocmarginnote} command.
\begin{dispExample}
\tcbset{doc marginnote={colframe=blue!50!white,colback=blue!5!white}}%
This is some text\tcbdocmarginnote{Note A}
which is commented by a note inside the margin.
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{doc new}{=\meta{date}}{style, no default}
  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%
\begin{dispExample}
\begin{docCommand}[doc new=2000-01-01]{foosomething}{\marg{text}}
Some command for something.
\end{docCommand}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2014-09-19]{doc updated}{=\meta{date}}{style, no default}
  Adds a marginnote with a \enquote{Updated: \meta{date}} message at the beginning of
  the upper box part. See \refKey{/tcb/doc new}.
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2014-09-19]{doc new and updated}{=\marg{new date}\marg{update date}}{style, no default}
  Adds a marginnote with \enquote{New: \meta{new date}} and \enquote{Updated: \meta{update date}} messages at the beginning of
  the upper box part. See \refKey{/tcb/doc new}.
\end{docTcbKey}



\clearpage
%-------------------------------------------------------------------------------
\subsection{Entry Customization Option Keys}


\begin{docTcbKey}{doc left}{=\meta{length}}{no default, initially |2em|}
  Sets the left hand offset of the documentation texts from
  \refEnv{docCommand}, \refEnv{docEnvironment}, \refEnv{docKey}, etc, to \meta{length}.
\begin{dispExample}
\begin{docCommand*}[doc left=2cm,doc left indent=-2cm]{myCommandA}{\marg{argument}}
  This is the documentation of \refCom{myCommandA} which takes one \meta{argument}.
  \refCom{myCommandA} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{doc right}{=\meta{length}}{no default, initially |0em|}
  Sets the right hand offset of the documentation texts from
  \refEnv{docCommand}, \refEnv{docEnvironment}, \refEnv{docKey}, etc, to \meta{length}.
\begin{dispExample}
\begin{docCommand*}[doc right=2cm]{myCommandB}{\marg{argument}}
  This is the documentation of \refCom{myCommandB} which takes one \meta{argument}.
  \refCom{myCommandB} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{doc left indent}{=\meta{length}}{no default, initially |-2em|}
  Sets the left hand indent of documentation heads from
  \refEnv{docCommand}, \refEnv{docEnvironment}, \refEnv{docKey}, etc, to \meta{length}.
\begin{dispExample}
\begin{docCommand*}[doc left indent=2cm]{myCommandC}{\marg{argument}}
  This is the documentation of \refCom{myCommandC} which takes one \meta{argument}.
  \refCom{myCommandC} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}{doc right indent}{=\meta{length}}{no default, initially |0pt|}
  Sets the right hand indent of documentation heads from
  \refEnv{docCommand}, \refEnv{docEnvironment}, \refEnv{docKey}, etc, to \meta{length}.
\begin{dispExample}
\begin{docCommand*}[doc right indent=-10mm,doc right=10mm,
    doc description=test value]{myCommandD}{\marg{argument}}
  This is the documentation of \refCom{myCommandD} which takes one \meta{argument}.
  \refCom{myCommandD} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}

\clearpage
The head lines of the main documentation environments \refEnv{docCommand},
\refEnv{docEnvironment}, \refEnv{docKey}, etc, are |tcolorbox|es inside a
\refEnv{tcbraster}.
Options to the surrounding |tcbraster|s and the embedded
|tcolorbox|es can be given using the following keys.


\begin{docTcbKeys}[
  doc name        = doc raster command,
  doc parameter   = {=\meta{options}},
  doc description = {no default, initially empty},
  doc new         = 2020-04-24,
]{}
  Sets \meta{options} for the surrounding \refEnv{tcbraster} of\\
  \refEnv{docCommand}, \refEnv{docCommand*}, and \refEnv{docCommands}.

\begin{dispExample}
\tcbset{doc raster command={raster before skip=7mm,raster after skip=0mm}}

The is an example text.

\begin{docCommand*}{myCommandI}{\marg{argument}}
  This is the documentation of \refCom{myCommandI} which takes one \meta{argument}.
  \refCom{myCommandI} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}

\end{docTcbKeys}


\begin{docTcbKeys}[
  doc name        = doc raster environment,
  doc parameter   = {=\meta{options}},
  doc description = {no default, initially empty},
  doc new         = 2020-04-24,
]{}
  Sets \meta{options} for the surrounding \refEnv{tcbraster} of\\
  \refEnv{docEnvironment}, \refEnv{docEnvironment*}, and \refEnv{docEnvironments}.
\end{docTcbKeys}


\begin{docTcbKeys}[
  doc name        = doc raster key,
  doc parameter   = {=\meta{options}},
  doc description = {no default, initially empty},
  doc new         = 2020-04-24,
]{}
  Sets \meta{options} for the surrounding \refEnv{tcbraster} of\\
  \refEnv{docKey}, \refEnv{docKey*}, and \refEnv{docKeys}.
\end{docTcbKeys}


\begin{docTcbKeys}[
  doc name        = doc raster path,
  doc parameter   = {=\meta{options}},
  doc description = {no default, initially empty},
  doc new         = 2020-04-24,
]{}
  Sets \meta{options} for the surrounding \refEnv{tcbraster} of\\
  \refEnv{docPathOperation}, \refEnv{docPathOperation*}, and \refEnv{docPathOperations}.
\end{docTcbKeys}


\begin{docTcbKeys}[
  doc name        = doc raster,
  doc parameter   = {=\meta{options}},
  doc description = {no default, initially empty},
  doc new         = 2020-04-24,
]{}
  Shortcut for setting the same \meta{options} for
  \refKey{/tcb/doc raster command}, \refKey{/tcb/doc raster environment},
  \refKey{/tcb/doc raster key}, and \refKey{/tcb/doc raster path}.
\end{docTcbKeys}


\begin{docTcbKey}{doc head command}{=\meta{options}}{no default, initially empty}
  Sets \meta{options} for the head line of
  \refEnv{docCommand}, \refEnv{docCommand*}, and \refEnv{docCommands}.
\begin{dispExample}
\tcbset{doc head command={interior style={fill,left color=red!20!white,
  right color=blue!20!white}}}

\begin{docCommand*}{myCommandE}{\marg{argument}}
  This is the documentation of \refCom{myCommandE} which takes one \meta{argument}.
  \refCom{myCommandE} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}


\clearpage

\begin{docTcbKey}{doc head environment}{=\meta{options}}{no default, initially empty}
  Sets \meta{options} for the head line of
  \refEnv{docEnvironment}, \refEnv{docEnvironment*}, and \refEnv{docEnvironments}.
\begin{dispExample}
\tcbset{doc head environment={beamer,boxsep=2pt,arc=2pt,colback=green!20!white}}

\begin{docEnvironment*}{myEnvironment}{\marg{argument}}
  This is the documentation of \refEnv{myEnvironment} which
  takes one \meta{argument}.
\end{docEnvironment*}
\end{dispExample}
\end{docTcbKey}

\begin{docTcbKey}{doc head key}{=\meta{options}}{no default, initially empty}
  Sets \meta{options} for the head line of
  \refEnv{docKey}, \refEnv{docKey*}, and \refEnv{docKeys}.
\begin{dispExample}
\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}
  This is the documentation of \refKey{/foo/myKey}.
\end{docKey}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2019-09-18]{doc head path}{=\meta{options}}{no default, initially empty}
  Sets \meta{options} for the head line of
  \refEnv{docPathOperation}, \refEnv{docPathOperation*}, and \refEnv{docPathOperations}.
\begin{dispExample}
\tcbset{doc head command={interior style={fill,left color=red!7!white,
  right color=blue!7!white}}}

\begin{docPathOperation*}{-{}-}{\meta{coordinate or cycle}}
  This is the documentation of \refPathOperation{-{}-}.
\end{docPathOperation*}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc updated=2019-09-18]{doc head}{=\meta{options}}{no default, initially empty}
  Shortcut for setting the same \meta{options} for
  \refKey{/tcb/doc head command}, \refKey{/tcb/doc head environment},
  \refKey{/tcb/doc head key}, and \refKey{/tcb/doc head path}.
\end{docTcbKey}


\clearpage

The description texts of the main documentation environments \refEnv{docCommand},
\refEnv{docEnvironment}, \refEnv{docKey}, etc, are set in a compact form without
indention and |parskip=0pt|. This settings can overruled by using the following
keys to insert code before (or after) the description texts.

\begin{docTcbKey}[][doc new=2015-10-09]{before doc body command}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} before the description texts
  of \refEnv{docCommand} and \refEnv{docCommand*}.
\begin{dispExample}
\tcbset{before doc body command={%
    \setlength{\parindent}{2.5em}%
    \setlength{\parskip}{1ex plus 0.75ex minus 0.25ex}%
}}

\begin{docCommand*}{myCommandG}{\marg{argument}}
  This is the documentation of \refCom{myCommandG} which takes one \meta{argument}.
  \refCom{myCommandG} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2015-10-09]{after doc body command}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} after the description texts
  of \refEnv{docCommand} and \refEnv{docCommand*}.
\begin{dispExample}
\tcbset{after doc body command={%
    \hfill\nolinebreak[1]\hspace*{\fill}\textcolor{red}{$\diamondsuit$}%
}}

\begin{docCommand*}{myCommandH}{\marg{argument}}
  This is the documentation of \refCom{myCommandH} which takes one \meta{argument}.
  \refCom{myCommandH} does some funny things with its \meta{argument}.
\end{docCommand*}
\end{dispExample}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2015-10-09]{before doc body environment}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} before the description texts
  of \refEnv{docEnvironment} and \refEnv{docEnvironment*}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2015-10-09]{after doc body environment}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} after the description texts
  of \refEnv{docEnvironment} and \refEnv{docEnvironment*}.
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2015-10-09]{before doc body key}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} before the description texts
  of \refEnv{docKey} and \refEnv{docKey*}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2015-10-09]{after doc body key}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} after the description texts
  of \refEnv{docKey} and \refEnv{docKey*}.
\end{docTcbKey}

\clearpage

\begin{docTcbKey}[][doc new=2019-09-18]{before doc body path}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} before the description texts
  of \refEnv{docPathOperation} and \refEnv{docPathOperation*}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2019-09-18]{after doc body path}{=\meta{code}}{no default, initially empty}
  Executes \meta{code} after the description texts
  of \refEnv{docPathOperation} and \refEnv{docPathOperation*}.
\end{docTcbKey}


\begin{docTcbKey}[][doc new and updated={2015-10-09}{2019-09-18}]{before doc body}{=\meta{options}}{no default, initially empty}
  Shortcut for setting the same \meta{options} for
  \refKey{/tcb/before doc body command}, \refKey{/tcb/before doc body environment},
  \refKey{/tcb/before doc body key}, and \refKey{/tcb/before doc body path}.
\end{docTcbKey}

\begin{docTcbKey}[][doc new and updated={2015-10-09}{2019-09-18}]{after doc body}{=\meta{options}}{no default, initially empty}
  Shortcut for setting the same \meta{options} for
  \refKey{/tcb/after doc body command}, \refKey{/tcb/after doc body environment},
  \refKey{/tcb/after doc body key}, and \refKey{/tcb/after doc body path}.
\end{docTcbKey}







\clearpage
\subsection{General Customization Option Keys}

\begin{docTcbKey}[][doc updated=2015-03-16]{docexample}{}{style, no value}
  Sets the style for \refEnv{dispExample} and \refEnv{dispListing}
  with the colors |ExampleBack| and |ExampleFrame|.
  To change the appearance of the examples, this style can be
  redefined.
\begin{dispListing}
% Predefined style:
\tcbset{
  docexample/.style={colframe=ExampleFrame,colback=ExampleBack,
    before skip=\medskipamount,after skip=\medskipamount,
    fontlower=\footnotesize}
}
\end{dispListing}
\end{docTcbKey}

\begin{docTcbKey}{documentation listing options}{=\meta{key list}}{no default,\\\hspace*{\fill} initially |style=tcbdocumentation|}
  Sets the options from the package \refPkg{listings} \cite{hoffmann:listings}.
  They are used inside \refEnv{dispExample} and \refEnv{dispListing} to typeset
  the listings. Note that this is not identical to the key
  \refKey{/tcb/listing options} which is used for \enquote{normal} listings.\\
  Used for \refKey{/tcb/listing engine}|=listings| only.
\end{docTcbKey}

\begin{docTcbKey}{documentation listing style}{=\meta{listing style}}{no default, initially |tcbdocumentation|}
  Abbreviation for |documentation listing options={style=...}|.
  This key sets a \meta{style}
  for the \refPkg{listings} package, see \cite{hoffmann:listings}.
  Note that this is not identical to the key
  \refKey{/tcb/listing style} which is used for \enquote{normal} listings.\\
  Used for \refKey{/tcb/listing engine}|=listings| only.
\end{docTcbKey}

\begin{docTcbKey}{documentation minted options}{=\meta{key list}}{no default,\\\hspace*{\fill} initially |tabsize=2,fontsize=\textbackslash small|}
  Sets the options from the package \refPkg{minted} \cite{poore:minted}
  which are used during typesetting of the listing, if used.
  Note that this is not identical to the key
  \refKey{/tcb/minted options} which is used for \enquote{normal} listings.\\
  Used for \refKey{/tcb/listing engine}|=minted| only.
\end{docTcbKey}

\begin{docTcbKey}{documentation minted style}{=\meta{key list}}{no default, initially unset}
  Sets a \meta{style} known to |Pygments| \cite{pygments:web} for
  the package \refPkg{minted} \cite{poore:minted}, if used.
  Note that this is not identical to the key
  \refKey{/tcb/minted style} which is used for \enquote{normal} listings.\\
  Used for \refKey{/tcb/listing engine}|=minted| only.
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2017-04-24]{documentation minted language}{=\meta{programming language}}{no default, initially |latex|}
  Sets a \meta{programming language} known to |Pygments| \cite{pygments:web}
  for the package \refPkg{minted} \cite{poore:minted}, if used.
  Note that this is not identical to the key
  \refKey{/tcb/minted language} which is used for \enquote{normal} listings.\\
  Used for \refKey{/tcb/listing engine}|=minted| only.
\end{docTcbKey}

\clearpage

\begin{docTcbKey}[][doc new=2017-04-25]{keywords bold}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
  Keyword used in \refEnv{docEnvironment}, \refEnv{docCommand}, etc. are printed
  boldface (or not). Since the typewriter font is used, the effect may be
  invisible with Computer Modern fonts or similar which do not
  have a bold variant. Note that references to keywords are not printed boldface at all.
\begin{dispExample*}{sidebyside}
\LARGE
\docAuxCommand{fooaux}, \refCom{tcbset}

\tcbset{keywords bold=false}
\docAuxCommand{fooaux}, \refCom{tcbset}
\end{dispExample*}
\end{docTcbKey}


\begin{docTcbKeys}
  {
    {
      doc name        = page ref formatter,
      doc new         = {2024-03-13},
      doc parameter   = \colOpt{=\meta{macro}},
      doc description = {no default, initially \texttt{\textbackslash textsuperscript}},
    }
  }
Sets \meta{macro} as formatter for page references like the
reference to \refEnv{tcolorbox}.
The default setting puts the page reference in a |\textsuperscript|.
It may be changed to |\fakesuperscript| to cope with superiors problems
in combination with the \refPkg{realscripts} package or just otherwise for user customization.
\end{docTcbKeys}


\begin{docTcbKeys}
  {
    {
      doc name        = ctan formatter,
      doc new         = {2024-11-29},
      doc parameter   = \colOpt{=\meta{macro}},
      doc description = {no default, initially empty},
    }
  }
Sets \meta{macro} as formatter for the string CTAN inside \refCom{refPkg}.
The \meta{macro} has to take one mandatory argument (the string CTAN) and
is typically some font setting.
\begin{dispExample}
\tcbset{ctan formatter=\textsf}
Images are included using the \refPkg{graphicx} package.\par
\newcommand{\myformatter}[1]{\textbf{\ttfamily\color{red}\TeX-Archive}}
\tcbset{ctan formatter=\myformatter}
Draw your own picture with help of the \refPkg{tikz} package.
\end{dispExample}
\end{docTcbKeys}



\begin{docTcbKey}[][doc new=2015-01-09]{index command}{=\meta{macro}}{no default, initially \cs{index}}
  Replaces the internally used \cs{index} macro by the given \meta{macro}.
  The \meta{macro} has to take one mandatory argument like \cs{index}.
  This option is mutually exclusive with \refKey{/tcb/index command name}.
\begin{dispListing}
\tcbset{index command=\myindexcommand}
\end{dispListing}
\end{docTcbKey}


\begin{docTcbKey}[][doc new=2015-01-09]{index command name}{=\meta{name}}{no default, initially unset}
  Replaces the internally used \cs{index} macro by
  \mbox{\cs{index}\texttt{[\meta{name}]}}, i.\,e.,
  \mbox{\cs{index}\texttt{\textbraceleft\ldots\textbraceright}} is replaced by
  \mbox{\cs{index}\texttt{[\meta{name}]\textbraceleft\ldots\textbraceright}}.
  This option is intended to be used with \refPkg{imakeidx} and is
  mutually exclusive with \refKey{/tcb/index command}.
\begin{dispListing}
\tcbset{index command name=mydoc}
\end{dispListing}
\end{docTcbKey}

\clearpage

\begin{docTcbKey}{index format}{=\meta{format}}{no default, initially |pgf|}
  Determines the basic \meta{format} of the generated index.
  Feasible values are:
  \begin{itemize}
  \item\docValue{pgfsection}: The index is formatted like in the \refPkg{pgf} documentation (as a section).
  \item\docValue{pgfchapter}: The index is formatted like in the \refPkg{pgf} documentation (as a chapter).
  \item\docValue{pgf}: Alias for \docValue{pgfsection}.
  \item\docValue{doc}: The index is assumed to be formatted by \refPkg{doc} or
    \refPkg{ltxdoc}. The usage of \refPkg{makeindex}
    with |-s gind.ist| is assumed. The package \refPkg{hypdoc} has to be loaded
    \emph{before} |tcolorbox|. Only a limited set of customizations will
    work! This option cannot be unset when used!
  \item\docValue{off}: The index is not formatted by |tcolorbox|. Use this, if
    the index is formatted by other package like \refPkg{imakeidx}.
  \end{itemize}
\end{docTcbKey}


\begin{docTcbKey}{index actual}{=\meta{character}}{no default, initially |@|}
  Sets the character for \enquote{actual} in automatic indexing.
\end{docTcbKey}

\begin{docTcbKey}{index quote}{=\meta{character}}{no default, initially |"|}
  Sets the character for \enquote{quote} in automatic indexing.
\end{docTcbKey}

\begin{docTcbKey}{index level}{=\meta{character}}{no default, initially |!|}
  Sets the character for \enquote{level} in automatic indexing.
\end{docTcbKey}

\begin{docTcbKey}{index default settings}{}{style, no value}
  Sets the \refPkg{makeindex} default values for
  \refKey{/tcb/index actual},
  \refKey{/tcb/index quote}, and
  \refKey{/tcb/index level}.
\end{docTcbKey}


\begin{docTcbKey}{index german settings}{}{style, no value}
  Sets the \refPkg{makeindex} values recommended for German language texts.
  This is identical to setting the following:
\begin{dispListing}
\tcbset{index actual={=},index quote={!},index level={>}}
\end{dispListing}
\end{docTcbKey}


\begin{docTcbKey}{index annotate}{\colOpt{=true\textbar false}}{default |true|, initially |true|}
  If set to |true|, the index entries are annotated with short descriptions
  given by \refKey{/tcb/doclang/environment}, \refKey{/tcb/doclang/key},
  and others.
\end{docTcbKey}

\begin{docTcbKey}{index colorize}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
  If set to |true|, the index entries colorized according to the color
  settings given by \refKey{/tcb/color environment}, \refKey{/tcb/color key},
  and others.
\end{docTcbKey}


\begin{docTcbKeys}[
    doc new={2022-06-20},
    doc parameter = {\colOpt{=true\textbar false}},
    doc description = {default |true|, initially |true|}
  ]
  {
    {
      doc name        = index gather colors,
    },
    {
      doc name        = index gather commands,
    },
    {
      doc name        = index gather counters,
    },
    {
      doc name        = index gather environments,
    },
    {
      doc name        = index gather keys,
    },
    {
      doc name        = index gather lengths,
    },
    {
      doc name        = index gather paths,
    },
    {
      doc name        = index gather values,
    }
  }
  If set to |true|, an additional index grouping is created where entries
  are gathered, e.\,g.\ \refKey{/tcb/index gather counters} creates an index
  entry `Colors', see \refKey{/tcb/doclang/colors}, which gets all colors
  as sub entries.
\end{docTcbKeys}


\begin{docTcbKeys}[
    doc new={2022-06-20},
    doc parameter = {},
  ]
  {
    {
      doc name        = index gather all,
      doc description = {style, initially set}
    },
    {
      doc name        = index gather none,
      doc description = {style}
    },
  }
  Switches all index gather options from above to |true| (all) or |false| (none).
\end{docTcbKeys}

\clearpage

\begin{docTcbKey}{color command}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by macro definitions.
\end{docTcbKey}

\begin{docTcbKey}{color environment}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by environment definitions.
\end{docTcbKey}

\begin{docTcbKey}{color key}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by key definitions.
\end{docTcbKey}

\begin{docTcbKey}[][doc new={2019-09-18}]{color path}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by \tikzname\ path operation definitions.
\end{docTcbKey}

\begin{docTcbKey}{color value}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by value definitions.
\end{docTcbKey}

\begin{docTcbKey}[][doc new={2015-01-08}]{color counter}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by counter definitions.
\end{docTcbKey}

\begin{docTcbKey}[][doc new={2015-01-08}]{color length}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by length definitions.
\end{docTcbKey}

\begin{docTcbKey}{color color}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color used by color definitions.
\end{docTcbKey}

\begin{docTcbKey}[][doc updated={2019-09-18}]{color definition}{=\meta{color}}{no default, initially |Definition|}
  Sets the highlight color for \refKey{/tcb/color command}, \refKey{/tcb/color environment},
  \refKey{/tcb/color key}, \refKey{/tcb/color path}, \refKey{/tcb/color value}, \refKey{/tcb/color counter},
  \refKey{/tcb/color length}, and \refKey{/tcb/color color}.
\end{docTcbKey}

\begin{docTcbKey}{color option}{=\meta{color}}{no default, initially |Option|}
  Sets the color used for optional arguments.
\end{docTcbKey}

\begin{docTcbKey}{color fade}{=\meta{color}}{no default, initially |Fade|}
  Sets the color used for faded text like \colFade{\textbackslash path}
  in \refEnv{docPathOperation}.
\end{docTcbKey}


\begin{docTcbKey}{color hyperlink}{=\meta{color}}{no default, initially |Hyperlink|}
  Sets the color for all hyper-links, i.\,e., all internal and external links.
\end{docTcbKey}


\clearpage
%-------------------------------------------------------------------------------
\subsection{Language Option Keys}

The following keys are provided for language specific settings.
The English language is predefined.

\begin{docTcbKey}{english language}{}{style, no value}
  Sets all language specific settings to English.
\end{docTcbKey}

\begin{langTcbKey}{color}{=\meta{text}}{no default, initially |color|}
  Text used in the index for colors.
\end{langTcbKey}

\begin{langTcbKey}{colors}{=\meta{text}}{no default, initially |Colors|}
  Heading text in the index for colors.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2022-06-20}]{commands}{=\meta{text}}{no default, initially |Commands|}
  Heading text in the index for commands.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2015-01-08}]{counter}{=\meta{text}}{no default, initially |counter|}
  Text used in the index for counters.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2015-01-08}]{counters}{=\meta{text}}{no default, initially |Counters|}
  Heading text in the index for counters.
\end{langTcbKey}

\begin{langTcbKey}{environment}{=\meta{text}}{no default, initially |environment|}
  Text used in the index for environments.
\end{langTcbKey}

\begin{langTcbKey}{environments}{=\meta{text}}{no default, initially |Environments|}
  Heading text in the index for environments.
\end{langTcbKey}

\begin{langTcbKey}{environment content}{=\meta{text}}{no default, initially |environment content|}
  Text used in \refEnv{docEnvironment}.
\end{langTcbKey}

\begin{langTcbKey}{index}{=\meta{text}}{no default, initially |Index|}
  Heading text for the index.
\end{langTcbKey}

\begin{langTcbKey}{key}{=\meta{text}}{no default, initially |key|}
  Text used in the index for keys.
\end{langTcbKey}

\begin{langTcbKey}{keys}{=\meta{text}}{no default, initially |Keys|}
  Heading text used in the index for keys.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2015-01-08}]{length}{=\meta{text}}{no default, initially |length|}
  Text used in the index for lengths.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2015-01-08}]{lengths}{=\meta{text}}{no default, initially |Lengths|}
  Heading text in the index for lengths.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2014-09-19}]{new}{=\meta{text}}{no default, initially |New|}
  Announcement text for new content.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2019-09-18}]{path}{=\meta{text}}{no default, initially |path operation|}
  Text used in the index for path operations.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2019-09-18}]{paths}{=\meta{text}}{no default, initially |Path operations|}
  Heading text in the index for path operations.
\end{langTcbKey}

\begin{langTcbKey}{pageshort}{=\meta{text}}{no default, initially |P.|}
  Short text for page references.
\end{langTcbKey}

\begin{langTcbKey}[][doc new={2014-09-19}]{updated}{=\meta{text}}{no default, initially |Updated|}
  Announcement text for updated content.
\end{langTcbKey}

\clearpage

\begin{langTcbKey}{value}{=\meta{text}}{no default, initially |value|}
  Text used in the index for values.
\end{langTcbKey}

\begin{langTcbKey}{values}{=\meta{text}}{no default, initially |Values|}
  Heading text in the index for values.
\end{langTcbKey}



\subsection{Predefined Colors of the Library}\tcbdocmarginnote{\tcbdocupdated{2019-09-18}}
The following colors are predefined. They are used as default colors
in some library commands.

\def\dispColor#1{\docColor{#1}~\tikz[baseline=1mm]\path[fill=#1,draw] (0,0) rectangle (0.4,0.4);~}

\dispColor{Option},
\dispColor{Definition},
\dispColor{ExampleFrame},
\dispColor{ExampleBack},
\dispColor{Hyperlink},
\dispColor{Fade}.