% 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}[]{\unskip\da{} \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{} 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}{}\Default{} Choose the instance to be used. Read more on this in section~\ref{sec:tasks}. \Option{counter-format}{}\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}{}\Default{} \changedversion{0.9}Can be used to apply a formatting like, \emph{e.g.}, \cmd*{bfseries} to the labels. \Option{label}{}\Default{} \changedversion{0.9}Overwrite the automatic label to a custom one. \Option{label-width}{}\Default{1em} Sets the width of the item labels. \Option{label-offset}{}\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}{}\Default{0pt} Sets the skip before the list. \Option{after-skip}{}\Default{0pt} Sets the skip after the list. \Option{after-item-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}{} \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}[]{}\oa{}\newline Define environment \ma{} that uses \code{} to introduce a new item. Default for \code{} is \cmd{task}, default for \code{} is \code{1}. The \code{} are the ones described in section~\ref{sec:tasks:options}. \Befehl{RenewTasks}[]{}\oa{}\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}