% 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{*}}

% ----------------------------------------------------------------------------
\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.  Here are some of the differences:
\begin{itemize}
\item A first difference: there is no pagebreak possible inside an item but
  only between items.
\item A second difference: the enumeration default is a), b), c) \ldots
\item A 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 A fourth difference: the \code{tasks} environment cannot be nested.
  You can, however, use an \code{itemize} environment or something in it.
\item A 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}.
\item A sixth difference: %footnotes
\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}
