exsheets (10mar13)

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

3 files changed, 188 insertions, 125 deletions

diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README
index a493117fefd..180c9f30362 100644
--- a/Master/texmf-dist/doc/latex/exsheets/README
+++ b/Master/texmf-dist/doc/latex/exsheets/README
@@ -1,10 +1,10 @@
 --------------------------------------------------------------------------
-EXSHEETS v0.7b - 2013/02/17
+EXSHEETS v0.8 - 2013/03/10
 
 bundled packages:
 the EXSHEETS package
   Yet another package for the creation of exercise sheets
-the TRANSLATIONS package v0.6
+the TRANSLATIONS package v0.8
   a simple translator
 the CNTFORMATS package v0.4
   A different way to read counters.
diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf
index 469aa546192..6cdfb667e84 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 e5e9ce18ae7..82ecb068e62 100644
--- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
+++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex
@@ -96,14 +96,15 @@
   acs, addpoints,
   blank, bigstar, bottomrule,
   checkedchoicebox, choice, choicebox, citetitle, cmd, color, correct,
-  DeclareInstance, DeclareTemplateInterface, DeclareQuestionProperty,
-    DebugExSheets,
-  endspacing, examspace, ForEachQuestion, GetQuestionProperty, grade,
-    includequestions, iflastquestion, lastvariant, midrule, NewQuSolPair,
-    numberofquestions,
+  DebugExSheets, DeclareInstance, DeclareQuestionClass, DeclareQuestionProperty,
+    DeclareTemplateInterface,
+  endspacing, examspace, ForEachQuestion,
+  GetQuestionProperty, grade,
+  includequestions, iflastquestion,
+  lastvariant, midrule, NewQuSolPair, numberofquestions,
   points, PrintIfIncludeActiveF, PrintIfIncludeActiveT, PrintIfIncludeActiveTF,
     printsolutions, PrintSolutionsF, PrintSolutionsTF, PrintSolutionsT,
-  QuestionNumber, RenewQuSolPair, rightarrow,
+  questionsincludedlast, QuestionNumber, RenewQuSolPair, rightarrow,
   s, sample, setlength, SetQuestionProperties, SetupExSheets, SetVariations,
     spacing, square, sumpoints,
   tabcolsep, textcite, textcolor, toprule, totalpoints,
@@ -114,8 +115,8 @@
 \newcommand*\translations{{\scshape\textcolor{main}{translations}}\xspace}
 \addcmds{
   cuisine,
-  DeclareLanguage, DeclareLanguageAlias, DeclareLanguageDialect,
-    DeclareTranslation,
+  DeclareDictTranslation, DeclareLanguage, DeclareLanguageAlias,
+    DeclareLanguageDialect, DeclareTranslation,
   GetTranslation, GetTranslationFor,
   kitchen,
   LoadDictionary, LoadDictionaryFor,
@@ -227,6 +228,7 @@
 
 % ----------------------------------------------------------------------------
 % example definitions that have to be done in the preamble:
+\DeclareQuestionClass{difficulty}{difficulties}
 \DeclareQuestionProperty{notes}
 \DeclareQuestionProperty{reference}
 \DeclareQuestionProperty{topic}
@@ -310,14 +312,14 @@
 \TitlePicture{%
   \parbox{.8\linewidth}{%
     \ExSheets provides means to create exercises or questions and their
-    corresponding solutions. The questions can be divided into classes and/or
-    topics and can be printed selectively. Meta-data to questions can be added
-    and recovered.\par
-   The solutions may be printed where they are, can be collected and printed at
-   a later point in the document alltogether or section-wise or selectively by
-   \acs{id}.\par
-   \ExSheets provides a comprehensive interface for styling the headings of
-   questions and solutions.}}
+    corresponding solutions. The questions can be divided into classes and can
+    be printed selectively. Meta-data to questions can be added and recovered.
+    \par
+    The solutions may be printed where they are, can be collected and printed at
+    a later point in the document alltogether or section-wise or selectively by
+    \acs{id}.\par
+    \ExSheets provides a comprehensive interface for styling the headings of
+    questions and solutions.}}
 
 \begin{document}
 
