exsheets (28jun14)

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

6 files changed, 87 insertions, 27 deletions

diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README
index 319d5e15641..b1408ac5818 100644
--- a/Master/texmf-dist/doc/latex/exsheets/README
+++ b/Master/texmf-dist/doc/latex/exsheets/README
@@ -1,7 +1,7 @@
 --------------------------------------------------------------------------
-EXSHEETS 2014/05/11
+EXSHEETS 2014/06/27
 bundled packages:
-the EXSHEETS package v0.13
+the EXSHEETS package v0.14
   Yet another package for the creation of exercise sheets
 the EXSHEETS-LISTINGS package v0.2
   Using listings in exsheets
diff --git a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf
index 5ce72181de8..8cf3a16ec5d 100644
--- a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf
+++ b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf
diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf
index 59593bf3880..191ab5488e5 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 ea18bc5f1a2..a96d6c2584c 100644
--- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
+++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
@@ -249,9 +249,9 @@
 \license
 
 \ExSheets\ loads and needs the following packages:
-\needpackage{l3kernel}~\cite{pkg:l3kernel}, \pkg{xparse}, \pkg{xtemplate},
-\pkg{l3keys2e}\footnote{all three \CTANurl{l3packages}}~\cite{pkg:l3packages},
-\pkg{l3sort}\footnote{\CTANurl{l3experimental}}~\cite{pkg:l3experimental},
+\needpackage{l3kernel}~\cite{bnd:l3kernel}, \pkg{xparse}, \pkg{xtemplate},
+\pkg{l3keys2e}\footnote{all three \CTANurl{l3packages}}~\cite{bnd:l3packages},
+\pkg{l3sort}\footnote{\CTANurl{l3experimental}}~\cite{bnd:l3experimental},
 \needpackage{xcolor}~\cite{pkg:xcolor}, \needpackage{ulem}~\cite{pkg:ulem},
 \needpackage{etoolbox}~\cite{pkg:etoolbox},
 \needpackage{environ}~\cite{pkg:environ}, and
@@ -261,7 +261,7 @@ calls \cs*{normalem} (from the \pkg{ulem} package).
 \section{Motivation}
 There are already quite a number of packages that allow the creation of
 exercise sheets or written exams.  Just to name the most common ones:
