From 48f8b21c2d50f6df0ccca85645ed3d6f7f0dd4a0 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 22 Jan 2013 23:46:45 +0000
Subject: exsheets/tasks 0.7a (22jan13)

git-svn-id: svn://tug.org/texlive/trunk@28907 c570f23f-e606-0410-a88d-b1316a301751
---
 .../texmf-dist/doc/latex/exsheets/exsheets_en.tex  | 676 +++++++++++++--------
 1 file changed, 407 insertions(+), 269 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex')

diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
index 9147ad61bda..34ea299cfee 100644
--- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
+++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
@@ -28,7 +28,7 @@
 % --------------------------------------------------------------------------
 % The exsheets package consists of the files
 %  - exsheets.sty, exsheets_headings.def, exsheets_headings.cfg,
-%    exsheets_tasks.def, exsheets_tasks.cfg, exsheets_configurations.cfg,
+%    exsheets_configurations.cfg,
 %  - exsheets_en.tex, exsheets_en.pdf,
 %  - README
 % --------------------------------------------------------------------------
@@ -49,7 +49,10 @@
 \docsetup{
   pkg      = {[load-headings,load-tasks]exsheets} ,
   url      = {https://bitbucket.org/cgnieder/exsheets/} ,
-  title    = ExSheets ,
+  title    = the ExSheets bundle ,
+  subtitle = {the packages \ExSheets, \Tasks, \translations and \cntformats\\
+    \emph{or}\\
+    Yet another package for the creation of exercise sheets and exams.} ,
   name     = ExSheets ,
   language = en ,
   modules  = true ,
@@ -65,6 +68,7 @@
 \makeatletter
 \edef\trnsltversion{\@trnslt@version}
 \edef\cntfmtsversion{\@cntfmts@version}
+\edef\tasksversion{v\@tasks@version}
 \makeatother
 \cnpkgusecolorscheme{friendly}
 
@@ -95,13 +99,13 @@
   DeclareInstance, DeclareTemplateInterface, DeclareQuestionProperty,
     DebugExSheets, endspacing, examspace, ForEachQuestion, GetQuestionProperty,
   grade, includequestions, iflastquestion,
-  midrule, NewQuSolPair, NewTasks, numberofquestions, points,
+  midrule, NewQuSolPair, numberofquestions, points,
   PrintIfIncludeActiveF, PrintIfIncludeActiveT, PrintIfIncludeActiveTF,
     printsolutions, PrintSolutionsF, PrintSolutionsTF, PrintSolutionsT,
   QuestionNumber, RenewQuSolPair, rightarrow, s, sample, setlength,
   SetQuestionProperties, SetupExSheets, SetVariations, spacing, square,
     sumpoints,
-  tabcolsep, task, textcite, textcolor, toprule, totalpoints,
+  tabcolsep, textcite, textcolor, toprule, totalpoints,
   variant, vary
 }
 
@@ -128,11 +132,22 @@
   ReadCounterPatternFrom, SaveCounterPattern, tmpa, tmpb
 }
 
+% tasks:
+\newcommand*\Tasks{{\scshape\textcolor{main}{tasks}}\xspace}
+\addcmds{
+  leftthumbsup, NewTasks, settasks, task
+}
 % ----------------------------------------------------------------------------
 % other packages, bibliography, index
-\usepackage{xcoffins,wasysym,enumitem,acro,booktabs,siunitx}
-\DeclareAcronym{id}{id}{Identifier}
-\DeclareAcronymFormat{id}{\scshape}
+\usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx}
+\usepackage[accsupp]{acro}
+\DeclareAcronym{id}{
+  short     = id ,
+  long      = Identifier ,
+  format    = \scshape ,
+  pdfstring = ID ,
+  accsupp   = ID
+}
 
 \usepackage{filecontents}
 \begin{filecontents}{\jobname.ist}
@@ -226,6 +241,9 @@
 }
 
 \usepackage{amssymb}
+\let\checkmark\relax
+\usepackage{dingbat}
+
 \NewQuSolPair
   {question*}[name=\protect\llap{$\bigstar$\space}Bonus Question]
   {solution*}[name=\protect\llap{$\bigstar$\space}Solution]
@@ -241,9 +259,7 @@
 \DeclareTranslation{British}{foo}{bar}
 
 \usepackage{alphalph}
-\makeatletter
-\NewPatternFormat{aa}{\alphalph@alph}
-\makeatother
+\NewPatternFormat{aa}{\alphalph}
 \NewCounterPattern{testa}{ta}
 
 % ----------------------------------------------------------------------------
@@ -303,6 +319,7 @@
    questions and solutions.}}
 
 \begin{document}
