From da88d6a955687f433382b1d3072ef1ac42fc5fc1 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 21 Mar 2020 21:17:24 +0000 Subject: tasks (21mar20) git-svn-id: svn://tug.org/texlive/trunk@54449 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/tasks/README | 4 +- Master/texmf-dist/doc/latex/tasks/tasks-manual.pdf | Bin 0 -> 465232 bytes Master/texmf-dist/doc/latex/tasks/tasks-manual.tex | 498 +++++++++++++++++++ Master/texmf-dist/doc/latex/tasks/tasks_en.pdf | Bin 448228 -> 0 bytes Master/texmf-dist/doc/latex/tasks/tasks_en.tex | 527 --------------------- 5 files changed, 500 insertions(+), 529 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/tasks/tasks-manual.pdf create mode 100644 Master/texmf-dist/doc/latex/tasks/tasks-manual.tex delete mode 100644 Master/texmf-dist/doc/latex/tasks/tasks_en.pdf delete mode 100644 Master/texmf-dist/doc/latex/tasks/tasks_en.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/tasks/README b/Master/texmf-dist/doc/latex/tasks/README index aa177739fa0..76abb73d319 100644 --- a/Master/texmf-dist/doc/latex/tasks/README +++ b/Master/texmf-dist/doc/latex/tasks/README @@ -1,7 +1,7 @@ -------------------------------------------------------------------------- -the TASKS package v1.1a 2020/01/11 +the TASKS package v1.2 2020/03/21 - horizontally columned lists + lists with columns filled horizontally -------------------------------------------------------------------------- Clemens Niederberger diff --git a/Master/texmf-dist/doc/latex/tasks/tasks-manual.pdf b/Master/texmf-dist/doc/latex/tasks/tasks-manual.pdf new file mode 100644 index 00000000000..e16f2d755b0 Binary files /dev/null and b/Master/texmf-dist/doc/latex/tasks/tasks-manual.pdf differ diff --git a/Master/texmf-dist/doc/latex/tasks/tasks-manual.tex b/Master/texmf-dist/doc/latex/tasks/tasks-manual.tex new file mode 100644 index 00000000000..2bcfb18d3ef --- /dev/null +++ b/Master/texmf-dist/doc/latex/tasks/tasks-manual.tex @@ -0,0 +1,498 @@ +% -------------------------------------------------------------------------- +% the TASKS package +% +% lists with columns filled horizontally +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://github.com/cgnieder/tasks/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2013--2020 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. +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\documentclass{tasks-manual} + +\begin{document} + +\section{Preface} +\subsection{Motivation \& History} +Originally \Tasks\ has been an integral part of the +\ExSheets\changedversion{0.7} package~\cite{pkg: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 \env{tasks} +environment available. Since I agree with this the environment has been +extracted into a package if its own, \Tasks. Since then \Tasks\ has been +distributed as a package of its own but as part of the \ExSheets\ +bundle\changedversion{0.10}. With v0.10 I decided to make it a completely +independent package. So the relation to \ExSheets\ only is a historical one. + +The reason for the \env{tasks} environment is an unwritten agreement in German +maths textbooks (exspecially in (junior) high school textbooks) 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. + +\subsection{Changes} +The \sinceversion{1.0} step to version~1.0 brought some significant changes: +\begin{itemize} + \item the option \option{counter-format} is deprecated. Labels can now be + set quite similar to the way they are set in \pkg{enumitem}. This also + made the \code{enumerate} option of the list template superfluous which has + been removed accordingly. + \item The commands \cs{NewTasks} and \cs{RenewTasks} have been renamed. + \item The multiple choice lists have been removed. + \item Custom definitions can be put in a \code{tasks.cfg} file which is + automatically loaded if available. +\end{itemize} + +\section{License and Requirements}\label{sec:license} +\license + +\Tasks\ requires the \bnd{l3kernel}~\cite{bnd:l3kernel} bundle, +\needpackage{xparse} and \pkg{xtemplate}. + +\section{How it works} +\subsection{Background} +The \env{tasks} environment is similar to a list like \env{enumerate} but not +the same. Here are some of the differences: +\begin{tasks}[style=enumerate] + \task there is no pagebreak possible inside an item but only between items. + \task the enumeration default is a), b), c) \ldots + \task the body of the \env{tasks} environment is 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. + This directly leads to\ldots + \task \ldots\ the fact that the \env{tasks} environment cannot be nested. + You can, however, use an \env*{itemize} environment or another + \enquote{real} list in it. + \task 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}. +\end{tasks} + +\begin{bewareofthedog} + The environments of \Tasks\ are what I like to call + \enquote{pseudo-environments}. This means like environments defined by the + package \pkg{environ}~\cite{pkg:environ} the body of the environment is read + as argument before it is processed. This is why verbatim material cannot be + used in \Tasks' lists. +\end{bewareofthedog} + +\subsection{The Basics} +\begin{environments} + \environment{tasks}[\oarg{options}\darg{num of columns}] + List like environment where the single items are introduced with + \cs{task}. +\end{environments} +Let's see an example: +\begin{example} + % \Sample is defined to contain some sample text: + % \def\sample{This is some sample text we will use to create a somewhat + % longer text spanning a few lines.} + % \def\Sample{\sample\ \sample\par\sample} + 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 \sample\ \sample + \task \sample + \task \Sample + \task \sample\par\sample + \end{tasks} +\end{example} + +\subsection{Items Spanning More Than One Column} +Sometimes it may come in handy if an item is allowed to span more than one +column. \Tasks\sinceversion{0.10} supports items using the remaining space by +adding an optional\label{optional-star} star to \cs{task}: +\begin{example} + \begin{tasks}(3) + \task \sample + \task* \sample + \task* \sample + \task \sample + \task \sample + \end{tasks} +\end{example} + +\Tasks\sinceversion{0.10} also supports items that span \emph{all} columns in +any case by adding an optional bang\label{optional-bang} to \cs{task}. +\begin{example} + \begin{tasks}(3) + \task \sample + \task! \sample + \task! \sample + \task \sample + \task \sample + \end{tasks} +\end{example} + +The optional star has itself an optional argument with parentheses where you +can specify the number of columns the item is supposed to span:\label{debug} +\begin{example} + \settasks{debug} + \begin{tasks}(4) + \task the first + \task the second + \task the third + \task the fourth + \task*(3) the fifth item is way too long for this and needs three columns + \task the sixth + \task the seventh + \task*(2) the eighth item is way too long for this and needs two columns + \task the nineth + \task the tenth + \end{tasks} +\end{example} +If there are not enough columns left (say two columns but you said +\cs{task}\sarg\Darg{3}) the argument is ignored and the maximum number of +remaining columns is used (two in case of our example). + +Both optional star and optional bang can be combined with the optional +argument for a custom label: +\begin{example} + \begin{tasks}(3) + \task \sample + \task* \sample + \task*[(x)] \sample + \task \sample + \task \sample + \end{tasks} +\end{example} + +Forcing a new item line manually is also possible\sinceversion{0.9} using the +following command: +\begin{commands} + \command{startnewitemline} + Introduce a new line in a \env{tasks} environment. +\end{commands} +While this works it also needs a bit of care since the width of the items +doesn't change which means in order to use the full width you'd have to use +trickery like \cs*{rlap} which then means the danger of the item text sticking +into the margin. + +\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 does not have any package options\changedversion{0.10}. + +The environment \env{tasks} has a number of options, though, 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{label-format}{code}\Default + \changedversion{1.1a}Can be used to apply a formatting like, \eg, + \cs*{bfseries} to the labels. This may be code accepting the item as + mandatory argument. + \keyval{label}{code}\Default{\cs*{alph}\code{*)}} + \changedversion{1.0}Sets a custom label. The \code{*} is replaced by + \Marg{task}. This is heavily inspired by + \pkg{enumitem}'s~\cite{pkg:enumitem} \code{label} option. + \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-format}{code}\Default + \sinceversion{0.11}Can be used to apply a formatting like, \eg, + \cs*{bfseries} to the items. This may be code accepting the item as + mandatory argument. + \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). Please see figure~\ref{fig:lengths} + for a sketch of the available lengths and how they are set. + \keyval{column-sep}{dim}\Default{0pt} + \sinceversion{0.10}A horizontal length that is inserted between columns ot + items. + \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. + \keyval{start}{integer}\Default{1} + \sinceversion{1.1}Set the starting value with which the list starts + counting. + \keyval{counter}{counter}\Default{task} + \sinceversion{1.2}The counter to be used to count the items. + \keybool{debug}\Default{false} + \sinceversion{0.10}If set to true \cs*{fboxsep} is set to \code{0pt} + inside the \env{tasks} environment and \cs*{fbox} is used to draw a frame + around the label boxes and the item boxes. +\end{options} + +\begin{figure} + \centering + \begin{tikzpicture}[every node/.style={font=\footnotesize},scale=.5] + \coordinate (itemedge1) at (2,2) ; + \coordinate (itemedge2) at (13,2) ; + \draw + (itemedge1) -- ++(8,0) -- ++(0,-2) -- ++(-8,0) -- cycle ; + \draw + (itemedge1) ++(-.5,0) coordinate(labeledge1) + -- ++(-1,0) --++ (0,-1) --++(1,0) --++(0,1) ; + \draw (itemedge1) ++(-2,0) -- ++(0,-2) ; + \draw + (itemedge2) -- ++(8,0) -- ++(0,-2) -- ++(-8,0) -- cycle ; + \draw + (itemedge2) ++(-.3,0) coordinate(labeledge2) + -- ++(-1,0) --++ (0,-1) --++(1,0) --++(0,1) ; + \draw (itemedge2) ++(-2,0) -- ++(0,-2) ; + \draw[<->] (itemedge2) ++(-2,0) --node[above]{column sep} ++(-1,0) ; + \draw[<->] (0,-.5) --node[below]{item indent} (2,-.5) ; + \draw[<->] (2,-.5) --node[below]{item width} (10,-.5) ; + \draw[<->] (labeledge1) ++(0,1) --node[above]{label width} ++(-1,0) ; + \draw[<->] (labeledge1) --node[above]{label offset} ++(.5,0) ; + \end{tikzpicture} + \caption{A visual representation of the used lengths.} + \label{fig:lengths} +\end{figure} + +Now the same list as above but with three columns and a different label: +\begin{example} + \begin{tasks}[label=(\roman*),label-width=4ex](2) + \task \Sample + \task \sample\ \sample + \task \sample + \task \Sample + \task \sample\par\sample + \end{tasks} +\end{example} + +Let's use it inside a question, \ie, inside \pkg{xsim}'s \env{exercise} +environment~\cite{pkg:xsim}: +\begin{example} + % since settings are local the following ones will be lost + % outside this example; + \settasks{ + label = \theexercise.\arabic* , + item-indent = 2em , + label-width = 2em , + label-offset = 0pt + } + \begin{exercise} + 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{exercise} + \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} + +Finally let's see what the \option{debug} option does (you could see it +already on page~\pageref{debug}): +\begin{example} + \settasks{debug} + \begin{tasks}(2) + \task \Sample + \task \Sample + \end{tasks} +\end{example} + +\section{Available Instances}\label{sec:tasks:instances} +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} +\end{example} + % \begin{tasks}[style=multiplechoice](2) + % \task that's just how\ldots + % \task \ldots we expected + % \end{tasks} + +\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} + +\begin{commands} + \command{tasksifmeasuringTF}[\marg{true}\marg{false}] + \sinceversion{1.2}This command used inside a label checks if the label is + typeset for measuring its width or if it is typeset \enquote{for + real}. Might be useful sometimes. There are also the variants + \cs{tasksifmeasuringT} and \cs{tasksifmeasuringF}. +\end{commands} + +\section{New \code{tasks}-like Environments} +It is possible to add custom environments that work like the \code{tasks} +environment. +\begin{commands} + \command{NewTasksEnvironment}[\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{RenewTasksEnvironment}[\oarg{options}\marg{name}\oarg{separator}\darg{cols}] + Renew environment previously defined with \cs{NewTasksEnvironment}. +\end{commands} +The \env{tasks} environment is defined as follows: +\begin{sourcecode} + \NewTasksEnvironment{tasks} +\end{sourcecode} + +The separator does not have to be a control sequence: +\begin{example} + % preamble: + % \usepackage{fontawesome} + \NewTasksEnvironment[label=\faThumbsOUp,label-width=15pt]{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. + +Please also keep in mind that the separator still has an optional star +argument (see~\pageref{optional-star}), an optional bang argument and the +standard optional argument. Using \code{*} will prevent the optional star +argument. + +\begin{example} + % preamble: + % \usepackage{fontawesome} + \NewTasksEnvironment[label=\faThumbsOUp,label-width=15pt]{done}[*] + \begin{done}(3) + * First task + * Second task + *! Third task spanning the full width available + * Fourth task + \end{done} +\end{example} + +\section{Styling \Tasks} +\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 + label : tokenlist = \alph*) , + indent : length = 2.5em , + 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}{} + % itemize + \DeclareInstance {tasks} {itemize} {default} + { + label-width = 1.125em , + label = \labelitemi + } + % enumerate: + \DeclareInstance {tasks} {enumerate} {default} + { label = \arabic*. } +\end{sourcecode} + +\clearpage +\printbibliography + +\end{document} diff --git a/Master/texmf-dist/doc/latex/tasks/tasks_en.pdf b/Master/texmf-dist/doc/latex/tasks/tasks_en.pdf deleted file mode 100644 index 27389741a3c..00000000000 Binary files a/Master/texmf-dist/doc/latex/tasks/tasks_en.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/tasks/tasks_en.tex b/Master/texmf-dist/doc/latex/tasks/tasks_en.tex deleted file mode 100644 index 8821283a822..00000000000 --- a/Master/texmf-dist/doc/latex/tasks/tasks_en.tex +++ /dev/null @@ -1,527 +0,0 @@ -% -------------------------------------------------------------------------- -% the TASKS package -% -% horizontally columned lists -% -% -------------------------------------------------------------------------- -% Clemens Niederberger -% Web: https://github.com/cgnieder/tasks/ -% E-Mail: contact@mychemistry.eu -% -------------------------------------------------------------------------- -% Copyright 2013--2020 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. -% -------------------------------------------------------------------------- -% If you have any ideas, questions, suggestions or bugs to report, please -% feel free to contact me. -% -------------------------------------------------------------------------- -\documentclass[load-preamble+]{cnltx-doc} -\usepackage{tasks} - -\setcnltx{ - package = {tasks} , - authors = Clemens Niederberger , - email = {contact@mychemistry.eu} , - url = {https://github.com/cgnieder/tasks/} , - info = {horizontally columned lists} , - add-cmds = { - NewTasksEnvironment, - RenewTasksEnvironment, - settasks, - startnewitemline , - task - } , - add-silent-cmds = { - DeclareInstance, DeclareTemplateInterface, - leftthumbsup, - sample, Sample , theexercise - } -} - -\newpackagename\ExSheets{ExSheets} -\newpackagename\xsim{xsim} -\newpackagename\Tasks{tasks} - -% ---------------------------------------------------------------------------- -% other packages, bibliography, index -\usepackage{xcoffins,tikz,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{xsim} -\usepackage{dingbat} - -\newcommand*\sample{This is some sample text we will use to create a somewhat - longer text spanning a few lines.} -\newcommand*\Sample{\sample\ \sample\par\sample} - -\begin{document} - -\section{Preface} -\subsection{Motivation} -Originally \Tasks\ has been an integral part of the -\ExSheets\changedversion{0.7} package. 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. Since then \Tasks{} has been distributed as a package of its -own but as part of the \ExSheets{} bundle\changedversion{0.10}. With v0.10 I -decided to make it a completely independent package. So the relation to -\ExSheets{} only is a historical one. - -The reason for the \env{tasks} environment is an unwritten agreement in German -maths textbooks (exspecially in (junior) high school textbooks) 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. - -\subsection{Changes} -The \sinceversion{1.0} step to version~1.0 brought some significant changes: -\begin{itemize} - \item the option \option{counter-format} is deprecated. Labels can now be - set quite similar to the way they are set in \pkg{enumitem}. This also - made the \code{enumerate} option of the list template superfluous which has - been removed accordingly. - \item The commands \cs{NewTasks} and \cs{RenewTasks} have been renamed. - \item The multiple choice lists have been removed. - \item Custom definitions can be put in a \code{tasks.cfg} file which is - automatically loaded if available. -\end{itemize} - -\section{License and Requirements}\label{sec:license} -\license - -\Tasks\ requires the \bnd{l3kernel}~\cite{bnd:l3kernel} bundle, -\needpackage{xparse} and \pkg{xtemplate}. - -\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: the body of the \env{tasks} environment is 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. This directly leads to\ldots - \item \ldots{} a fourth difference: the \env{tasks} environment cannot be - nested. You can, however, use an \env*{itemize} environment or another - \enquote{real} list 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 introduced with - \cs{task}. -\end{environments} -Let's see an example: -\begin{example} - % \Sample is defined to contain some sample text: - % \def\sample{This is some sample text we will use to create a somewhat - % longer text spanning a few lines.} - % \def\Sample{\sample\ \sample\par\sample} - 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 \sample\ \sample - \task \sample - \task \Sample - \task \sample\par\sample - \end{tasks} -\end{example} - -\subsection{Items Spanning More Than One Column} -Sometimes it may come in handy if an item is allowed to span more than one -column. \Tasks\sinceversion{0.10} supports items using the remaining space by -adding an optional\label{optional-star} star to \cs{task}: -\begin{example} - \begin{tasks}(3) - \task \sample - \task* \sample - \task* \sample - \task \sample - \task \sample - \end{tasks} -\end{example} - -\Tasks\sinceversion{0.10} also supports items that span \emph{all} columns in -any case by adding an optional bang\label{optional-bang} to \cs{task}. -\begin{example} - \begin{tasks}(3) - \task \sample - \task! \sample - \task! \sample - \task \sample - \task \sample - \end{tasks} -\end{example} - -The optional star has itself an optional argument with parentheses where you -can specify the number of columns the item is supposed to span:\label{debug} -\begin{example} - \settasks{debug} - \begin{tasks}(4) - \task the first - \task the second - \task the third - \task the fourth - \task*(3) the fifth item is way too long for this and needs three columns - \task the sixth - \task the seventh - \task*(2) the eighth item is way too long for this and needs two columns - \task the nineth - \task the tenth - \end{tasks} -\end{example} -If there are not enough columns left (say two columns but you said -\cs{task}\sarg\Darg{3}) the argument is ignored and the maximum number of -remaining columns is used (two in case of our example). - -Both optional star and optional bang can be combined with the optional -argument for a custom label: -\begin{example} - \begin{tasks}(3) - \task \sample - \task* \sample - \task*[(x)] \sample - \task \sample - \task \sample - \end{tasks} -\end{example} - -Forcing a new item line manually is also possible\sinceversion{0.9} using 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} - -While this works it also needs a bit of care since the width of the items -doesn't change which means in order to use the full width you'd have to use -trickery like \cs*{rlap} which then means the danger of the item text sticking -into the margin\ldots - -\section{Available Options}\label{sec:tasks:options} - -The \Tasks{} package does not have any package options\changedversion{0.10}. - -The environment \env{tasks} has a number of options, though, 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{label-format}{code}\Default - \changedversion{1.1a}Can be used to apply a formatting like, \eg, - \cs*{bfseries} to the labels. This may be code accepting the item as - mandatory argument. - \keyval{label}{code}\Default{\cs*{alph}\code{*)}} - \changedversion{1.0}Sets a custom label. The \code{*} is replaced by - \Marg{task}. This is heavily inspired by - \pkg{enumitem}'s~\cite{pkg:enumitem} \code{label} option. - \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-format}{code}\Default - \sinceversion{0.11}Can be used to apply a formatting like, \eg, - \cs*{bfseries} to the items. This may be code accepting the item as - mandatory argument. - \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). Please see figure~\ref{fig:lengths} - for a sketch of the available lengths and how they are set. - \keyval{column-sep}{dim}\Default{0pt} - \sinceversion{0.10}A horizontal length that is inserted between columns ot - items. - \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. - \keyval{start}{integer}\Default{1} - \sinceversion{1.1}Set the starting value with which the list starts - counting. - \keybool{debug}\Default{false} - \sinceversion{0.10}If set to true \cs*{fboxsep} is set to \code{0pt} - inside the \env{tasks} environment and \cs*{fbox} is used to draw a frame - around the label boxes and the item boxes. -\end{options} - -\begin{figure} - \centering - \begin{tikzpicture}[every node/.style={font=\footnotesize},scale=.5] - \coordinate (itemedge1) at (2,2) ; - \coordinate (itemedge2) at (13,2) ; - \draw - (itemedge1) -- ++(8,0) -- ++(0,-2) -- ++(-8,0) -- cycle ; - \draw - (itemedge1) ++(-.5,0) coordinate(labeledge1) - -- ++(-1,0) --++ (0,-1) --++(1,0) --++(0,1) ; - \draw (itemedge1) ++(-2,0) -- ++(0,-2) ; - \draw - (itemedge2) -- ++(8,0) -- ++(0,-2) -- ++(-8,0) -- cycle ; - \draw - (itemedge2) ++(-.3,0) coordinate(labeledge2) - -- ++(-1,0) --++ (0,-1) --++(1,0) --++(0,1) ; - \draw (itemedge2) ++(-2,0) -- ++(0,-2) ; - \draw[<->] (itemedge2) ++(-2,0) --node[above]{column sep} ++(-1,0) ; - \draw[<->] (0,-.5) --node[below]{item indent} (2,-.5) ; - \draw[<->] (2,-.5) --node[below]{item width} (10,-.5) ; - \draw[<->] (labeledge1) ++(0,1) --node[above]{label width} ++(-1,0) ; - \draw[<->] (labeledge1) --node[above]{label offset} ++(.5,0) ; - \end{tikzpicture} - \caption{A visual representation of the used lengths.} - \label{fig:lengths} -\end{figure} - -Now the same list as above but with three columns and a different label: -\begin{example} - \begin{tasks}[label=(\roman*),label-width=4ex](2) - \task \Sample - \task \sample\ \sample - \task \sample - \task \Sample - \task \sample\par\sample - \end{tasks} -\end{example} - -Let's use it inside a question, \ie, inside \xsim's \env{exercise} -environment: -\begin{example} - % since settings are local the following ones will be lost - % outside this example; - \settasks{ - label = \theexercise.\arabic* , - item-indent = 2em , - label-width = 2em , - label-offset = 0pt - } - \begin{exercise} - 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{exercise} - \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} - -Finally let's see what the \option{debug} option does (you could see it -already on page~\pageref{debug}): -\begin{example} - \settasks{debug} - \begin{tasks}(2) - \task \Sample - \task \Sample - \end{tasks} -\end{example} - -\section{Available Instances}\label{sec:tasks:instances} -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} -\end{example} - % \begin{tasks}[style=multiplechoice](2) - % \task that's just how\ldots - % \task \ldots we expected - % \end{tasks} - -\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 \code{tasks}-like Environments} -It is possible to add custom environments that work like the \code{tasks} -environment. -\begin{commands} - \command{NewTasksEnvironment}[\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{RenewTasksEnvironment}[\oarg{options}\marg{name}\oarg{separator}\darg{cols}] - Renew environment previously defined with \cs{NewTasksEnvironment}. -\end{commands} -The \env{tasks} environment is defined as follows: -\begin{sourcecode} - \NewTasksEnvironment{tasks} -\end{sourcecode} - -The separator does not have to be a control sequence: -\begin{example} - % preamble: - % \usepackage{dingbat} - \NewTasksEnvironment[label=\footnotesize\leftthumbsup,label-width=15pt]{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. - -Please also keep in mind that the separator still has an optional star -argument (see~\pageref{optional-star}), an optional bang argument and the -standard optional argument. Using \code{*} will prevent the optional star -argument. - -\begin{example} - % preamble: - % \usepackage{dingbat} - \NewTasksEnvironment[label=\footnotesize\leftthumbsup,label-width=15pt]{done}[*] - \begin{done}(3) - * First task - * Second task - *! Third task spanning the full width available - * Fourth task - \end{done} -\end{example} - -\section{Styling \Tasks} -\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 - label : tokenlist = \alph*) , - indent : length = 2.5em , - 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}{} - % itemize - \DeclareInstance {tasks} {itemize} {default} - { - label-width = 1.125em , - label = \labelitemi - } - % enumerate: - \DeclareInstance {tasks} {enumerate} {default} - { label = \arabic*. } -\end{sourcecode} - -\end{document} -- cgit v1.2.3