% !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 |pgf| \cite{tantau:2013a} documentation.
Typically, this library is assumed to be used in conjunction with the
class |ltxdoc| or alike.

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{listings}, see \Vref{sec:listings},
the library \mylib{skins}, see \Vref{sec:skins},
the library \mylib{xparse}\tcbdocmarginnote{\tcbdocnew{2014-09-19}}, see \Vref{sec:xparse},
and a bunch of packages, namely
|pifont|, |marvosym|, |makeidx|, |marginnote|, |refcount|, and |hyperref|.

\begin{marker}
The package |makeidx| is loaded only, if \docAuxCommand*{printindex} is
\emph{not} already defined. Therefore, one can include an alternative to |makeidx| like
|imakeidx| \emph{before} the library |documentation| is used.
\end{marker}
\begin{marker}
The package |marginnote| is loaded only, if \docAuxCommand*{marginnote} is
\emph{not} already defined.
\end{marker}

For UTF-8 support, load:
\begin{dispListing}
  \tcbuselibrary{listingsutf8,documentation}
\end{dispListing}

For |minted| \cite{rudolph:2011a} support, load:
\begin{dispListing}
  \tcbuselibrary{documentation,minted}
  \tcbset{listing engine=minted}
\end{dispListing}


\subsection{Macros of the Library}
\enlargethispage*{15mm}
\begin{docEnvironment}[doclang/environment content=command description]{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}[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}.
\end{docCommand}
\end{dispExample}
\end{docEnvironment}


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


%\clearpage
{\let\xdocEnvironment\docEnvironment
\let\endxdocEnvironment\enddocEnvironment
\begin{xdocEnvironment}[doclang/environment content=environment description]{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]{docEnvironment*}{\oarg{options}\marg{name}\marg{parameters}}
  Identical to \refEnv{docEnvironment}, but without index entry.
\end{xdocEnvironment}}


\begin{docEnvironment}[doclang/environment content=key description,doc updated=2014-09-29]{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=2014-09-29]{docKey*}{\oarg{key path}\oarg{options}\marg{name}\marg{parameters}\marg{description}}
  Identical to \refEnv{docKey}, but without index entry.
\end{docEnvironment}


\begin{docCommand}{docValue}{\marg{name}}
  Documents a value with given \meta{name}. Typically, this is a value for a key.
  This value is automatically indexed.
\begin{dispExample}
A feasible value for \refKey{/foo/footitle} is \docValue{foovalue}.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{docValue*}{\marg{name}}
  Identical to \refCom{docValue}, but without index entry.
\end{docCommand}


\begin{docCommand}[doc updated=2014-10-09]{docAuxCommand}{\marg{name}}
  Documents an auxiliary or minor \LaTeX\ macro with given \meta{name}
  where \meta{name} is written without backslash.
  This macro is automatically indexed.
\begin{dispExample}
The macro \docAuxCommand{fooaux} holds some interesting data.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc updated=2014-10-09]{docAuxCommand*}{\marg{name}}
  Identical to \refCom{docAuxCommand}, but without index entry.
\end{docCommand}

\begin{docCommand}{docAuxEnvironment}{\marg{name}}
  Documents an auxiliary or minor \LaTeX\ environment with given \meta{name}.
  This macro is automatically indexed.
\begin{dispExample}
The environment \docAuxEnvironment{fooauxenv} holds some interesting data.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{docAuxEnvironment*}{\oarg{key path}\marg{name}}
  Identical to \refCom{docAuxEnvironment}, but without index entry.
\end{docCommand}


\begin{docCommand}{docAuxKey}{\oarg{key path}\marg{name}}
  Documents an auxiliary key with given \meta{name} and an optional \meta{key path}.
  It is automatically indexed.
\begin{dispExample}
The key \docAuxKey[foo]{fooaux} holds some interesting data.
\end{dispExample}
\end{docCommand}


\begin{docCommand}{docAuxKey*}{\oarg{key path}\marg{name}}
  Identical to \refCom{docAuxKey}, but without index entry.
\end{docCommand}


\clearpage
\begin{docCommand}[doc new=2015-01-08]{docCounter}{\marg{name}}
  Documents a counter with given \meta{name}. The counter is automatically indexed.
\begin{dispExample}
The counter \docCounter{foocounter} can be used for computation.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc new=2015-01-08]{docCounter*}{\marg{name}}
  Identical to \refCom{docCounter}, but without index entry.
\end{docCommand}

\begin{docCommand}[doc new=2015-01-08]{docLength}{\marg{name}}
  Documents a counter with given \meta{name}. The counter is automatically indexed.
\begin{dispExample}
The length \docLength{foolength} can be used for computation.
\end{dispExample}
\end{docCommand}

\begin{docCommand}[doc new=2015-01-08]{docLength*}{\marg{name}}
  Identical to \refCom{docLength}, but without index entry.
\end{docCommand}


\begin{docCommand}{docColor}{\marg{name}}
  Documents a color with given \meta{name}. The color is automatically indexed.
