summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex')
-rw-r--r--Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex242
1 files changed, 231 insertions, 11 deletions
diff --git a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
index 0242d15119e..2b6e64f95c3 100644
--- a/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
+++ b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
@@ -4,7 +4,7 @@
\section{Library \mylib{documentation}}\label{sec: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:2010c} documentation.
+Till Tantau's |pgf| \cite{tantau:2013a} documentation.
Typically, this library is assumed to be used in conjunction with the
class |ltxdoc| or alike.
@@ -29,7 +29,6 @@ For |minted| \cite{rudolph:2011a} support, load:
\subsection{Macros of the Library}
-
\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}.
@@ -51,7 +50,13 @@ For |minted| \cite{rudolph:2011a} support, load:
\end{dispExample}
\end{docEnvironment}
-\clearpage
+
+\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}}
@@ -76,6 +81,12 @@ For |minted| \cite{rudolph:2011a} support, load:
\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]{docKey}{\oarg{key path}\marg{name}\marg{parameters}\marg{description}}
Documents a key with given \meta{name} and an optional \meta{key path}.
@@ -91,6 +102,25 @@ For |minted| \cite{rudolph:2011a} support, load:
\end{docEnvironment}
+\begin{docEnvironment}[doclang/environment content=key description]{docKey*}{\oarg{key path}\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}{docAuxCommand}{\marg{name}}
Documents an auxiliary or minor \LaTeX\ macro with given \meta{name}
where \meta{name} is written without backslash.
@@ -100,6 +130,37 @@ The macro \docAuxCommand{fooaux} holds some interesting data.
\end{dispExample}
\end{docCommand}
+\begin{docCommand}{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*}{\marg{name}}
+ Identical to \refCom{docAuxEnvironment}, but without index entry.
+\end{docCommand}
+
+
+\begin{docCommand}{docAuxKey}{\marg{name}}
+ Documents an auxiliary key with given \meta{name} including path.
+ It is automatically indexed.
+\begin{dispExample}
+The key \docAuxEnvironment{/foo/fooaux} holds some interesting data.
+\end{dispExample}
+\end{docCommand}
+
+
+\begin{docCommand}{docAuxKey*}{\marg{name}}
+ Identical to \refCom{docAuxKey}, but without index entry.
+\end{docCommand}
+
+
\clearpage
\begin{docCommand}{docColor}{\marg{name}}
Documents a color with given \meta{name}. The color is automatically indexed.
@@ -108,6 +169,10 @@ The color \docColor{foocolor} is available.
\end{dispExample}
\end{docCommand}
+\begin{docCommand}{docAuxColor*}{\marg{name}}
+ Identical to \refCom{docColor}, but without index entry.
+\end{docCommand}
+
\begin{docCommand}{cs}{\marg{name}}
Macro from |ltxdoc| \cite{carlisle:2007a} to typeset a command word \meta{name}
@@ -119,6 +184,7 @@ This is a \cs{foocommand}.
\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}
@@ -225,12 +291,18 @@ heading line. Optionally, such a box can be split in an upper and a lower part.
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}
@@ -288,6 +360,25 @@ 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 definition color, see \refKey{/tcb/color definition}.
@@ -315,7 +406,7 @@ This is my \colOpt{text}.
\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:2007a}.
+ 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.\\
@@ -325,7 +416,7 @@ This is my \colOpt{text}.
\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:2007a}.
+ 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.
@@ -373,13 +464,13 @@ This is my \colOpt{text}.
Determines the basic \meta{format} of the generated index.
Feasible values are:
\begin{itemize}
- \item |pgfsection|: The index is formatted like in the |pgf| documentation (as a section).
- \item |pgfchapter|: The index is formatted like in the |pgf| documentation (as a chapter).
- \item |pgf|: Alias for |pgfsection|.
- \item |doc|: The index is assumed to be formatted by |doc|/|ltxdoc|. A usage of |makeindex|
+ \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 |off|: The index is not formatted by |tcolorbox|.
+ \item\docValue{off}: The index is not formatted by |tcolorbox|.
\end{itemize}
\end{docTcbKey}
@@ -412,7 +503,7 @@ This is my \colOpt{text}.
\end{dispListing}
\end{docTcbKey}
-%\clearpage
+
The following keys are provided for language specific settings.
The English language is predefined.
@@ -444,6 +535,14 @@ The English language is predefined.
Text used in the index for keys.
\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}
+
\begin{langTcbKey}{index}{=\meta{text}}{no default, initially |Index|}
Heading text for the index.
\end{langTcbKey}
@@ -453,6 +552,127 @@ The English language is predefined.
\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}
+
+\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}
+
+%\clearpage
+
+
\subsection{Predefined Colors of the Library}
The following colors are predefined. They are used as default colors
in some library commands.