-\pkg{eqexam}~\cite{pkg:eqexam}, \pkg{exam}~\cite{pkg:exam},
+\pkg{eqexam}~\cite{pkg:eqexam}, \pkg{exam}~\cite{cls:exam},
 \pkg{examdesign}~\cite{pkg:examdesign}, \pkg{exercise}~\cite{pkg:exercise},
 \pkg{probsoln}~\cite{pkg:probsoln}, \pkg{answers}~\cite{pkg:answers},
 \pkg{esami}~\cite{pkg:esami}, \pkg{exsol}~\cite{pkg:exsol} (and many
@@ -316,9 +316,9 @@ documentation.  These packages provide functionality that is used by
 The package \cntformats\ is probably not really useful on a user-level but
 maybe for package writers.
 
-\changedversion{0.9i}\ExSheets\ used to bundle the \pkg{translations}
-package, too, but doesn't any more.  You can find the \pkg{translations}
-package as a package of it's own on the \ac{ctan}.
+\ExSheets\ used to bundle the \pkg{translations} package,
+too\changedversion{0.9i}, but doesn't any more.  You can find the
+\pkg{translations} package as a package of it's own on the \ac{ctan}.
 
 \section{Installation and Documentation}
 If you install \ExSheets\ manually beware to put the files
@@ -421,6 +421,23 @@ New options:
     section~\ref{sec:solutions-print-all}.
 \end{itemize}
 
+\subsection{Version 0.14}
+New options:
+\begin{itemize}
+  \item New option \option{pre-hook} to the \env{question} environment that
+    allows to add code directly before the question body, see
+    section~\ref{sec:opti-ques-envir}.
+  \item New option \option{post-hook} to the \env{question} environment that
+    allows to add code directly after the question body, see
+    section~\ref{sec:opti-ques-envir}.
+  \item New command \cs{ExSheetsHeading}.
+  \item New pre-defined question properties \code{question-body},
+    \code{bonus-points} and \code{counter}, see section
+    \ref{sec:additional_info}.
+  \item New option \option{save-to-aux}, see section
+    \ref{sec:additional_info}.
+\end{itemize}
+
 \section{Thanks}
 I need to thank the many users who gave me feedback so far!  For one thing
 this shows me that \ExSheets\ is useful to people.  It also led to many
@@ -636,6 +653,10 @@ The \env{question} environment takes one or more of the following options:
     section~\ref{sec:topics} for further information.
   \keybool{use}\Module{question}\Default{true}
     Discards the question.  Or not.
+  \keyval{pre-hook}{code}\Module{question}\Default
+    \sinceversion{0.14}Adds \meta{code} directly before the question body.
+  \keyval{pre-hook}{code}\Module{question}\Default
+    \sinceversion{0.14}Adds \meta{code} directly after the question body.
 \end{options}
 
 \begin{example}
@@ -1243,7 +1264,10 @@ say.  This is possible with the following commands:
  \bool_set_false:N \g__exsheets_use_difficulties_bool
 \ExplSyntaxOff
 
-\section{Adding and Using Additional Information to Questions}\label{sec:additional_info}
+\section{Adding and Using Additional Information to
+  Questions}\label{sec:additional_info}
+\subsection{Question Properties -- the Basics}
+
 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 possible with the following commands.  First the ones for saving:
@@ -1264,7 +1288,7 @@ Now the commands for recovering the properties:
   \expandable\command{GetQuestionProperty}[\marg{name}\marg{id}]
     Recover the property \meta{name} of the question with the \acs{id}
     \meta{id}.  Of course the property must have been declared before.  The
-    command is expandable.  Since\sinceversion{0.12} the properties of a
+    command is expandable.  Since\changedversion{0.12} the properties of a
     question are written to the \code{aux} file it is possible to retrieve
     them before the corresponding \env{question} environment has been used.
 \end{commands}
@@ -1327,30 +1351,65 @@ It is now possible to recover these values later:
   \end{center}
 \end{example}
 
-\sinceversion{0.7a}If you use the package option \option{auto-label} the
-properties \code{ref} and \code{pageref} are predefined which will call the
-corresponding \cs*{ref} or \cs*{pageref}, respectively.  Also see
-section~\ref{sec:auto-label-opti}.
+Please note that properties \emph{are not the same} as the dividing concepts
+explained in section~\ref{sec:dividing-concepts} although they may seem
+similar in meaning or even have the same name.
+
+When properties are set they are also written to the \code{aux} file which
+means they can be retrieved \emph{before} the corresponding question.  Of
+course this means that two compilation runs are necessary.
+
+\subsection{Pre-defined Properties}
+
+A few properties are already defined by \ExSheets:
+\begin{itemize}
+  \item \code{counter}:\sinceversion{0.14} this property holds the actual
+    question number formatted according to the formatting set with option
+    \option{counter-format}.
+  \item \code{subtitle}:\sinceversion{0.12} this property holds the subtitle
+    of the question if given.
+  \item \code{question-body}:\sinceversion{0.14} this property holds the body
+    of the corresponding \env{question} environment.  Unlike the other
+    properties it is per default \emph{not} written to the \code{aux} file.
+  \item \code{points}: this property holds the sum of points given to a
+    question.
+  \item \code{bonus-points}:\sinceversion{0.14} this property holds the sum of
+    bonus points given to a question.
+  \item \code{ref}:\sinceversion{0.7f} when the option \option{auto-label} is
+    used this property is defined and expands to the corresponding \cs*{ref}.
+    Also see section~\ref{sec:auto-label-opti}.
+  \item \code{page-ref}:\sinceversion{0.7f} when the option
+    \option{auto-label} is used this property is defined and expands to the
+    corresponding \cs*{pageref}.  Also see section~\ref{sec:auto-label-opti}.
+\end{itemize}
+
+There is one option affecting the property \code{question-body}:
+\begin{options}
+  \keybool{save-to-aux}\Module{question}\Default{false}
+    When set to \code{true} the property \code{question-body} is also written
+    to the \code{aux} file.
+\end{options}
 
-Please note that these properties \emph{are not the same} as the dividing
-concepts explained in section~\ref{sec:dividing-concepts} although they may
-seem similar in meaning or even have the same name.
+\subsection{Advanced Usage}
 
-\sinceversion{0.3}There are additional commands that might prove useful:
+There are additional commands\sinceversion{0.3} that might prove useful.  They
+allow advanced usage of defined properties.  Below an example is shown how
+they can be used to generate a grading table.
 \begin{commands}
   \command{ForEachQuestion}[\marg{code to be executed for each used question}]
-    Inside the argument one can refer to the \ac{id} of a question with
-    \code{\#1}.  Beware that this command only knows of questions used before
-    it is issued.
+    \changedversion{0.14}Inside the argument one can refer to the \ac{id} of a
+    question with \code{\#1}.  You can also refer to the number of the
+    question with \code{\#2}.  \emph{Number} means that if you \emph{use}
+    seven questions then those questions have numbers~1 to~7.
   \expandable\command{numberofquestions}
-    Returns the current number of used questions.  Beware that this command
-    only knows of questions used before it is issued.
+    \changedversion{0.14} returns the complete number of used questions.
   \expandable\command{iflastquestion}[\marg{true code}\marg{false code}]
     Although this command is available in the whole document it is only useful
     inside \cs{ForEachQuestion}.  It tells you if the end of the loop is
     reached or not.
 \end{commands}
-For example one could use these commands to create a grading table:
+
+One could use these commands to create a grading table, for instance:
 \begin{sourcecode}
   \begin{tabular}{|l|*{\numberofquestions}{c|}c|}\hline
     Question &
@@ -1380,8 +1439,9 @@ figure~\ref{fig:grading-table}.
 
 
 \section{Variations of an Exam}
-\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
+
+It is a quite common task\sinceversion{0.6} 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
 different but only small details, the numbers in a maths exam, say.  For this
 purpose \ExSheets\ provides the following commands:
diff --git a/Master/texmf-dist/doc/latex/exsheets/grading-table.pdf b/Master/texmf-dist/doc/latex/exsheets/grading-table.pdf
index ad2da7f271e..248ccb5dba7 100644
--- a/Master/texmf-dist/doc/latex/exsheets/grading-table.pdf
+++ b/Master/texmf-dist/doc/latex/exsheets/grading-table.pdf
diff --git a/Master/texmf-dist/doc/latex/exsheets/tasks_en.pdf b/Master/texmf-dist/doc/latex/exsheets/tasks_en.pdf
index e70bac5f399..671ff5e4f3b 100644
--- a/Master/texmf-dist/doc/latex/exsheets/tasks_en.pdf
+++ b/Master/texmf-dist/doc/latex/exsheets/tasks_en.pdf