diff options
Diffstat (limited to 'macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex')
-rw-r--r-- | macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex | 1023 |
1 files changed, 1023 insertions, 0 deletions
diff --git a/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex b/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex new file mode 100644 index 0000000000..f8c1c4553c --- /dev/null +++ b/macros/latex/contrib/tcolorbox/tcolorbox.doc.documentation.tex @@ -0,0 +1,1023 @@ +% !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:tikz_and_pgf} 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} +\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 |minted| \cite{poore:minted} 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}} + +\clearpage +\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} + +\clearpage + +\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} + + +\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{hoffmann:2018a}. + 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{hoffmann:2018a}. + 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 options}{=\meta{minted style}}{no default,\\\hspace*{\fill} initially |tabsize=2,fontsize=\textbackslash small|} + Sets the options from the package |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 '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 |minted| \cite{poore:minted}, 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}[][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 |minted| \cite{poore:minted}, if used. + Note that this is not identical to the key + \refKey{/tcb/minted language} 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=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{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{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} + +\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{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 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{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} + +\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{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} 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 +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} + +\begin{docTcbKey}[][doc new=2015-10-09]{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}, + and \refKey{/tcb/before doc body key}. +\end{docTcbKey} + +\begin{docTcbKey}[][doc new=2015-10-09]{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}, + and \refKey{/tcb/after doc body 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{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 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}. + + |