diff options
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.tex | 242 |
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. |