exsheets (29apr13)

git-svn-id: svn://tug.org/texlive/trunk@30166 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 564 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
new file mode 100644
index 00000000000..7bc73eaac63
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/exsheets/tasks_en.tex
@@ -0,0 +1,564 @@
+% arara: pdflatex
+% arara: biber
+% arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the TASKS package
+% 
+%   horizontal columned lists
+% 
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web:    https://bitbucket.org/cgnieder/exsheets/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2011-2013 Clemens Niederberger
+% 
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%   http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+% 
+% This work has the LPPL maintenance status `maintained'.
+% 
+% The Current Maintainer of this work is Clemens Niederberger.
+% --------------------------------------------------------------------------
+% The tasks package is part of the exsheets bundle
+% --------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% --------------------------------------------------------------------------
+%
+% if you want to compile this documentation you'll need the document class
+% `cnpkgdoc' which you can get here:
+%    https://bitbucket.org/cgnieder/cnpkgdoc/
+% the class is licensed LPPL 1.3 or later
+%
+% use `pdflatex' and `biber' for compilation
+%
+\PassOptionsToPackage{supstfm=libertinesups}{superiors}
+\documentclass[DIV9,toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc}
+% ----------------------------------------------------------------------------
+% document layout and typographic features
+\docsetup{
+  pkg      = {[more]tasks} ,
+  url      = {https://bitbucket.org/cgnieder/exsheets/} ,
+  title    = \Tasks ,
+  subtitle = {{\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip]create horizontal columned lists} ,
+  name     = tasks ,
+  language = en ,
+  modules  = true ,
+  code-box = {
+    backgroundcolor  = gray!7!white ,
+    skipbelow        = .6\baselineskip plus .5ex minus .5ex ,
+    skipabove        = .6\baselineskip plus .5ex minus .5ex ,
+    innerleftmargin  = 1.5em ,
+    innerrightmargin = 2.5em
+  } ,
+  gobble   = 1
+}
+\usepackage{libertinehologopatch}
+\cnpkgusecolorscheme{friendly}
+
+\usepackage[biblatex]{embrac}[2012/06/29]
+  \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+  \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+\usepackage{microtype}
+\usepackage[multiple]{fnpct}
+
+\renewcommand*\othersectionlevelsformat[3]{\textcolor{main}{#3\autodot}\enskip}
+\renewcommand*\partformat{\textcolor{main}{\partname~\thepart\autodot}}
+
+\pagestyle{headings}
+
+\setcapindent{1.5em}
+\setkomafont{caption}{\normalfont\footnotesize\sffamily}
+\setkomafont{captionlabel}{\normalfont\footnotesize\sffamily\scshape}
+
+\usepackage{booktabs,array,ragged2e}
+
+% ----------------------------------------------------------------------------
+% code examples
+\newcommand*\Tasks{{\scshape\textcolor{main}{tasks}}\xspace}
+\newcommand*\ExSheets{{\scshape\textcolor{main}{ExSheets}}\xspace}
+
+\addcmds{
+  choice, correct,
+  DeclareInstance, DeclareTemplateInterface,
+  leftthumbsup, NewTasks,
+  s, sample, settasks, task
+}
+
+% ----------------------------------------------------------------------------
+% other packages, bibliography, index
+\usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx}
+\usepackage[accsupp]{acro}
+\DeclareAcronym{id}{
+  short     = id ,
+  long      = Identifier ,
+  format    = \scshape ,
+  pdfstring = ID ,
+  accsupp   = ID
+}
+
+\usepackage{filecontents}
+\usepackage{imakeidx}
+\begin{filecontents*}{\jobname.ist}
+ heading_prefix "{\\bfseries "
+ heading_suffix "\\hfil}\\nopagebreak\n"
+ headings_flag  1
+ delim_0 "\\dotfill\\hyperpage{"
+ delim_1 "\\dotfill\\hyperpage{"
+ delim_2 "\\dotfill\\hyperpage{"
+ delim_r "}\\textendash\\hyperpage{"
+ delim_t "}"
+ suffix_2p "\\nohyperpage{\\,f.}"
+ suffix_3p "\\nohyperpage{\\,ff.}"
+\end{filecontents*}
+\indexsetup{othercode=\footnotesize}
+\makeindex[options={-s \jobname.ist},intoc,columns=3]
+
+\usepackage{csquotes}
+\usepackage[backend=biber,style=alphabetic]{biblatex}
+
+
+% ----------------------------------------------------------------------------
+% example definitions that have to be done in the preamble:
+\usepackage{exsheets}
+\usepackage{dingbat}
+\NewTasks[style=multiplechoice]{choices}[\choice](3)
+\newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
+
+% ----------------------------------------------------------------------------
+% custom commands
+\newcommand*\Default[1]{%
+  \hfill\llap
+    {%
+      \ifblank{#1}%
+        {(initially~empty)}%
+        {Default:~\code{#1}}%
+    }%
+  \newline
+}
+\newcommand*\required{\hfill\llap{required}\newline}
+\newcommand*\optional{\hfill\llap{optional}\newline}
+
+\newcommand*\nooption[2]{\item[\code{\textcolor{key}{#1} = #2}] \cnpkgdocarrow\ }
+
+\newcommand*\unexpsign{$\RHD$}
+\newcommand*\expsign{\textcolor{red}{$\rhd$}}
+\renewcommand*\cnpkgdoctriangle{\unexpsign}
+\newcommand*\expandable{%
+  \def\cnpkgdoctriangle{%
+    \expsign
+    \gdef\cnpkgdoctriangle{\unexpsign}}}
+
+\usepackage{marginnote}
+\makeatletter
+\newcommand*\sinceversion[1]{%
+  \@bsphack
+  \marginnote{%
+    \footnotesize\sffamily\RaggedRight
+    \textcolor{black!75}{Introduced in version~#1}}%
+  \@esphack}
+\newcommand*\changedversion[1]{%
+  \@bsphack
+  \marginnote{%
+    \footnotesize\sffamily\RaggedRight
+    \textcolor{black!75}{Changed in version~#1}}%
+  \@esphack}
+\makeatother
+
+\pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}}
+
+% ----------------------------------------------------------------------------
+% title page
+% \TitlePicture{%
+%   \parbox{.8\linewidth}{%
+%   }%
+% }
+
+\def\s{This is some sample text we will use to create a somewhat
+  longer text spanning a few lines.}
+\def\sample{\s\ \s\par\s}
+
+\begin{document}
+
+\section{Motivation}\secidx{Motivation}
+\noindent\changedversion{0.7}Originally \Tasks has been an integral part of
+\ExSheets. However, users told me that it indeed could be useful to have it as a
+stand-alone package not having to load the whole \ExSheets beast just for having
+the \code{tasks} environment available. Since I agree with this the environment
+has been extracted into a package if its own, \Tasks.
+
+The reason for the \code{tasks} environment is an unwritten agreement in German
+maths textbooks (in (junior) high school, especially) to organize exercises in
+columns counting horizontally rather than vertically. That is what \code{tasks}
+primarily is for. If you don't need this feature you're better off using traditional
+\LaTeX{} lists and the \paket{enumitem} package for customization.
+\secidx*{Motivation}
+
+\section{License and Requirements}\label{sec:license}\secidx{Requirements}
+\Tasks is placed under the terms of the \LaTeX{} Project Public License,
+version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}). It has the
+status ``maintained.''
+
+\Tasks requires packages \paket{l3kernel} ,\paket{xparse}, \paket{l3keys2e},
+\paket{epic}, \paket*{cntformats}\footnote{Part of the \ExSheets bundle},
+\paket{xtemplate} and \paket{environ}.
+\secidx*{Requirements}
+
+\section{How it works}
+\subsection{The Basics}
+The \code{tasks} environment is similar to a list like \code{enumerate} but not
+the same:
+\begin{itemize}
+ \item The first difference: there is no pagebreak possible inside an item but
+   only between items.
+ \item The second difference: the enumeration default is a), b), c) \ldots
+ \item The third difference: there is a split at \emph{every} occurrence of the
+   item separator. For this reason the default separator is not \cmd*{item} but
+   \cmd{task} so it is unique to this environment only.
+ \item The fourth difference: the \code{tasks} environment cannot be nested. You
+   can, however, use an \code{itemize} environment or something in it.
+ \item The fifth difference: verbatim material cannot be used in it. You'll
+   have to use \cmd*{string}, \cmd*{texttt} or \cmd*{detokenize}. If this won't
+   suffice then don't use \code{tasks}.
+\end{itemize}
+
+\begin{beschreibung}
+ \Umg{tasks}[<options>]{\unskip\da{<num of columns>} \cmd{task}\ldots}
+\end{beschreibung}
+Let's see an example:
+\begin{beispiel}[code only]
+ % \sample is defined to contain some sample text:
+ % \def\s{This is some sample text we will use to create a somewhat
+ %   longer text spanning a few lines.}
+ % \def\sample{\s\ \s\par\s}
+ Some text before the list.
+ \begin{tasks}
+  \task \sample
+  \task \sample
+  \task \sample
+ \end{tasks}
+ And also some text after it.
+\end{beispiel}
+Some text before the list.
+\begin{tasks}
+ \task \sample
+ \task \sample
+ \task \sample
+\end{tasks}
+And also some text after it.
+ 
+The environment takes the optional argument \da{<num of columns>} with which the
+number of columns used by the environment is specified.
+\begin{beispiel}[code only]
+ \begin{tasks}(2)
+  \task \sample
+  \task \s\ \s
+  \task \s
+  \task \sample
+  \task \s\par\s
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}(2)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+\end{tasks}
+
+\subsection{Introducing a New Row}
+\noindent\sinceversion{0.9}Sometimes it may come in handy if the current
+row of items could be terminated and a new one is started. This is possible
+with the following command:
+\begin{beschreibung}
+ \Befehl{startnewitemline}
+\end{beschreibung}
+\begin{beispiel}[code only]
+ \begin{tasks}(4)
+  \task the first
+  \task the second
+  \task the third
+  \task the fourth
+  \task \rlap{the fifth item is way too long for this so we start a new row} \startnewitemline
+  \task the sixth
+  \task the seventh
+  \task \rlap{the eighth item also is too long} \startnewitemline
+  \task the nineth
+  \task the tenth
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}(4)
+ \task the first
+ \task the second
+ \task the third
+ \task the fourth
+ \task \rlap{the fifth item is way too long for this so we start a new row} \startnewitemline
+ \task the sixth
+ \task the seventh
+ \task \rlap{the eighth item also is too long} \startnewitemline
+ \task the nineth
+ \task the tenth
+\end{tasks}
+
+\section{Available Options}\secidx{Options}\label{sec:tasks:options}
+The \Tasks package has one package option which also is called when you load
+\ExSheets with the \key{load-tasks} option.
+\begin{beschreibung}
+ \Option{more}\newline
+   load additional instances for the \code{tasks} object, details are explained
+   later in section~\ref{sec:tasks:instances}.
+\end{beschreibung}
+
+The environment itself has some more options, namely these:
+\begin{beschreibung}
+ \Option{style}{<instance>}\Default{}
+   Choose the instance to be used. Read more on this in section~\ref{sec:tasks}.
+ \Option{counter-format}{<counter specs>}\Default{}
+   \sinceversion{0.9}Sets a custom label. The letters \code{tsk} are replaced
+   with the task-counter. An optional argument directly following these letters
+   specifies the counter format: \code{1}: \cmd{arabic}, \code{a}: \cmd{alph},
+   \code{A}: \cmd{Alph}, \code{r}: \cmd{roman} and \code{R}: \cmd{Roman}.
+ \Option{label-format}{<code>}\Default{}
+   \changedversion{0.9}Can be used to apply a formatting like, \emph{e.g.},
+   \cmd*{bfseries} to the labels.
+ \Option{label}{<code>}\Default{}
+   \changedversion{0.9}Overwrite the automatic label to a custom one.
+ \Option{label-width}{<dim>}\Default{1em}
+   Sets the width of the item labels.
+ \Option{label-offset}{<dim>}\Default{.3333em}
+   \sinceversion{0.7}Sets the offset, \emph{i.e.}, the distance between label and item.
+ \Option{item-indent}\Default{2.5em}
+   \sinceversion{0.9a}The indent of an item, \textit{i.e.}, the horizontal space
+   available for both label and label-offset. If \code{indent = label-width + label=offset}
+   the label will align with the textblock above (if \key{label-align}{left} is
+   set).
+ \Option{label-align}{left|right|center}\Default{left}
+   \sinceversion{0.7}Determines how the labels are aligned within the label-box
+   whose width is set with \key{label-width}
+ \Option{before-skip}{<skip>}\Default{0pt}
+   Sets the skip before the list.
+ \Option{after-skip}{<skip>}\Default{0pt}
+   Sets the skip after the list.
+ \Option{after-item-skip}{<skip>}\Default{1ex plus 1ex minus 1ex}
+   \sinceversion{0.9}This vertical skip is inserted between rows of items.
+ \Option{resume}{\default{true}|false}\Default{false}
+   The enumeration will resume from a previous \code{tasks} environment. In order
+   to use this option properly you shouldn't mix different \code{tasks} environments
+   that both count their items.
+\end{beschreibung}
+These options can also be set using a setup command:
+\begin{beschreibung}
+ \Befehl{settasks}{<options>}
+\end{beschreibung}
+
+Now the same list as above but with three columns and a different label:
+\begin{beispiel}[code only]
+ \begin{tasks}[counter-format=(tsk[r]),label-width=4ex](3)
+  \task \sample
+  \task \s\ \s
+  \task \s
+  \task \sample
+  \task \s\par\s
+ \end{tasks}
+\end{beispiel}
+\begin{tasks}[counter-format=(tsk[r]),label-width=4ex](3)
+ \task \sample
+ \task \s\ \s
+ \task \s
+ \task \sample
+ \task \s\par\s
+\end{tasks}
+
+Let's use it inside a question, \textit{i.e.}, inside \ExSheets' \code{question}
+environment:
+\begin{beispiel}
+ % since settings are local the following ones will be lost
+ % outside this example;
+ \settasks{
+   counter-format = qu.tsk ,
+   item-indent    = 2em ,
+   label-width    = 2em ,
+   label-offset   = 0pt
+ }
+ \begin{question}[type=exam]{4}
+  I have these two tasks for you. Shall we begin?
+  \begin{tasks}(2)
+   \task The first task: easy!
+   \task The second task: even more so!
+  \end{tasks}
+ \end{question}
+ \begin{solution}[print]
+  Now, let's see\ldots\ ah, yes:
+  \begin{tasks}
+   \task This is the first solution. Told you it was easy.
+   \task This is the second solution. And of course you knew that!
+  \end{tasks}
+ \end{solution}
+\end{beispiel}
+\secidx*{Options}
+
+\section{Available Instances}\label{sec:tasks:instances}
+When you use the package option \key{more} of the \Tasks package or load \ExSheets
+with the \key{load-tasks} option there are currently three additional instances
+for the \code{tasks} object available:
+\begin{description}
+ \item[itemize] uses \cmd{labelitemi} as labels.
+ \item[enumerate] enumerates the items with 1., 2., \ldots
+ \item[multiplechoice] a --~well~-- `multiple choice' list.
+\end{description}
+\begin{beispiel}
+ \begin{tasks}[style=itemize](2)
+  \task that's just how\ldots
+  \task \ldots we expected
+ \end{tasks}
+ \begin{tasks}[style=enumerate](2)
+  \task that's just how\ldots
+  \task \ldots we expected
+ \end{tasks}
+ \begin{tasks}[style=multiplechoice](2)
+  \task that's just how\ldots
+  \task \ldots we expected
+ \end{tasks}
+\end{beispiel}
+
+\section{Custom Labels}\secidx{Custom Labels}
+If you want to change a single label inside a list, you can use the optional
+argument of \cmd{task}. This will temporarily overwrite the default label.
+\begin{beispiel}
+ \begin{tasks}[style=itemize]
+  \task a standard item
+  \task another one
+  \task[+] a different one
+  \task and another one
+ \end{tasks}
+\end{beispiel}
+\secidx*{Custom Labels}
+
+\section{New Tasks}\secidx{Own Environments}
+It is possible to add custom environments that work like the \code{tasks} environment.
+\begin{beschreibung}
+ \Befehl{NewTasks}[<options>]{<name>}\oa{<separator}\da{<cols>}\newline
+   Define environment \ma{<name>} that uses \code{<separator>} to introduce a
+   new item. Default for \code{<separator>} is \cmd{task}, default for
+   \code{<cols>} is \code{1}. The \code{<options>} are the ones described in
+   section~\ref{sec:tasks:options}.
+ \Befehl{RenewTasks}[<options>]{<name>}\oa{<separator}\da{<cols>}\newline
+   Renew environment previously defined with \cmd{NewTasks}.
+\end{beschreibung}
+The \code{tasks} environment is defined as follows:
+\begin{beispiel}[code only]
+ \NewTasks{tasks}
+\end{beispiel}
+
+The separator does not have to be a control sequence:
+\begin{beispiel}
+ % preamble:
+ % \usepackage{dingbat}
+ \NewTasks[label=\footnotesize\leftthumbsup,label-width=1.3em]{done}[*]
+ \begin{done}
+  * First task
+  * Second Task
+ \end{done}
+\end{beispiel}
+Although this might seem handy or even nice I strongly advice against using
+something different than a command sequence. Remember that the items will be
+split at \emph{every} occurrence of the separator. So in order to use the
+separator (here for example for a starred variant of a command) within an item
+it has to be hidden in braces. This is avoided of you use a command sequence
+which even doesn't have to be defined.
+
+Let's say you want a \code{choices} environment that has three columns in its
+default state. You could do something like this:
+\begin{beispiel}
+ % preamble:
+ % \NewTasks[style=multiplechoice]{choices}[\choice](3)
+ % \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
+ %
+ % \PrintSolutionsTF and the {question} environment are provided
+ % by the ExSheets package
+ \begin{question}
+ \begin{choices}
+  \choice First choice
+  \choice Second choice
+  \choice[\correct] Third choice
+ \end{choices}
+ \end{question}
+ \begin{solution}[print]
+ \begin{choices}
+  \choice First choice
+  \choice Second choice
+  \choice[\correct] Third choice
+ \end{choices}
+ \end{solution}
+\end{beispiel}
+
+The last example shows you two additional commands:
+\begin{beschreibung}
+ \Befehl{choicebox} \choicebox
+ \Befehl{checkedchoicebox} \checkedchoicebox
+\end{beschreibung}
+\secidx*{Own Environments}
+
+\section{Styling \Tasks}
+Equivalent to the styling of \ExSheets{} \Tasks uses \paket{xtemplate} to
+declare additional instances for the lists.
+
+\subsection{The \code{tasks} Object}\label{sec:tasks}\secidx{The `tasks' Object}
+The object that's defined by \Tasks is the `tasks' object.
+This time there are four instances available for the one template (again
+`default') that was defined.
+
+\subsubsection{Available Options}
+This section only lists the options that can be used when defining an instance
+of the `default' template. The following subsections will give some examples
+of their usage.
+
+\begin{beispiel}[code only]
+ \DeclareTemplateInterface{tasks}{default}{3}
+  {
+    % option        : type      = default
+    enumerate       : boolean   = true    ,
+    label           : tokenlist           ,
+    indent          : length    = 2.5em   ,
+    counter-format  : tokenlist = tsk[a]) ,
+    label-format    : tokenlist           ,
+    label-width     : length    = 1em     ,
+    label-offset    : length    = .3333em ,
+    after-item-skip : skip      = 1ex plus 1ex minus 1ex
+  }
+\end{beispiel}
+
+\subsubsection{Predefined Instances}
+This is rather brief this time:
+\begin{beispiel}[code only]
+ % ALPHABETIZE: a) b) c)
+ \DeclareInstance{tasks}{alphabetize}{default}{}
+ % available when `load-tasks=true':
+ % ITEMIZE:
+ \DeclareInstance{tasks}{itemize}{default}
+   {
+     enumerate   = false ,
+     label-width = 1.125em
+   }
+ % ENUMERATE:
+ \DeclareInstance{tasks}{enumerate}{default}
+   { counter-format = tsk. }
+ % MULTIPLECHOICE:
+ \DeclareInstance{tasks}{multiplechoice}{default}
+   {
+     enumerate = false       ,
+     label     = \choicebox  ,
+   }
+\end{beispiel}
+\secidx*{The `tasks' Object}
+
+\printindex
+
+\end{document}