% 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. % -------------------------------------------------------------------------- \documentclass[load-preamble+]{cnltx-doc} \usepackage[more]{tasks} \setcnltx{ package = {tasks} , authors = Clemens Niederberger , email = {contact@mychemistry.eu} , url = {https://bitbucket.org/cgnieder/exsheets/} , info = {% {\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip] create horizontal columned lists% } , add-cmds = { checkedchoicebox , choicebox, NewTasks, settasks, startnewitemline , task } , add-silent-cmds = { choice, correct, DeclareInstance, DeclareTemplateInterface, leftthumbsup, s, sample } } \newpackagename\ExSheets{ExSheets} \newpackagename\ExSheetslistings{ExSheets-listings} \newpackagename\cntformats{cntformats} \newpackagename\Tasks{tasks} % ---------------------------------------------------------------------------- % 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{csquotes} % ---------------------------------------------------------------------------- % example definitions that have to be done in the preamble: \usepackage{exsheets} \usepackage{dingbat} \NewTasks[style=multiplechoice]{multiplechoice}[\choice](3) \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}} \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} Originally \Tasks\ has been an integral part of \ExSheets\changedversion{0.7}. 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 \env{tasks} environment available. Since I agree with this the environment has been extracted into a package if its own, \Tasks. The reason for the \env{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 \pkg{enumitem} package for customization. \section{License and Requirements}\label{sec:license} \license \Tasks\ requires the \bnd{l3kernel}~\cite{bnd:l3kernel} bundle ,\needpackage{xparse}, \pkg{xtemplate} and \needpackage{l3keys2e} which are part of the \bnd{l3packages}~\cite{bnd:l3packages} bundle, \pkg{epic}~\cite{pkg:epic}, \pkg{cntformats}\footnote{Part of the \ExSheets\ bundle}, and \pkg{environ}~\cite{pkg:environ}. \section{How it works} \subsection{The Basics} The \env{tasks} environment is similar to a list like \env{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 \cs*{item} but \cs{task} so it is unique to this environment only. \item A fourth difference: the \env{tasks} environment cannot be nested. You can, however, use an \env*{itemize} environment or something in it. \item A fifth difference: verbatim material cannot be used in it. You'll have to use \cs*{string}, \cs*{texttt} or \cs*{detokenize}. If this won't suffice then don't use \env{tasks}. % \item A sixth difference: %footnotes \end{itemize} \begin{environments} \environment{tasks}[\oarg{options}\darg{num of columns}] List like environment where the single items are iintroduced with \cs{task}. \end{environments} Let's see an example: \begin{example} % \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{example} The environment takes the optional argument \darg{num of columns} with which the number of columns used by the environment is specified. \begin{example} \begin{tasks}(2) \task \sample \task \s\ \s \task \s \task \sample \task \s\par\s \end{tasks} \end{example} \subsection{Introducing a New Row} Sometimes it may come in handy if the current\sinceversion{0.9} row of items could be terminated and a new one is started. This is possible with the following command: \begin{commands} \command{startnewitemline} Introduce a new line in a \env{tasks} environment. \end{commands} \begin{example} \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{example} \section{Available Options}\label{sec:tasks:options} The \Tasks\ package has one package option which also is called when you load \ExSheets\ with the \option{load-tasks} option. \begin{options} \opt{more} Load additional instances for the \env{tasks} object, details are explained later in section~\ref{sec:tasks:instances}. \end{options} The environment itself has some more options, namely the following ones that can be set using a setup command: \begin{commands} \command{settasks}[\marg{options}] Setup command for \Tasks. \end{commands} \begin{options} \keyval{style}{instance}\Default Choose the instance to be used. Read more on this in section~\ref{sec:tasks}. \keyval{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}: \cs*{arabic}, \code{a}: \cs*{alph}, \code{A}: \cs*{Alph}, \code{r}: \cs*{roman} and \code{R}: \cs*{Roman}. \keyval{label-format}{code}\Default \changedversion{0.9}Can be used to apply a formatting like, \eg, \cs*{bfseries} to the labels. \keyval{label}{code}\Default \changedversion{0.9}Overwrite the automatic label to a custom one. \keyval{label-width}{dim}\Default{1em} Sets the width of the item labels. \keyval{label-offset}{dim}\Default{.3333em} \sinceversion{0.7}Sets the offset, \ie, the distance between label and item. \keyval{item-indent}{dim}\Default{2.5em} \sinceversion{0.9a}The indent of an item, \ie, the horizontal space available for both label and label-offset. If \[ \text{\code{indent}} = \text{\code{label-width}} + \text{\code{label=offset}} \] the label will align with the textblock above (if \keyis{label-align}{left} is set). \keychoice{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 \option{label-width}. \keyval{before-skip}{skip}\Default{0pt} Sets the skip before the list. \keyval{after-skip}{skip}\Default{0pt} Sets the skip after the list. \keyval{after-item-skip}{skip}\Default{1ex plus 1ex minus 1ex} \sinceversion{0.9}This vertical skip is inserted between rows of items. \keybool{resume}\Default{false} The enumeration will resume from a previous \env{tasks} environment. In order to use this option properly you shouldn't mix different \env{tasks} environments that both count their items. \end{options} Now the same list as above but with three columns and a different label: \begin{example} \begin{tasks}[counter-format=(tsk[r]),label-width=4ex](2) \task \sample \task \s\ \s \task \s \task \sample \task \s\par\s \end{tasks} \end{example} % \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, \ie, inside \ExSheets' \env{question} environment: \begin{example} % 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{example} \section{Available Instances}\label{sec:tasks:instances} When you use the package option \option{more} of the \Tasks\ package or load \ExSheets\ with the \option{load-tasks} option there are currently three additional instances for the \code{tasks} object available: \begin{description} \item[itemize] uses \cs*{labelitemi} as labels. \item[enumerate] enumerates the items with 1., 2., \ldots \item[multiplechoice] a --~well~-- `multiple choice' list. \end{description} \begin{example} \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{example} \section{Custom Labels} If you want to change a single label inside a list, you can use the optional argument of \cs{task}. This will temporarily overwrite the default label. \begin{example}[side-by-side] \begin{tasks}[style=itemize] \task a standard item \task another one \task[+] a different one \task and another one \end{tasks} \end{example} \section{New Tasks} It is possible to add custom environments that work like the \code{tasks} environment. \begin{commands} \command{NewTasks}[\oarg{options}\marg{name}\oarg{separator}\darg{cols}] Define environment \meta{name} that uses \meta{separator} to introduce a new item. Default for \meta{separator} is \cs{task}, default for \meta{cols} is \code{1}. The \meta{options} are the ones described in section~\ref{sec:tasks:options}. \command{RenewTasks}[\oarg{options}\marg{name}\oarg{separator}\darg{cols}] Renew environment previously defined with \cs{NewTasks}. \end{commands} The \env{tasks} environment is defined as follows: \begin{sourcecode} \NewTasks{tasks} \end{sourcecode} The separator does not have to be a control sequence: \begin{example} % preamble: % \usepackage{dingbat} \NewTasks[label=\footnotesize\leftthumbsup,label-width=1.3em]{done}[*] \begin{done} * First task * Second Task \end{done} \end{example} 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 \env*{multiplechoice} environment that has three columns in its default state. You could do something like this: \begin{example} % preamble: % \NewTasks[style=multiplechoice]{multiplechoice}[\choice](3) % \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}} % % \PrintSolutionsTF and the {question} environment are provided % by the ExSheets package \begin{question} \begin{multiplechoice} \choice First choice \choice Second choice \choice[\correct] Third choice \end{multiplechoice} \end{question} \begin{solution}[print] \begin{multiplechoice} \choice First choice \choice Second choice \choice[\correct] Third choice \end{multiplechoice} \end{solution} \end{example} The last example shows you two additional commands: \begin{commands} \command{choicebox}[\quad\choicebox] Print an empty square. \command{checkedchoicebox}[\quad\checkedchoicebox] Print a crossed-out square. \end{commands} \section{Styling \Tasks} Equivalent to the styling of \ExSheets\ \Tasks\ uses \pkg{xtemplate} to declare additional instances for the lists. \subsection{The \code{tasks} Object}\label{sec:tasks} 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{sourcecode} \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{sourcecode} \subsubsection{Predefined Instances} This is rather brief this time: \begin{sourcecode} % 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{sourcecode} \end{document}