summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/tasks/tasks-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/tasks/tasks-manual.tex')
-rw-r--r--macros/latex/contrib/tasks/tasks-manual.tex498
1 files changed, 498 insertions, 0 deletions
diff --git a/macros/latex/contrib/tasks/tasks-manual.tex b/macros/latex/contrib/tasks/tasks-manual.tex
new file mode 100644
index 0000000000..2bcfb18d3e
--- /dev/null
+++ b/macros/latex/contrib/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}