summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-09 16:31:58 +0000
committerKarl Berry <karl@freefriends.org>2013-04-09 16:31:58 +0000
commitd6730e96b1acc94ef3a26f9079e57099be823dff (patch)
tree2bc872d6369d464c590c9a071de5274beca219c7 /Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
parent92897266fb13289d7ef1da636a65bd9c444864f3 (diff)
tcolorbox (9apr13)
git-svn-id: svn://tug.org/texlive/trunk@29788 c570f23f-e606-0410-a88d-b1316a301751
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.tex343
1 files changed, 343 insertions, 0 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
new file mode 100644
index 00000000000..b6a9405acb0
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex
@@ -0,0 +1,343 @@
+% !TeX root = tcolorbox.tex
+% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
+\clearpage
+\section{Library '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.
+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 'listings', see section \ref{sec:listings},
+and a bunch of packages, namely
+|doc|, |pifont|, |marvosym|, |hyperref|, and |makeidx|.
+
+For UTF-8 support, load:
+\begin{dispListing}
+ \tcbuselibrary{listingsutf8,documentation}
+\end{dispListing}
+
+
+\subsection{Macros of the Library}
+
+\begin{docEnvironment}{docCommand}{\marg{name}\marg{parameters}}
+ Documents a \LaTeX\ macro with given \meta{name} where \meta{name} is
+ written without backslash. 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}
+\end{docEnvironment}
+
+
+{\let\xdocEnvironment\docEnvironment
+\let\endxdocEnvironment\enddocEnvironment
+\begin{xdocEnvironment}{docEnvironment}{\marg{name}\marg{parameters}}
+ Documents a \LaTeX\ environment with given \meta{name}.
+ 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}
+\end{xdocEnvironment}}
+
+\clearpage
+\begin{docEnvironment}{docKey}{\oarg{key path}\marg{name}\marg{parameters}\marg{description}}
+ Documents a key with given \meta{name} and an optional \meta{key path}.
+ 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{docCommand}{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}{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}{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}.
+\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}
+
+\clearpage
+\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}
+
+
+
+{\let\xdispExample\dispExample
+ \let\endxdispExample\enddispExample
+\begin{docEnvironment}{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.
+\begin{xdispExample}
+\begin{dispExample}
+This is a \LaTeX\ example.
+\end{dispExample}
+\end{xdispExample}
+\end{docEnvironment}}
+
+
+\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}
+
+\clearpage
+\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}
+
+\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.
+\begin{dispExample}
+\tcbmakedocSubKey{docFooKey}{foo}
+
+\begin{docFooKey}{foodummy}{=\meta{nothing}}{no default, initially empty}
+Some key.
+\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.
+\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}.
+\begin{dispExample}
+We have created \refEnv{foocolorbox} as an example.
+\end{dispExample}
+\end{docCommand}
+
+\begin{docCommand}{refKey}{\marg{name}}
+ References a documented key with given \meta{name} where \meta{name}
+ is the full path name of the key.
+\begin{dispExample}
+We have created \refKey{/foo/footitle} as an example.
+\end{dispExample}
+\end{docCommand}
+
+\clearpage
+\begin{docCommand}{colDef}{\marg{text}}
+Sets \meta{text} with the definition color, see \refKey{/tcb/color definition}.
+\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}
+
+
+\subsection{Option Keys of the Library}
+
+\begin{docTcbKey}{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 could be
+ redefined.
+\end{docTcbKey}
+
+\begin{docTcbKey}{documentation listing style}{=\meta{listing style}}{no default, initially |tcbdocumentation|}
+ Sets a \meta{listing style} for the |listings| package \cite{heinz:2007a}.
+ It is used inside \refEnv{dispExample} and \refEnv{dispListing} to typeset
+ the listings. Note that this is not identical to the key
+ \refKey{/tcb/listing style} which is used for 'normal' listings.
+\end{docTcbKey}
+
+\begin{docTcbKey}{color definition}{=\meta{color}}{no default, initially |Definition|}
+ Sets the highlight color used by macro and key definitions.
+\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}
+
+\begin{docTcbKey}{before example}{=\meta{macros}}{no default, initially \cs{par}\cs{smallskip}}
+ Sets the \meta{macros} which are executed before \refEnv{dispExample} and \refEnv{dispListing}
+ additional to \refKey{/tcb/before}.
+\end{docTcbKey}
+
+\begin{docTcbKey}{after example}{=\meta{macros}}{no default, initially empty}
+ Sets the \meta{macros} which are executed after \refEnv{dispExample} and \refEnv{dispListing}
+ additional to \refKey{/tcb/after}.
+\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}
+
+\clearpage
+\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}
+
+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}{environment content}{=\meta{text}}{no default, initially |environment content|}
+ Text used in \refEnv{docEnvironment}.
+\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}{key}{=\meta{text}}{no default, initially |key|}
+ Text used in the index for keys.
+\end{langTcbKey}
+
+\begin{langTcbKey}{index}{=\meta{text}}{no default, initially |Index|}
+ Heading text for the index.
+\end{langTcbKey}
+
+\begin{langTcbKey}{pageshort}{=\meta{text}}{no default, initially |P.|}
+ Short text for page references.
+\end{langTcbKey}
+
+
+\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}.
+
+