exsheets (8nov12)

git-svn-id: svn://tug.org/texlive/trunk@28212 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 147 insertions, 71 deletions

diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README
index 74803b4238a..0a082e1f372 100644
--- a/Master/texmf-dist/doc/latex/exsheets/README
+++ b/Master/texmf-dist/doc/latex/exsheets/README
@@ -1,5 +1,5 @@
 --------------------------------------------------------------------------
-EXSHEETS v0.3 - 2012/10/23
+EXSHEETS v0.4 - 2012/11/08
 
 bundled packages:
 the EXSHEETS package
diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf
index 502693a22cf..16fb782c201 100644
--- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf
+++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf
diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
index e9fb998099b..1c7fdfe63f1 100644
--- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
+++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
@@ -58,14 +58,13 @@
     skipbelow        = .6\baselineskip plus .5ex minus .5ex ,
     skipabove        = .6\baselineskip plus .5ex minus .5ex ,
     innerleftmargin  = 1.5em ,
-    innerrightmargin = 2.5em ,
-    ignorelastdescenders
+    innerrightmargin = 2.5em
   } ,
   gobble   = 1
 }
 \cnpkgusecolorscheme{friendly}
 
-\usepackage{embrac}[2012/06/29]
+\usepackage[biblatex]{embrac}[2012/06/29]
   \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
   \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
 \usepackage{microtype}
@@ -86,16 +85,17 @@
 % code examples
 % ExSheets:
 \addcmds{
-  acs, addpoints, blank, bigstar, bottomrule, citetitle, cmd, color,
+  acs, addpoints, blank, bigstar, bottomrule, checkedchoicebox, choice, choicebox,
+  citetitle, cmd, color, correct,
   DeclareInstance, DeclareTemplateInterface, DeclareQuestionProperty,
   DebugExSheets, endspacing, examspace, ForEachQuestion, GetQuestionProperty,
   grade, includequestions, iflastquestion,
-  midrule, NewQuSolPair, numberofquestions, points, PrintIfIncludeActiveF,
-  PrintIfIncludeActiveT, PrintIfIncludeActiveTF, printsolutions,
-  PrintSolutionsTF,
-  QuestionNumber, RenewQuSolPair, s, sample, setlength, SetQuestionProperties,
-  SetupExSheets, spacing, square, sumpoints, tabcolsep, task, textcite, textcolor,
-  toprule, totalpoints
+  midrule, NewQuSolPair, NewTasks, numberofquestions, points,
+  PrintIfIncludeActiveF, PrintIfIncludeActiveT, PrintIfIncludeActiveTF,
+  printsolutions, PrintSolutionsF, PrintSolutionsTF, PrintSolutionsT,
+  QuestionNumber, RenewQuSolPair, rightarrow, s, sample, setlength,
+  SetQuestionProperties, SetupExSheets, spacing, square, sumpoints,
+  tabcolsep, task, textcite, textcolor, toprule, totalpoints
 }
 
 % translations:
@@ -215,8 +215,11 @@
 
 \usepackage{amssymb}
 \NewQuSolPair
-  {question*}[name=\llap{$\bigstar$\space}Bonus Question]
-  {solution*}[name=\llap{$\bigstar$\space}Solution]
+  {question*}[name=\protect\llap{$\bigstar$\space}Bonus Question]
+  {solution*}[name=\protect\llap{$\bigstar$\space}Solution]
+
+\NewTasks[style=multiplechoice]{choices}[\choice](3)
+\newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
 
 \DeclareTranslation{English}{Kueche}{kitchen}
 \DeclareTranslation{German}{Kueche}{K\"uche}
@@ -269,6 +272,8 @@
   \@esphack}
 \makeatother
 
+\pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}}
+
 % ----------------------------------------------------------------------------
 % title page
 \TitlePicture{%
@@ -287,7 +292,7 @@
 \part{Preliminary}\secidx{Preliminary}
 \section{Licence and Requirements}
 \secidx[Licence]{Preliminary}\secidx[Requirements]{Preliminary}
-\ExSheets is placed under the terms of the LaTeX Project Public License,
+\ExSheets is placed under the terms of the \LaTeX{} Project Public License,
 version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}).
 It has the status ``maintained.''
 
@@ -498,7 +503,7 @@ argument.
  \end{question}
 \end{beispiel}
 
-\sinceversion{3.0}On additional thing: you might want to define custom
+\sinceversion{0.3}On additional thing: you might want to define custom
 commands that should behave differently if they're inside or outside of the
 \code{question} environment. In this case you can use these commands:
 \begin{beschreibung}
