diff options
author | Karl Berry <karl@freefriends.org> | 2013-04-09 16:31:58 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-04-09 16:31:58 +0000 |
commit | d6730e96b1acc94ef3a26f9079e57099be823dff (patch) | |
tree | 2bc872d6369d464c590c9a071de5274beca219c7 /Master/texmf-dist/doc/latex/tcolorbox/tcolorbox.doc.documentation.tex | |
parent | 92897266fb13289d7ef1da636a65bd9c444864f3 (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.tex | 343 |
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}. + + |