+
 \part{Preliminary}\secidx{Preliminary}
 \section{Licence and Requirements}
 \secidx[Licence]{Preliminary}\secidx[Requirements]{Preliminary}
@@ -312,8 +329,8 @@ It has the status ``maintained.''
 
 \ExSheets loads and needs the following packages: \paket*{l3kernel},
 \paket{xparse}, \paket{xtemplate}, \paket{l3sort}, \paket{l3keys2e},
-\paket{xcolor}, \paket{ulem}, \paket{etoolbox}, \paket{environ}, \paket{lcg}
-and \paket{silence}. \ExSheets calls \cmd{normalem} (from the \paket{ulem} package).
+\paket{xcolor}, \paket{ulem}, \paket{etoolbox}, \paket{environ}, and
+\paket{pgfcore}. \ExSheets calls \cmd{normalem} (from the \paket{ulem} package).
 
 \section{Motivation}\secidx[Motivation]{Preliminary}
 There are already quite a number of packages that allow the creation of exercise
@@ -337,7 +354,7 @@ in section~\ref{sec:additional_info}.
 
 Then there is --~at least in Germany~-- the habit of having lists of exercises
 aligned in columns but counting from the left to the right instead from up to
-down. \ExSheets provides a possibility for that (see section~\ref{sec:tasks}).
+down. \ExSheets provides a possibility for that (see part~\ref{part:tasks}).
 I am not quite content with it as it works now, though\footnote{There are still
 other possibilities, for example take a look here:
 \url{http://tex.stackexchange.com/questions/67966/enumerate-in-multicols} or at
@@ -358,31 +375,56 @@ of writing (\today) there still are probably lots of rough edges let alone bugs
 so I am very interested in all kinds of feedback.
 
 \section{Additional Packages}
-\ExSheets actually bundles three packages: \ExSheets, \translations and \cntformats.
-\translations is described in part~\ref{part:translations} and \cntformats in
-part~\ref{part:cntformats}. These two packages provide functionality that is used
-by \ExSheets. They can, however, be used independently from \ExSheets.
+\ExSheets actually bundles four packages: \ExSheets, \Tasks, \translations and
+\cntformats. \Tasks is described in part~\ref{part:tasks}, \translations is
+described in part~\ref{part:translations} and \cntformats in part~\ref{part:cntformats}.
+These packages provide functionality that is used by \ExSheets. They can, however,
+be used independently from \ExSheets.
 
 \section{Installation}\secidx[Installation]{Preliminary}
 If you install \ExSheets manually beware to put the files
 \begin{itemize}
  \item[]\verb+exsheets_headings.def+
  \item[]\verb+exsheets_headings.cfg+
- \item[]\verb+exsheets_tasks.def+
- \item[]\verb+exsheets_tasks.cfg+
 \end{itemize}
 in the same directory as the \code{exsheets.sty} file\footnote{That is, a directory
 like \code{texmf-local/tex/latex/exsheets}, probably}. You \emph{can} install the
-other two packages, \translations and \cntformats, in different locations but since
-they belong to \ExSheets they probably should be placed in the same directory.
+other packages, \Tasks, \translations and \cntformats, in different locations but
+since they belong to \ExSheets they probably should be placed in the same directory.
+
+You should put the file \code{tasks.cfg} in the same directory as the \code{tasks.sty}
+file.
 
 As with every manual package installation you need to make sure to put the files
 in a directory where \TeX\ can find them and afterwards update the database.
+
+\section{News}
+With version~0.7 there has been a potentially breaking change: the \code{tasks}
+environment previously provided by \ExSheets has been extracted into a package
+of its own. This does not change any syntax \emph{per se}. However, if you used
+custom settings then you'll probably run into some problems. The options for the
+environment are no longer set with \cmd{SetupExSheets} but with \cmd{settasks}.
+Also the object that is used for the list template and its instances has been
+renamed from \code{exsheets-tasks} into \code{tasks}.
+
+What's probably even more of a breaking change is a syntax difference of the
+\code{tasks} environment: the optional argument for the number of columns is
+\emph{no longer set in braces but parentheses}. This is deliberate as it
+reflects the optional nature of the argument better and is consistent with the
+syntax of \cmd{NewTasks}, too.
+
+Additionally the labels of the list got an additional offset of \code{1ex} from
+the items which will lead to slightly different output. In some cases this might
+actually lead to the most annoying changes. In this case say
+\cmd{settasks}{label-offset=0pt} which should cure things again.
+
+I am very sorry for any inconvenience! I am trying to keep such changes as minimal
+and rare as possibly. However, it is not always avoidable when a package is new
+and still a child. It will grow up eventually.
 \secidx*{Preliminary}
 
 \part{The \ExSheets package}\label{part:exsheets}\secidx{\ExSheets}[ExSheets]
-\section{Package Usage}
-\subsection{Setup}\secidx{Setup}
+\section{Setup}\secidx{Setup}
 The \ExSheets package has three different types of options, kind of. The first
 type are the classic package options which are used when you load \ExSheets:
 \begin{beispiel}[code only]
@@ -418,7 +460,7 @@ the objects used be \ExSheets. This is explained in a little more detail in
 part~\ref{part:style} on page~\pageref{part:style}\,ff.
 \secidx*{Setup}
 
-\subsection{Package Options}\label{sec:options}\secidx{Package Options}
+\section{Package Options}\label{sec:options}\secidx{Package Options}
 The package \ExSheets has some options, namely the following ones:
 \begin{beschreibung}
  %% color
@@ -430,6 +472,11 @@ The package \ExSheets has some options, namely the following ones:
    of string that is described in section~\ref{ssec:counter}.
  \Option{counter-within}{<counter>}\Default{}
    Resets the \code{question} counter with every step of \code{<counter>}.
+ %% auto-label
+ \Option{auto-label}{\default{true}|false}\Default{false}
+   If set to true \ExSheets will automatically place a \cmd*{label}{qu:<id>}
+   for each question. It will also create the question properties \code{ref}
+   and \code{pageref}, see section~\ref{sec:additional_info} for more on this.
  %% headings
  \Option{headings}{<instance>}\Default{block}
    Choose the style of the questions' and solutions' headings. There are two
@@ -444,7 +491,7 @@ The package \ExSheets has some options, namely the following ones:
    section~\ref{sec:exsheets-headings}.
  %% load-tasks
  \Option{load-tasks}{\default{true}|false}\Default{false}
-   Loads additional styles for the \code{tasks} environment. See section~\ref{sec:tasks}.
+   Loads additional styles for the \code{tasks} environment. See part~\ref{part:tasks}.
  %% totoc
  \Option{totoc}{\default{true}|false}\Default{false}
    This option adds the questions and solutions with their names and numbers to
@@ -479,10 +526,10 @@ The \code{toc} options are demonstrated with section~\ref{sec:solutions:list} an
 the solutions printed there being listed in the table of contents.
 \secidx*{Package Options}
 
-\subsection{Create Questions/Exercises and their Solutions}
+\section{Create Questions/Exercises and their Solutions}
 Now, let's start with the most important part: the questions and (possibly) their
 respective solutions.
-\subsubsection{The \code{question} Environment}\label{ssec:questions}
+\subsection{The \code{question} Environment}\label{ssec:questions}
 Questions are written inside the \code{question} environment:
 \begin{beschreibung}
  \Umg{question}[<options>]{\unskip\ma{<points>} ... }
@@ -526,7 +573,7 @@ commands that should behave differently if they're inside or outside of the
  \expandable\Befehl{IfInsideQuestionF}{<false code>}
 \end{beschreibung}
 
-\subsubsection{Options to the \code{question} Environment}\secidx[options]{questions}
+\subsection{Options to the \code{question} Environment}\secidx[options]{questions}
 The \code{question} environment takes one or more of the following options:
 \begin{beschreibung}
  \Option[question]{type}{exam|exercise}\Default{exercise}
@@ -541,6 +588,9 @@ The \code{question} environment takes one or more of the following options:
  \Option[question]{ID}{<id>}\Default{}
    assigns a custom \acs{id} to the question. See section~\ref{ssec:ids} for further
    information.
+ \Option[question]{label}{<label>}\Default{}
+   Places a \cmd*{label}{<label>} for the question. This will overwrite any label
+   that is placed by the \key{auto-label} option.
  \Option[question]{class}{<class>}\Default{}
    assigns a class to the question. See section~\ref{sec:classes} for further
    information.
@@ -571,7 +621,7 @@ is fully discarded which means it is not accessible through an \acs{id} and a po
 solution will not be saved.
 \secidx*{questions}
 
-\subsubsection{The \code{solution} Environment}\secidx{solutions}
+\subsection{The \code{solution} Environment}\secidx{solutions}
 If you want to save/print (more on the exact usage in section~\ref{sec:solutions})
 a solution you have to use the \code{solution} environment \emph{after} the
 question it belongs to and \emph{before} the next question.
@@ -590,7 +640,7 @@ You can see that in the default settings the solution is \emph{not} written to t
 document. It has been saved, though, for possible later usage. We will see the
 solution later!
 
-\subsubsection{Options to the \code{solution} Environment}\secidx[options]{solutions}
+\subsection{Options to the \code{solution} Environment}\secidx[options]{solutions}
 The \code{solutions} environment also has options, namely these:
 \begin{beschreibung}
  \Option[solution]{name}{<name>}\Default{}
@@ -619,14 +669,14 @@ Their meaning is the same as those for the \code{question} environment.
 \end{beispiel}
 \secidx*{solutions}
 
-\subsubsection{Setting the Counter}\label{ssec:counter}\secidx{Setting the Counter}
+\subsection{Setting the Counter}\label{ssec:counter}\secidx{Setting the Counter}
 The package option \key{counter-format} allows you to specify how
 the question counter is formatted.
 
 The input is an arbitrary string which means you can have anything as counter
 number. However, the letter combinations \code{ch}, \code{se}, \code{qu} and
 \code{tsk} are replaced with the counters for the chapter, section, question
-or tasks (see section~\ref{sec:tasks}), respectively. While the last one is not
+or tasks (see part~\ref{part:tasks}), respectively. While the last one is not
 really useful in this case the others allow for a combined numbering. Each of
 these letter combinations can have an optional argument that specifies the format
 of the respective counter. \code{1}: \cmd{arabic}, \code{a}: \cmd{alph}, \code{A}:
@@ -648,7 +698,7 @@ interrupt them by an empty group.
 \end{beispiel}
 \secidx*{Setting the Counter}
 
-\subsubsection{Language Settings}\secidx{Language Settings}
+\subsection{Language Settings}\secidx{Language Settings}
 The names of the questions and solutions are language dependent. If you use
 \paket{babel} or \paket{polyglossia} \ExSheets will adapt to the document
 language. Exsheets has a number of translations but surely not all! If you miss
@@ -673,8 +723,8 @@ the \translations package (see part~\ref{part:translations}). In this case pleas
 notify me, too. You then can still use the \key{name} options.
 \secidx*{Language Settings}
 
-\subsection{Counting Points}\label{sec:points}\secidx{Counting Points}
-\subsubsection{The Commands}
+\section{Counting Points}\label{sec:points}\secidx{Counting Points}
+\subsection{The Commands}
 You have seen in section~\ref{ssec:questions} that you can assign points to a
 question. If you do so these points are printed into the margin\footnote{Well,
 not necessarily. It depends on the heading style you have chosen.} and are counted
@@ -738,7 +788,7 @@ You have two possibilities to display and count them:
  \end{question}
 \end{beispiel}
 
-\subsubsection{Options}\secidx[options]{Counting Points}
+\subsection{Options}\secidx[options]{Counting Points}
 \begin{beschreibung}
  \Option[points]{name}{<name>}\Default{P.}
    Choose the ``unit'' for the points. If you like to differentiate between a
@@ -785,7 +835,7 @@ You have two possibilities to display and count them:
 \end{beispiel}
 \secidx*{Counting Points}
 
-\subsection{Printing Solutions}\label{sec:solutions}\secidx[print]{solutions}
+\section{Printing Solutions}\label{sec:solutions}\secidx[print]{solutions}
 You have already seen that you can print solutions where they are using the
 \key[solution]{print} option. But \ExSheets offers you quite more possibilities.
 
@@ -812,7 +862,7 @@ They might come in handy if you want two versions of an exercise sheet, one with
 the exercises and one with the solutions, and you want to add different titles
 to these versions, for instance.
 
-\subsubsection{Print all}\secidx[print!all]{solutions}
+\subsection{Print all}\secidx[print!all]{solutions}
 The first and easiest usage of \cmd{printsolutions} is the following:
 \begin{beispiel}[code only]
  \printsolutions
@@ -827,7 +877,7 @@ sections.
  \printsolutions
 \end{beispiel}
 
-\subsubsection{Print per chapter/section}\secidx[print!per section/chapter]{solutions}
+\subsection{Print per chapter/section}\secidx[print!per section/chapter]{solutions}
 \minisec{Current chapter/section}
 If you are not creating an exercise sheet or an exam but are writing a textbook
 you maybe want a section at the end of each chapter showing the solution to the
@@ -908,7 +958,7 @@ is as follows:
 Please be aware that the labels must be processed in a previous \LaTeX\ run before
 \cmd{S} and \cmd{C} can pass them on to \cmd{printsolutions}.
 
-\subsubsection{Print by \texorpdfstring{\acs{id}}{ID}}\label{ssec:ids}\secidx[print!by ID]{solutions}
+\subsection{Print by \texorpdfstring{\acs{id}}{ID}}\label{ssec:ids}\secidx[print!by ID]{solutions}
 Now comes the best part: you can also print selected solutions! Every question
 has an \acs{id}. To see which \acs{id} a question has you can call the following
 command:
@@ -949,7 +999,7 @@ order given you can use the option
    Sort solutions given by \acs{id} or don't.
 \end{beschreibung}
 
-\subsection{Using Classes}\label{sec:classes}\secidx{Classes}
+\section{Using Classes}\label{sec:classes}\secidx{Classes}
 For creating different variants of a written exam or different difficulty levels
 of an exercise sheet it comes in handy if one can assign certain classes to questions
 and then tell \ExSheets only to use one ore more specific classes.
@@ -977,7 +1027,7 @@ that questions that don't have a class assigned are discarded.}
  \bool_set_false:N \g__exsheets_use_classes_bool
 \ExplSyntaxOff
 
-\subsection{Using Topics}\label{sec:topics}\secidx{Topics}
+\section{Using Topics}\label{sec:topics}\secidx{Topics}
 Similarly to classes one can assign topics to questions. The usage is practically
 identical, the semantic meaning is different.
 \begin{beschreibung}
@@ -1007,7 +1057,7 @@ supported yet.
  \bool_set_false:N \g__exsheets_use_topics_bool
 \ExplSyntaxOff
 
-\subsection{Variations of an Exam}\secidx{Variations}
+\section{Variations of an Exam}\secidx{Variations}
 \noindent\sinceversion{0.6}It is a quite common task to design an exam in two
 different variants. This is of course possible with \ExSheets' classes (see
 section~\ref{sec:classes}). However, often not the whole question is to be
@@ -1038,7 +1088,7 @@ purpose \ExSheets provides the following commands:
 \end{beispiel}
 \secidx*{Variations}
 
-\subsection{A Grade Distribution}\secidx{Grade Distribution}
+\section{A Grade Distribution}\secidx{Grade Distribution}
 Probably this is a rather esoteric feature but it could proof useful in some cases.
 Suppose you are a German math teacher and want to grade exactly corresponding to
 the number of points relative to the sum of total points, regardless of how big
@@ -1082,7 +1132,7 @@ These are the available commands and options:
 \end{beschreibung}
 \secidx*{Grade Distribution}
 
-\subsection{Adding and Using Additional Information to Questions}\label{sec:additional_info}
+\section{Adding and Using Additional Information to Questions}\label{sec:additional_info}
 \secidx{Additional Information to Questions}
 For managing lots of questions and corresponding solutions it can be very useful
 to be able to save and recover additional information to the questions. This is
@@ -1163,6 +1213,10 @@ It is now possible to recover these values later:
  \end{center}
 \end{beispiel}
 
+\sinceversion{0.7a}If you use the package option \key{auto-label} the properties
+\code{ref} and \code{pageref} are predefined which will call the corresponding
+\cmd*{ref} or \cmd*{pageref}, respectively.
+
 \sinceversion{0.3}There are additional commands that might prove useful:
 \begin{beschreibung}
  \Befehl{ForEachQuestion}{<code to be executed for each used question>}\newline
@@ -1204,7 +1258,7 @@ For four questions the table now would look similar to figure~\ref{fig:grading-t
 \end{figure}
 \secidx*{Additional Information to Questions}
 
-\subsection{Selectively Include Questions from External Files}\label{sec:include}
+\section{Selectively Include Questions from External Files}\label{sec:include}
 \secidx{Include from External Files}
 Suppose you have one or more files with questions prepared to use them as a kind
 of database. One for class A, say, one for class B, one for class C and so one,
@@ -1242,9 +1296,7 @@ are however the following options:
    Includes only the specified questions.
  \Option[include]{random}{<num>}\Default{}
    Includes \code{<num>} randomly selected questions. This option uses the
-   \paket{lcg} package to create the pseudo-random numbers.
- \Option[include]{seed}{<num>}\Default{-1}
-   Sets the seed for the pseudo-random numbers.
+   \paket{pgfcore} package to create the pseudo-random numbers.
 \end{beschreibung}
 The usage should be self-explainable:
 \begin{beispiel}[code only]
@@ -1254,7 +1306,7 @@ The usage should be self-explainable:
  \includequestions[random=3]{classA}
 \end{beispiel}
 In order to be able to select the questions \ExSheets needs to \cmd{input} the
-file twice. The first time the available questions are detemined, the second time
+file twice. The first time the available questions are determined, the second time
 the selected questions are used. This unfortunately means that anything that is
 \emph{not} part of a question or solution is also input twice. Either don't do
 that or use one of the following commands for control:
@@ -1267,12 +1319,11 @@ that or use one of the following commands for control:
 If you use the \key{random} option you need to be aware of the following facts:
 the options \key{use-classes}, \key{use-topics} and \key{question/print} are not
 considered when selecting the questions which means you might end up with less
-questions included than you've specified. The option \key{question/use} is also
-not taken into consideration. In fact it is completely ignored and the questions
-are included anyway. I'm still not sure this is a feature or a bug\ldots
+questions included than you've specified. I'm still not sure this is a feature
+or a bug\ldots
 \secidx*{Include from External Files}
 
-\subsection{Own Question/Solution Pairs}
+\section{Own Question/Solution Pairs}
 \noindent\sinceversion{0.3}\ExSheets provides he possibility to create new
 environments that behave like the \code{question} and \code{solution} environments.
 This would allow, for example, to define a \code{question*}/\code{solution*}
@@ -1304,193 +1355,8 @@ to define starred variants that add a star in the margin left to the title:
 As you can see the environments take the same options as are described for the
 standard \code{question} and \code{solution} environments.
 
-\subsection{The \code{tasks} Environment}\label{sec:tasks}\secidx{tasks}
-\subsubsection{How it works}
-\noindent\changedversion{0.4}The \code{tasks} environment is similar to a list
-like \code{enumerate} but not the same. The first difference: there is no
-pagebreak possible inside an item but only between items. The second difference:
-the enumeration default is a), b), c) \ldots 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. The fourth difference: the \code{tasks} environment cannot
-be nested. You can, however, use an \code{itemize} environment or something in
-it.
-\begin{beschreibung}
- \Umg{tasks}[<options>]{\unskip\ma{<num of columns>} list of tasks introduced
-   with \cmd{task}}
-\end{beschreibung}
-Let's use some sample text in the next few examples:
-\begin{beispiel}[code only]
- \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}
-\end{beispiel}
-\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{beispiel}[below]
- Some text before the list.
- \begin{tasks}
-  \task \sample
-  \task \sample
-  \task \sample
- \end{tasks}
- And also some text after it.
-\end{beispiel}
-The environment takes the optional argument \ma{<num of columns>} with which the
-number of columns used by the environment is specified.
-\begin{beispiel}[below]
- \begin{tasks}{2}
-  \task \sample
-  \task \s\ \s
-  \task \s
-  \task \sample
-  \task \s\par\s
- \end{tasks}
-\end{beispiel}
-
-\subsubsection{Available Options}\secidx[Options]{tasks}\label{sssec:tasks:options}
-The environment has some options, namely these:
-\begin{beschreibung}
- \Option[tasks]{style}{<instance>}\Default{}
-   Choose the instance to be used. Read more on this in section~\ref{sec:exsheets-tasks}.
- \Option[tasks]{label}{<label specs>}\Default{}
-   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[tasks]{label-width}{<dim>}\Default{3ex}
-   Sets the width of the item labels.
- \Option[tasks]{before-skip}{<skip>}\Default{0pt}
-   Sets the skip before the list.
- \Option[tasks]{after-skip}{<skip>}\Default{0pt}
-   Sets the skip after the list.
- \Option[tasks]{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}
-
-Now the same list as above but with three columns and a different label:
-\begin{beispiel}[below]
- \begin{tasks}[label=(tsk[r]),label-width=4ex]{3}
-  \task \sample
-  \task \s\ \s
-  \task \s
-  \task \sample
-  \task \s\par\s
- \end{tasks}
-\end{beispiel}
-
-Let's use it inside a question:
-\begin{beispiel}
- \SetupExSheets[tasks]{label=qu.tsk,label-width=5ex}
- \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}
-
-\subsubsection{Available Instances}
-When you use the package option \key{load-tasks} there are currently three
-additional instances for the \code{tasks} are 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}
-
-\subsubsection{Custom Labels}\secidx[Custom Labels]{tasks}
-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}
-
-\subsubsection{New Tasks}\secidx[Own Environments]{tasks}
-\noindent\sinceversion{0.3b}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{sssec:tasks:options}.
-\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}
- \NewTasks[label=$\rightarrow$]{todo}[>]
- \begin{todo}
-  > First task
-  > Second Task
- \end{todo}
-\end{beispiel}
-
-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}}
- \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*{tasks}
-
-\subsection{Filling in the Blanks}\secidx{Blanks}
-\subsubsection{Cloze}\secidx[Cloze]{Blanks}
+\section{Filling in the Blanks}\secidx{Blanks}
+\subsection{Cloze}\secidx[Cloze]{Blanks}
 \noindent\changedversion{0.4}Both in exercise sheets and in exams it is sometimes
 desirable to be able to create \blank{blanks} that have to be filled in. Or may
 be some more lines: \blank[width=5\linewidth]{}