@@ -618,6 +623,15 @@ of the respective counter. \code{1}: \cmd{arabic}, \code{a}: \cmd{alph}, \code{A
   A question with a differently formatted number.
  \end{question}
 \end{beispiel}
+Since the strings associated with the counters are replaced one has to hide them
+if they are actually wanted in the counter format. The easiest way would to
+interrupt them by an empty group.
+\begin{beispiel}
+ \SetupExSheets{counter-format=s{}ection\,se~q{}uestion\,(qu[a])}
+ \begin{question}
+  A question with a yet differently formatted number.
+ \end{question}
+\end{beispiel}
 \secidx*{Setting the Counter}
 
 \subsubsection{Language Settings}\secidx{Language Settings}
@@ -714,7 +728,7 @@ You have two possibilities to display and count them:
 \begin{beschreibung}
  \Option[points]{name}{<name>}\Default{P.}
    Choose the ``unit'' for the points. If you like to differentiate between a
-   single point and more than one point you can give a plural ending seperated
+   single point and more than one point you can give a plural ending separated
    with a slash: \key{name}{point/s}. This sets also the name of the bonus points.
  \Option[points]{name-plural}{<plural form of name>}\Default{}
    Instead of forming the plural form with an ending to the singular form this
@@ -722,7 +736,7 @@ You have two possibilities to display and count them:
    the bonus points.
  \Option[points]{bonus-name}{<name>}\Default{P.}
    Choose the ``unit'' for the bonus points. If you like to differentiate between a
-   single point and more than one point you can give a plural ending seperated
+   single point and more than one point you can give a plural ending separated
    with a slash: \key{bonus-name}{point/s}.
  \Option[points]{bonus-plural}{<plural form of name>}\Default{}
    Instead of forming the plural form with an ending to the singular form this
@@ -1100,7 +1114,7 @@ It is now possible to recover these values later:
  \end{center}
 \end{beispiel}
 
-\sinceversion{3.0}There are additional commands that might prove useful:
+\sinceversion{0.3}There are additional commands that might prove useful:
 \begin{beschreibung}
  \Befehl{ForEachQuestion}{<code to be executed for each used question>}\newline
    Inside the argument one can refer to the \ac{id} of a question with \code{\#1}.
@@ -1124,7 +1138,7 @@ For example one could use these commands to create a grading table:
     \pointssum* \\ \hline
   Reached  &
     \ForEachQuestion{\iflastquestion{}{&}} & \\ \hline
-\end{tabular}
+ \end{tabular}
 \end{beispiel}
 For four questions the table now would look similar to figure~\ref{fig:grading-table}.
 
@@ -1210,7 +1224,7 @@ are included anyway. I'm still not sure this is a feature or a bug\ldots
 \secidx*{Include from External Files}
 
 \subsection{Own Question/Solution Pairs}
-\noindent\sinceversion{3.0}\ExSheets provides he possibility to create new
+\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*}
 environment pair for bonus questions. The following commands may be used in the
@@ -1229,8 +1243,8 @@ to define starred variants that add a star in the margin left to the title:
 \begin{beispiel}
  % preamble:
  % \NewQuSolPair
- %   {question*}[name=\llap{$\bigstar$\space}Bonus Question]
- %   {solution*}[name=\llap{$\bigstar$\space}Solution]
+ %   {question*}[name=\protect\llap{$\bigstar$\space}Bonus Question]
+ %   {solution*}[name=\protect\llap{$\bigstar$\space}Solution]
  \begin{question*}
   This is a bonus question.
  \end{question*}
@@ -1243,18 +1257,23 @@ standard \code{question} and \code{solution} environments.
 
 \subsection{The \code{tasks} Environment}\label{sec:tasks}\secidx{tasks}
 \subsubsection{How it works}
-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: the input syntax:
+\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, each ended by
- a semicolon}
+ \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\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
@@ -1263,9 +1282,9 @@ Let's use some sample text in the next few examples:
 \begin{beispiel}[below]
  Some text before the list.
  \begin{tasks}
-  \sample ;
-  \sample ;
-  \sample ;
+  \task \sample
+  \task \sample
+  \task \sample
  \end{tasks}
  And also some text after it.
 \end{beispiel}
@@ -1273,15 +1292,15 @@ 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}
-  \sample ;
-  \s\ \s ;
-  \s ;
-  \sample ;
-  \s\par\s ;
+  \task \sample
+  \task \s\ \s
+  \task \s
+  \task \sample
+  \task \s\par\s
  \end{tasks}
 \end{beispiel}
 
-\subsubsection{Available Options}\secidx[Options]{tasks}
+\subsubsection{Available Options}\secidx[Options]{tasks}\label{sssec:tasks:options}
 The environment has some options, namely these:
 \begin{beschreibung}
  \Option[tasks]{style}{<instance>}\Default{}
@@ -1293,20 +1312,24 @@ The environment has some options, namely these:
    \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{.33\cmd{baselineskip}}
+ \Option[tasks]{before-skip}{<skip>}\Default{0pt}
    Sets the skip before the list.