@@ -382,6 +384,9 @@ described in part~\ref{part:translations} and \cntformats in part~\ref{part:cntf
 These packages provide functionality that is used by \ExSheets. They can, however,
 be used independently from \ExSheets.
 
+The packages \translations and \cntformats both aren't really useful on a
+user-level but maybe for package writers.
+
 \section{Installation}\secidx[Installation]{Preliminary}
 If you install \ExSheets manually beware to put the files
 \begin{itemize}
@@ -616,10 +621,10 @@ The \code{question} environment takes one or more of the following options:
 
 The difference between \key{print} and \key{use} lies behind the scenes: with
 \key{print}{false} the question is not printed, but it still gets an individual
-ID, is numbered, and a possible solution is saved. This is for example useful
+\ac{id}, is numbered, and a possible solution is saved. This is for example useful
 when you want to print a sample solution for an exam. With \key{use}{false} it
-is fully discarded which means it is not accessible through an \acs{id} and a possible
-solution will not be saved.
+is fully discarded which means it is not accessible through an \acs{id} and a
+possible solution will not be saved.
 \secidx*{questions}
 
 \subsection{The \code{solution} Environment}\secidx{solutions}
@@ -959,13 +964,13 @@ 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}.
 
-\subsection{Print by \texorpdfstring{\acs{id}}{ID}}\label{ssec:ids}\secidx[print!by ID]{solutions}
+\subsection{Print by \acs{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:
 \begin{beschreibung}
  \Befehl{DebugExSheets}{true|false}
- \Befehl{CurrentQuestionID}\sinceversion{0.4a}\newline
+ \Befehl{CurrentQuestionID}\newline\sinceversion{0.4a}%
    expands to the current question \acs{id} (after two expansions).
 \end{beschreibung}
 Let's create some more questions and take a look what this command does:
@@ -1000,7 +1005,9 @@ order given you can use the option
    Sort solutions given by \acs{id} or don't.
 \end{beschreibung}
 
-\section{Using Classes}\label{sec:classes}\secidx{Classes}
+\section{Dividing Questions into Classes}\label{sec:dividing-concepts}
+\subsection{Using Classes}\label{sec:classes}\secidx{Classes}
+\secidx[Classes]{Dividing Concepts}
 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.
@@ -1010,15 +1017,15 @@ and then tell \ExSheets only to use one ore more specific classes.
    are printed and have their solutions saved.
 \end{beschreibung}
 \begin{beispiel}
- \SetupExSheets{use-classes={easy,hard}}
- \begin{question}[class=easy]
-  This one's easy.
+ \SetupExSheets{use-classes={A,C}}
+ \begin{question}[class=A]
+  Belonging to class A.
  \end{question}
- \begin{question}[class=middle]
-  This one's a little bit harder.
+ \begin{question}[class=B]
+  Belonging to class B.
  \end{question}
- \begin{question}[class=hard]
-  Let's see if you can solve this one!
+ \begin{question}[class=C]
+  Belonging to class C!
  \end{question}
 \end{beispiel}
 Questions of classes that are not used are fully discarded. \emph{This also means
@@ -1028,7 +1035,8 @@ that questions that don't have a class assigned are discarded.}
  \bool_set_false:N \g__exsheets_use_classes_bool
 \ExplSyntaxOff
 
-\section{Using Topics}\label{sec:topics}\secidx{Topics}
+\subsection{Using Topics}\label{sec:topics}\secidx{Topics}
+\secidx[Topics]{Dividing Concepts}
 Similarly to classes one can assign topics to questions. The usage is practically
 identical, the semantic meaning is different.
 \begin{beschreibung}
@@ -1058,90 +1066,45 @@ supported yet.
  \bool_set_false:N \g__exsheets_use_topics_bool
 \ExplSyntaxOff
 
-\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
-different but only small details, the numbers in a maths exam, say. For this
-purpose \ExSheets provides the following commands:
+\subsection{Own Dividing Concepts}\secidx{Dividing Concepts}
+\noindent\sinceversion{0.8}Actually both classes and topics are introduced into
+\ExSheets internally this way:
+\begin{beispiel}[code only]
+ \DeclareQuestionClass{class}{classes}
+ \DeclareQuestionClass{topic}{topics}
+\end{beispiel}
+which means you can do the same introducing your own dividing concepts.
 \begin{beschreibung}
- \Befehl{SetVariations}{<num>}\newline
-   Set the number of different variants. This will determine how many arguments
-   the command \cmd*{vary} will get. \code{<num>} must at least be \code{2} and
-   is initially set to \code{2}.
- \Befehl{variant}{<num>}\newline
-   Choose the active variant. The argument must be a number between \code{1}
-   and the number set with \cmd*{SetVariations}. Initially set to \code{1}.
- \Befehl{vary}{<variant 1>}\ma{<variant 2>}\newline
-   This command is the one actually used in the document. It has a number of
-   required arguments equal to the number set with \cmd*{SetVariations}. All of
-   its arguments are discarded except the one specified with \cmd*{variant}.
- \Befehl{lastvariant}\newline% TODO: richtige version einfügen!
-   \sinceversion{0.7b}Each time \cmd{vary} is called it stores the value it
-   chose in \cmd{lastversion}. This might be convenient to use if one
-   otherwise would have to repeatedly write the same \cmd{vary}.
+ \Befehl{DeclareQuestionClass}{<singular name>}\ma{<plural name>}\newline
+   Introduces a new dividing concept and defines both new options for the
+   \code{question} environment and new global options.
 \end{beschreibung}
 
-\begin{beispiel}
- \SetVariations{6}%
- \variant{6}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
- \variant{1}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
- \variant{5}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
- \variant{2}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
- \variant{4}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
- \variant{3}\vary{A}{B}{C}{D}{E}{F}
- (last variant: \lastvariant)
+For example you could decide you want to group your questions according to their
+difficulty. You could place the following line in your preamble:
+\begin{beispiel}[code only]
+ \DeclareQuestionSubdivision{difficulty}{difficulties}
 \end{beispiel}
-\secidx*{Variations}
-
-\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
-that might be. You could do something like this to present your grading decisions
-for the exam:
+This would define an option \key{use-difficulties} analogous to \key{use-classes}
+and \key{use-topics}. It would also define an option \key{difficulty} for the
+\code{question} environment. This means you could now do something like the
+following:
 \begin{beispiel}
- % preamble:
- % \DeclareRelGrades{
- %   1     = 1 ,
- %   {1,5} = .9167 ,
- %   2     = .8333 ,
- %   {2,5} = .75 ,
- %   3     = .6667 ,
- %   {3,5} = .5833 ,
- %   4     = .5
- % }
- \small\setlength\tabcolsep{2pt}
- \begin{tabular}{r|*8c}
-  Punkte
-    & $\grade*{1}$      & $\le\grade*{1}$ & $\le\grade*{1,5}$ & $\le\grade*{2}$
-    & $\le\grade*{2,5}$ & $\le\grade*{3}$ & $\le\grade*{3,5}$ & $<\grade*{4}$ \\
-  Note
-    & 1 & 1--2 & 2 & 2--3 & 3 & 3--4 & 4 & 5
- \end{tabular}
+ \SetupExSheets{use-difficulties={easy,hard}}
+ \begin{question}[difficulty=easy]
+  An easy question.
+ \end{question}
+ \begin{question}[difficulty=medium]
+  This one's a bit harder.
+ \end{question}
+ \begin{question}[difficulty=hard]
+  Now let's see if you can solve this one.
+ \end{question}
 \end{beispiel}
-
-These are the available commands and options:
-\begin{beschreibung}
- \Befehl{DeclareRelGrades}{<grade>=<num>,...}\newline
-   This command is used to define grades and assign the percentage of total
-   points to them.
- \Befehl{grade}*{<grade>}\newline
-   Gives the number of points corresponding to a grade depending on the value
-   of \cmd{pointssum} with or without (starred version) ``unit''.
- \Option[grades]{round}{<num>}\Default{0}
-   The number of decimals the points of a grade are rounded to. This doesn't apply
-   to the maximum number of points if the rounded number would be bigger than the
-   actual sum.
- \Option[grades]{half}{\default{true}|false}\Default{false}
-   If set to \code{true} points are rounded either to full or to half points.
-\end{beschreibung}
-\secidx*{Grade Distribution}
+\secidx*{Dividing Concepts}
+\ExplSyntaxOn
+ \bool_set_false:N \g__exsheets_use_difficulties_bool
+\ExplSyntaxOff
 
 \section{Adding and Using Additional Information to Questions}\label{sec:additional_info}
 \secidx{Additional Information to Questions}
@@ -1228,6 +1191,10 @@ It is now possible to recover these values later:
 \code{ref} and \code{pageref} are predefined which will call the corresponding
 \cmd*{ref} or \cmd*{pageref}, respectively.
 
+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.
+
 \sinceversion{0.3}There are additional commands that might prove useful:
 \begin{beschreibung}
  \Befehl{ForEachQuestion}{<code to be executed for each used question>}\newline
@@ -1269,6 +1236,91 @@ For four questions the table now would look similar to figure~\ref{fig:grading-t
 \end{figure}
 \secidx*{Additional Information to Questions}
 
+\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
+different but only small details, the numbers in a maths exam, say. For this
+purpose \ExSheets provides the following commands:
+\begin{beschreibung}
+ \Befehl{SetVariations}{<num>}\newline
+   Set the number of different variants. This will determine how many arguments
+   the command \cmd*{vary} will get. \code{<num>} must at least be \code{2} and
+   is initially set to \code{2}.
+ \Befehl{variant}{<num>}\newline
+   Choose the active variant. The argument must be a number between \code{1}
+   and the number set with \cmd*{SetVariations}. Initially set to \code{1}.
+ \Befehl{vary}{<variant 1>}\ma{<variant 2>}\newline
+   This command is the one actually used in the document. It has a number of
+   required arguments equal to the number set with \cmd*{SetVariations}. All of
+   its arguments are discarded except the one specified with \cmd*{variant}.
+ \Befehl{lastvariant}\newline% TODO: richtige version einfügen!
+   \sinceversion{0.7b}Each time \cmd{vary} is called it stores the value it
+   chose in \cmd{lastversion}. This might be convenient to use if one
+   otherwise would have to repeatedly write the same \cmd{vary}.
+\end{beschreibung}
+
+\begin{beispiel}
+ \SetVariations{6}%
+ \variant{6}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{1}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{5}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{2}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{4}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{3}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+\end{beispiel}
+\secidx*{Variations}
+
+\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
+that might be. You could do something like this to present your grading decisions
+for the exam:
+\begin{beispiel}
+ % preamble:
+ % \DeclareRelGrades{
+ %   1     = 1 ,
+ %   {1,5} = .9167 ,
+ %   2     = .8333 ,
+ %   {2,5} = .75 ,
+ %   3     = .6667 ,
+ %   {3,5} = .5833 ,
+ %   4     = .5
+ % }
+ \small\setlength\tabcolsep{2pt}
+ \begin{tabular}{r|*8c}
+  Punkte
+    & $\grade*{1}$      & $\le\grade*{1}$ & $\le\grade*{1,5}$ & $\le\grade*{2}$
+    & $\le\grade*{2,5}$ & $\le\grade*{3}$ & $\le\grade*{3,5}$ & $<\grade*{4}$ \\
+  Note
+    & 1 & 1--2 & 2 & 2--3 & 3 & 3--4 & 4 & 5
+ \end{tabular}
+\end{beispiel}
+
+These are the available commands and options:
+\begin{beschreibung}
+ \Befehl{DeclareRelGrades}{<grade>=<num>,...}\newline
+   This command is used to define grades and assign the percentage of total
+   points to them.
+ \Befehl{grade}*{<grade>}\newline
+   Gives the number of points corresponding to a grade depending on the value
+   of \cmd{pointssum} with or without (starred version) ``unit''.
+ \Option[grades]{round}{<num>}\Default{0}
+   The number of decimals the points of a grade are rounded to. This doesn't apply
+   to the maximum number of points if the rounded number would be bigger than the
+   actual sum.
+ \Option[grades]{half}{\default{true}|false}\Default{false}
+   If set to \code{true} points are rounded either to full or to half points.
+\end{beschreibung}
+\secidx*{Grade Distribution}
+
 \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
@@ -1308,6 +1360,9 @@ are however the following options:
  \Option[include]{random}{<num>}\Default{}
    Includes \code{<num>} randomly selected questions. This option uses the
    \paket{pgfcore} package to create the pseudo-random numbers.
+ \Option[include]{exclude}{<list of IDs>}\Default{}
+   Questions who's \acp{id} are specified here are \emph{not} included. This
+   option can be combined with the \key{random} option.
 \end{beschreibung}
 The usage should be self-explainable:
 \begin{beispiel}[code only]
@@ -1319,19 +1374,26 @@ The usage should be self-explainable:
 In order to be able to select the questions \ExSheets needs to \cmd{input} the
 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:
+\emph{not} part of a question or solution is also input twice. Either don't put
+anything else into the file or use one of the following commands for control:
 \begin{beschreibung}
  \Befehl{PrintIfIncludeActiveTF}\ma{<true code>}\ma{<false code>}
  \Befehl{PrintIfIncludeActiveT}\ma{<true code>}
  \Befehl{PrintIfIncludeActiveF}\ma{<false code>}
 \end{beschreibung}
 
-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. I'm still not sure this is a feature
-or a bug\ldots
+The selection can be refined further by selecting questions belonging to a
+specific class of questions (see section~\ref{sec:dividing-concepts}) before
+using \cmd{includequestions}.
+
+\sinceversion{0.8}After you've used \cmd{includequestions} the \acp{id} of the
+included questions is available as an unordered comma separated list in the
+following macro:
+\begin{beschreibung}
+ \Befehl{questionsincludedlast}\newline
+   Unordered comma separated list of question \acp{id} included with the last
+   usage of \cmd{includequestions}.
+\end{beschreibung}
 \secidx*{Include from External Files}
 
 \section{Own Question/Solution Pairs}
@@ -2035,7 +2097,7 @@ 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
+primarily is for. If you don't need this feature you're better off using traditional
 \LaTeX{} lists and the \paket{enumitem} package for customization.
 
 \section{Requirements}\secidx[Requirements]{\Tasks}[tasks]
@@ -2081,7 +2143,7 @@ Some text before the list.
 \end{tasks}
 And also some text after it.
  
-The environment takes the optional argument \ma{<num of columns>} with which the
+The environment takes the optional argument \da{<num of columns>} with which the
 number of columns used by the environment is specified.
 \begin{beispiel}[code only]
  \begin{tasks}(2)
@@ -2275,7 +2337,7 @@ The last example shows you two additional commands:
 \end{beschreibung}
 
 \section{Styling \Tasks}
-Equivalent to the styling of \ExSheets \Tasks uses \paket{xtemplate} to
+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}
@@ -2387,6 +2449,7 @@ These are the commands provided by \translations:
    specified language.
  \Befehl{LoadDictionaryFor}{<lang>}\ma{<name>}\newline
    Loads a file named \code{<name>-<lang>.trsl}.
+ \Befehl{DeclareDictTranslation}{<key>}\ma{<translation>}% TODO: beschreibung
 \end{beschreibung}
 Quite a number of languages already are defined, either directly or via an alias.
 So, before you define a language you should take a look in \code{translations.sty}
@@ -2423,11 +2486,11 @@ There is also preliminary support for dialects:
 A typical dictionary file should look as follows:
 \begin{beispiel}[code only]
  % this is file housing-german.trsl
- \ProvideDictionaryFor{german}{housing}[<version info>]
- \DeclareTranslation{German}{kitchen (housing)}{K\"uche}
- \DeclareTranslation{German}{bathroom (housing)}{Bad}
- \DeclareTranslation{German}{living room (housing)}{Wohnzimmer}
- \DeclareTranslation{German}{bedroom (housing)}{Schlafzimmer}
+ \ProvideDictionaryFor{German}{housing}[<version info>]
+ \DeclareDictTranslation{kitchen (housing)}{K\"uche}
+ \DeclareDictTranslation{bathroom (housing)}{Bad}
+ \DeclareDictTranslation{living room (housing)}{Wohnzimmer}
+ \DeclareDictTranslation{bedroom (housing)}{Schlafzimmer}
  ...
  \endinput
 \end{beispiel}