@@ -1535,7 +1401,7 @@ A number of empty lines are easily created by setting the width option:
  \blank[width=4.8\linewidth,linespread=1.5]{}
 \end{beispiel}
 
-\subsubsection{Vertical Space for answers}\secidx[vertical space]{Blanks}
+\subsection{Vertical Space for answers}\secidx[vertical space]{Blanks}
 \noindent\sinceversion{0.3}When you're creating an exam you might want to add some
 vertical space where the students can write down their answers. While you can
 always use \cmd*{vspace} this is not always handy when the space left on the
@@ -1657,6 +1523,16 @@ heading style than the ones available.
 Of you use the option \key{load-headings} each of the following instances is
 available through the option \key{headings}{<instance>}.
 
+The following examples use a sample text defined as follows:
+\begin{beispiel}[code only]
+ \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}
+\end{beispiel}
+\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}
+
 \subsubsection{The `block' Instance}
 \begin{beispiel}[code only]
  \DeclareInstance{exsheets-heading}{block}{default}
@@ -1787,6 +1663,7 @@ available through the option \key{headings}{<instance>}.
  A `block-nr' heading. \sample
 \end{question}
 
+\newpage% FIXME
 \subsubsection{The `block-nr-wp' Instance}
 \begin{beispiel}[code only]
  \DeclareInstance{exsheets-heading}{block-nr-wp}{default}
@@ -1802,7 +1679,6 @@ available through the option \key{headings}{<instance>}.
  A `block-nr-wp' heading. \sample
 \end{question}
 
-\newpage% FIXME
 \subsubsection{The `runin-rev' Instance}
 \begin{beispiel}[code only]
  \DeclareInstance{exsheets-heading}{runin-rev}{default}
@@ -1844,7 +1720,6 @@ available through the option \key{headings}{<instance>}.
  A `runin-wp' heading. \sample
 \end{question}
 
-\newpage% FIXME
 \subsubsection{The `runin-wp-rev' Instance}
 \begin{beispiel}[code only]
  \DeclareInstance{exsheets-heading}{runin-wp-rev}{default}
@@ -1919,6 +1794,7 @@ available through the option \key{headings}{<instance>}.
  A `runin-nr-wp' heading. \sample
 \end{question}
 
+\newpage% FIXME
 \subsubsection{The `inline' Instance}
 \sinceversion{0.5}
 \begin{beispiel}[code only]
@@ -1966,6 +1842,7 @@ Text before
 \end{question}
  Text after
 
+\newpage% FIXME
 \subsubsection{The `inline-nr' Instance}
 \sinceversion{0.5}
 \begin{beispiel}[code only]
@@ -2127,9 +2004,271 @@ Text before
 \end{question}
 \secidx*{The `exsheets-headings' Object}
 
-\subsection{The \code{exsheets-tasks} Object}\label{sec:exsheets-tasks}
-\secidx{The `exsheets-tasks' Object}
-The second object that's defined by \ExSheets is the `exsheets-tasks' object.
+\subsection{Load Custom Configurations}\secidx{Custom Configurations}
+If you have custom configurations you want to be loaded automatically then save
+them in a file \code{exsheets\_configurations.cfg}. If this file is present it
+will be loaded \cmd*{AtBeginDocument}.
+\secidx*{Custom Configurations}
+\secidx*{\ExSheets}[ExSheets]
+\SetupExSheets{headings=block}
+
+\part{The \Tasks package (\tasksversion)}\label{part:tasks}
+\secidx{\Tasks}[tasks]
+\section{Motivation}\secidx[Motivation]{\Tasks}[tasks]
+\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
+standalone 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 better off using traditional
+\LaTeX{} lists and the \paket{enumitem} package for customization.
+
+\section{Requirements}\secidx[Requirements]{\Tasks}[tasks]
+\Tasks requires packages \paket{l3kernel} ,\paket{xparse}, \paket{l3keys2e},
+\paket{epic}, \paket*{cntformats}\footnote{Part of the \ExSheets bundle, see
+part~\ref{part:cntformats}}, \paket{xtemplate} and \paket{environ}.
+
+\section{How it works}
+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}[<options>]{\unskip\da{<num of columns>} \cmd{task}\ldots}
+\end{beschreibung}
+Let's see an example:
+\begin{beispiel}[code only]
+ 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 \ma{<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}
+ 
+\section{Available Options}\secidx[Options]{\Tasks}[tasks]\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{label}{<label specs>}\Default{}
+   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-width}{<dim>}\Default{3ex}
+   Sets the width of the item labels.
+ \Option{label-offset}{<dim>}\Default{1ex}
+   \sinceversion{0.7}Sets the offset, i.e., the distance between label and item.
+ \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{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}[label=(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}[label=(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:
+\begin{beispiel}
+ % since settings are local the following ones will be lost
+ % outside this example; see the appendix how the solution
+ % appears there
+ \settasks{label=qu.tsk,label-width=5ex}
+ \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}
+
+\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]{\Tasks}[tasks]
+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}
+
+\section{New Tasks}\secidx[Own Environments]{\Tasks}[tasks]
+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}.
+\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]{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}}
+ \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}
+
+\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.
 