- \Option[tasks]{after-skip}{<skip>}\Default{.33\cmd{baselineskip}}
+ \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}
-  \sample ;
-  \s\ \s ;
-  \s ;
-  \sample ;
-  \s\par\s ;
+  \task \sample
+  \task \s\ \s
+  \task \s
+  \task \sample
+  \task \s\par\s
  \end{tasks}
 \end{beispiel}
 
@@ -1316,15 +1339,15 @@ Let's use it inside a question:
  \begin{question}[type=exam]{4}
   I have these two tasks for you. Shall we begin?
   \begin{tasks}{2}
-   The first task: easy! ;
-   The second task: even more so! ;
+   \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}
-   This is the first solution. Told you it was easy. ;
-   This is the second solution. And of course you knew that! ;
+   \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}
@@ -1339,38 +1362,87 @@ additional instances for the \code{tasks} are available:
 \end{description}
 \begin{beispiel}
  \begin{tasks}[style=itemize]{2}
-  that's just how\ldots ;
-  \ldots we expected ;
+  \task that's just how\ldots
+  \task \ldots we expected
  \end{tasks}
  \begin{tasks}[style=enumerate]{2}
-  that's just how\ldots ;
-  \ldots we expected ;
+  \task that's just how\ldots
+  \task \ldots we expected
  \end{tasks}
  \begin{tasks}[style=multiplechoice]{2}
-  that's just how\ldots ;
-  \ldots we expected ;
+  \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
-\begin{beschreibung}
- \Befehl{task}{<label>}
-\end{beschreibung}
-in one of the tasks. This will temporarily overwrite the default label.
+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]
-  a standard item ;
-  another one ;
-  \task{+}a different one ;
-  and another one ;
+  \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}
-\noindent\changedversion{3.0}Both in exercise sheets and in exams it is sometimes
+\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]{}
 
@@ -1387,6 +1459,9 @@ The options are these:
 \begin{beschreibung}
  \Option[blank]{style}{line|wave|dline|dotted|dashed}\Default{line}
    The style of the line.
+ \Option[blank]{scale}{<num>}\Default{1}
+   Scales the width of the blank by factor \code{<num>} unless the width is
+   explicitly set.
  \Option[blank]{width}{<dim>}\Default{}
    The width of the line. If it is not used the width of the filled in text is used.
  \Option[blank]{linespread}{<num>}\Default{1}
@@ -1412,7 +1487,7 @@ A number of empty lines are easily created by setting the width option:
 \end{beispiel}
 
 \subsubsection{Vertical Space for answers}\secidx[vertical space]{Blanks}
-\noindent\sinceversion{3.0}When you're creating an exam you might want to add some
+\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
 page is less than you want. In this case it would be nice if a) there would be
@@ -1446,7 +1521,7 @@ and for the \code{tasks} environment.
 
 What this package doesn't provide is changing the background of questions or
 framing them. But this is easily possible using the \paket{mdframed} package
-and its \cmd*{surroundwithmdframed} copmmand.
+and its \cmd*{surroundwithmdframed} command.
 
 \subsection{The \code{exsheets-headings} Object}\label{sec:exsheets-headings}
 \secidx{The `exsheets-headings' Object}
@@ -1509,7 +1584,7 @@ the second) using the following syntax:
  join = coffin1[handle11,handle12]coffin2[handle21,handle22](x-offset,y-offset)
 \end{beispiel}
 The syntax for attaching (two become one, the first does \emph{not} extend its
-bounding box around the second) the syntax is the same.
+bounding box around the second) is the same.
 
 More on coffin handles is described in the documentation for the \paket{xcoffins}.
 Figure~\ref{fig:handles} briefly demonstrates the available handle pairs.
@@ -1739,6 +1814,7 @@ available through the option \key{headings}{<instance>}.
  A `runin-wp-rev' heading. \sample
 \end{question}
 
+\newpage
 \subsubsection{The `runin-nr' Instance}
 \begin{beispiel}[code only]
  \DeclareInstance{exsheets-heading}{runin-nr}{default}
@@ -1956,7 +2032,7 @@ of their usage.
     indent          : length    = 2.5em          ,
     label-format    : tokenlist = tsk[a])        ,
     label-width     : length    = 3ex            ,
-    after-item-skip : length    = 2ex
+    after-item-skip : skip      = 1ex plus 1ex minus 1ex
   }
 \end{beispiel}
 
@@ -2242,7 +2318,7 @@ can add own formats.
 \SetupExSheets{headings=block,solutions-totoc}
 \printsolutions
 
-{\EmbracOff\RaggedRight\printbibliography}
+\RaggedRight\printbibliography
 
 \setindexpreamble{Section titles are indicated \textbf{bold}, packages \textsf{sans
 serif}, commands \code{\textbackslash\textcolor{code}{brown}}, options \textcolor