\begin{dispExample}
The color \docColor{foocolor} is available.
\end{dispExample}
\end{docCommand}

\begin{docCommand}{docColor*}{\marg{name}}
  Identical to \refCom{docColor}, but without index entry.
\end{docCommand}


\clearpage
\begin{docCommand}{cs}{\marg{name}}
  Macro from |ltxdoc| \cite{carlisle:2007a} 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 |doc| \cite{mittelbach:2011a} 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 |ltxdoc| \cite{carlisle:2007a} 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 |ltxdoc| \cite{carlisle:2007a} 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}


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

\clearpage

{\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}{tcbmakedocSubKey}{\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 default.
  The new environment \meta{name} takes the same para\-meters as \refEnv{docKey} itself.
  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}{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}

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


\begin{docCommand}{refAux}{\marg{name}}
  References some auxiliary environment, key, value, or color. The hyperlink color is
  used, 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}{refAuxcs}{\marg{name}}
  References some auxiliary macro \meta{name} where \meta{name} is
  written without backslash. The hyperlink color is
  used, 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}{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}

\clearpage

\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 |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{Option Keys of the Library}

\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 |listings| \cite{heinz:2013a}.
  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 '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 |listings| package, see \cite{heinz:2013a}.
  Note that this is not identical to the key
  \refKey{/tcb/listing style} which is used for 'normal' listings.\\
  Used for \refKey{/tcb/listing engine}|=listings| only.
\end{docTcbKey}

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

\begin{docTcbKey}{documentation minted options}{=\meta{minted style}}{no default,\\\hspace*{\fill} initially |tabsize=2,fontsize=\textbackslash small|}
  Sets the options from the package |minted| \cite{rudolph:2011a}
  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 'normal' listings.\\
  Used for \refKey{/tcb/listing engine}|=minted| only.
\end{docTcbKey}

\begin{marker}
The following two keys are deprecated and without function (v3.50 and above).
Use \refKey{/tcb/before} and \refKey{/tcb/after} with appropriate values
instead. Also see \refKey{/tcb/docexample}.
\end{marker}

\begin{docTcbKey}[][doc updated=2015-03-16]{before example}{=\meta{macros}}{no default, initially empty}
\smallskip\begin{deprecated}
  Sets the \meta{macros} which are executed before \refEnv{dispExample} and \refEnv{dispListing}
  additional to \refKey{/tcb/before}.
\end{deprecated}
\end{docTcbKey}

\begin{docTcbKey}{after example}{=\meta{macros}}{no default, initially empty}
\smallskip\begin{deprecated}
  Sets the \meta{macros} which are executed after \refEnv{dispExample} and \refEnv{dispListing}
  additional to \refKey{/tcb/after}.
\end{deprecated}
\end{docTcbKey}

\clearpage
\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 |imakeidx| and is
  mutually exclusive with \refKey{/tcb/index command}.
\begin{dispListing}
\tcbset{index command name=mydoc}
\end{dispListing}
\end{docTcbKey}



\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 |pgf| documentation (as a section).
  \item\docValue{pgfchapter}: The index is formatted like in the |pgf| documentation (as a chapter).
  \item\docValue{pgf}: Alias for |pgfsection|.
  \item\docValue{doc}: The index is assumed to be formatted by |doc| or |ltxdoc|. The usage of |makeindex|
    with |-s gind.ist| is assumed. The package |hypdoc| has to be loaded
    \emph{before} |tcolorbox|.
  \item\docValue{off}: The index is not formatted by |tcolorbox|. Use this, if
    the index is formatted by other package like |imakeidx|.
  \end{itemize}
\end{docTcbKey}


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

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

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

\begin{docTcbKey}{index default settings}{}{style, no value}
  Sets the |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 |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}

\clearpage

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


\clearpage
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={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}{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}

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



\clearpage
\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{argment}}
  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{argment}}
  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{argment}}
  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}

\enlargethispage*{10mm}
\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{argment}}
  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 set inside |tcolorbox|es.
Options to these |tcolorbox|es can be given using the following keys.

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

\begin{docCommand*}{myCommandE}{\marg{argment}}
  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}

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

\begin{docEnvironment*}{myEnvironment}{\marg{argment}}
  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} and \refEnv{docKey*}.
\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 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},
  and \refKey{/tcb/doc head key}.
\end{docTcbKey}

\clearpage
\begin{docTcbKey}{doc description}{=\meta{text}}{no default, initially empty}
  Sets a (short!) additional description \meta{text} for
  \refEnv{docCommand} or \refEnv{docEnvironment}. Such a description is
  mandatory for \refEnv{docKey}.
\begin{dispExample}
\begin{docCommand*}[doc description=my description]{myCommandF}{\marg{argment}}
  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 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=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 a marginnote with a 'New: \meta{data}' 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 'Updated: \meta{data}' 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 'New: \meta{new date}' and 'Updated: \meta{update data}' messages at the beginning of
  the upper box part. See \refKey{/tcb/doc new}.
\end{docTcbKey}


\subsection{Predefined Colors of the Library}
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}.