@@ -2139,14 +2278,15 @@ of the `default' template. The following subsections will give some examples
 of their usage.
 
 \begin{beispiel}[code only]
- \DeclareTemplateInterface{exsheets-tasks}{default}{3}
+ \DeclareTemplateInterface{tasks}{default}{3}
   {
     % option        : type      = default
-    enumerate       : boolean   = true           ,
-    label           : tokenlist                  ,
-    indent          : length    = 2.5em          ,
-    label-format    : tokenlist = tsk[a])        ,
-    label-width     : length    = 3ex            ,
+    enumerate       : boolean   = true    ,
+    label           : tokenlist           ,
+    indent          : length    = 2.5em   ,
+    label-format    : tokenlist = tsk[a]) ,
+    label-width     : length    = 3ex     ,
+    label-offset    : length    = 1ex     ,
     after-item-skip : skip      = 1ex plus 1ex minus 1ex
   }
 \end{beispiel}
@@ -2155,29 +2295,23 @@ of their usage.
 This is rather brief this time:
 \begin{beispiel}[code only]
  % ALPHABETIZE: a) b) c)
- \DeclareInstance{exsheets-tasks}{alphabetize}{default}{}
+ \DeclareInstance{tasks}{alphabetize}{default}{}
  % available when `load-tasks=true':
  % ITEMIZE:
- \DeclareInstance{exsheets-tasks}{itemize}{default}
+ \DeclareInstance{tasks}{itemize}{default}
    { enumerate    = false }
  % ENUMERATE:
- \DeclareInstance{exsheets-tasks}{enumerate}{default}
+ \DeclareInstance{tasks}{enumerate}{default}
    { label-format = tsk. }
  % MULTIPLECHOICE:
- \DeclareInstance{exsheets-tasks}{multiplechoice}{default}
+ \DeclareInstance{tasks}{multiplechoice}{default}
    {
      enumerate    = false       ,
      label        = \choicebox  ,
    }
 \end{beispiel}
-\secidx*{The `exsheets-tasks' Object}
-
-\subsection{Load Custom Configurations}\secidx{Custom Configurations}
-If you have custom configurations you want to be loaded automatically then save
-them in a file \code{exsheets\_configurations.cfg}. If this file is present it
-will be loaded \cmd*{AtBeginDocument}.
-\secidx*{Custom Configurations}
-\secidx*{\ExSheets}[ExSheets]
+\secidx*{The `tasks' Object}
+\secidx*{\Tasks}[tasks]
 
 \part{The \translations package (\trnsltversion)}
 \label{part:translations}\secidx{\translations}[translations]
@@ -2188,6 +2322,9 @@ need whatsoever for this package as \paket*{translator} from the \paket{beamer}
 bundle provides all the functionality \translations does (except for:
 \paket{translator}'s \cmd{translate} isn't expandable, \cmd{GetTranslation} is.).
 
+\section{Requirements}\secidx[Requirements]{\translations}[translations]
+\translations requires the \paket{etoolbox} package.
+
 \section{Usage}\secidx[Usage]{\translations}[translations]
 These are the commands provided by \translations:
 \begin{beschreibung}
@@ -2295,6 +2432,9 @@ does not use \cmd*{the<counter>} nor is it affected by the redefinition of them.
 This package is aimed at package or class authors and probably not very useful
 for document authors.
 
+\section{Requirements}\secidx[Requirements]{\cntformats}[cntformats]
+\cntformats requires the \paket{etoolbox} package.
+
 \section{Example}\secidx[Example]{\cntformats}[cntformats]
 A use case typically looks as follows:
 \begin{beispiel}
@@ -2306,7 +2446,7 @@ for what will be called \emph{pattern}. The keys for the counters can have optio
 arguments that specify the format:
 \begin{beispiel}
  \stepcounter{subsection}
- \ReadCounterPattern{se[A](sse[r])}
+ \ReadCounterPattern{se[R](sse[a])}
 \end{beispiel}
 \code{A} stands for \cmd{Alph} and \code{r} for \cmd{roman}. A complete list can
 be found in table~\ref{tab:predefined:formats} on page~\pageref{tab:predefined:formats}.
@@ -2443,9 +2583,7 @@ can add own formats.
 \begin{beispiel}
  % preamble
  % \usepackage{alphalph}
- % \makeatletter
- % \NewPatternFormat{aa}{\alphalph@alph}
- % \makeatother
+ % \NewPatternFormat{aa}{\alphalph}
  \ReadCounterPattern{se[aa]}
 \end{beispiel}
 \secidx*{\cntformats}[cntformats]
-- 
cgit v1.2.3

