From 6d44c638512eb736c41551c5887b4475a14935bf Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Thu, 15 Sep 2022 03:15:34 +0000
Subject: CTAN sync 202209150315

---
 .../contrib/stex/doc/packages/stex-problem.tex     | 97 ++++++++++++++++++++--
 1 file changed, 89 insertions(+), 8 deletions(-)

(limited to 'macros/latex/contrib/stex/doc/packages/stex-problem.tex')

diff --git a/macros/latex/contrib/stex/doc/packages/stex-problem.tex b/macros/latex/contrib/stex/doc/packages/stex-problem.tex
index a90c36412d..53316b28bc 100644
--- a/macros/latex/contrib/stex/doc/packages/stex-problem.tex
+++ b/macros/latex/contrib/stex/doc/packages/stex-problem.tex
@@ -1,4 +1,5 @@
-The \pkg{problem} package supplies an infrastructure that allows specify problem.  Problems
+\begin{sfragment}{Introduction}
+  The \pkg{problem} package supplies an infrastructure that allows specify problem.  Problems
 are text fragments that come with auxiliary functions: hints, notes, and
 solutions\footnote{for the moment multiple choice problems are not supported, but may
   well be in a future version}. Furthermore, we can specify how long the solution to a
@@ -7,7 +8,11 @@ solution.
 
 Finally, the \pkg{problem} package facilitates the management of problems in small files,
 so that problems can be re-used in multiple environment. 
+\end{sfragment}
 
+
+\begin{sfragment}{Problems and Solutions}
+  
 \begin{function}{solutions,notes,hints,gnotes,pts,min,boxed,test}
   The \pkg{problem} package takes the options |solutions| (should solutions be output?),
   |notes| (should the problem notes be presented?), |hints| (do we give the hints?),
@@ -43,7 +48,7 @@ so that problems can be re-used in multiple environment.
     \begin{exnote}
       Justify your answer
     \end{exnote}
-\begin{solution}[for=elefants,height=3cm]
+\begin{solution}[for=elefants]
   Four, two in the front seats, and two in the back.
   \begin{gnote}
     if they do not give the justification deduct 5 pts
@@ -66,7 +71,7 @@ so that problems can be re-used in multiple environment.
 \begin{environment}{hint,exnote,gnote}
   The |hint| and |exnote| environments can be used in a |problem| environment to give
   hints and to make notes that elaborate certain aspects of the problem.  The |gnote|
-  (grading notes) environment can be used to document situtations that may arise in
+  (grading notes) environment can be used to document situations that may arise in
   grading.
 \end{environment}
 
@@ -80,7 +85,22 @@ so that problems can be re-used in multiple environment.
   Also, sometimes, we want content (e.g. in an exam with master solutions) conditional on
   whether solutions are shown. This can be done with the |\ifsolutions| conditional.
 \end{function}
+\end{sfragment}
+
+\begin{sfragment}{Markup for Added-Value Services}
+
+\begin{sparagraph}
+  The |problem| package is all about specifying the meaning of the various moving parts of
+  practice/exam problems. The motivation for the additional markup is that we can base
+  added-value services from these, for instance auto-grading and immediate feedback.
 
+  The simplest example of this are multiple-choice problems, where the |problem| package
+  allows to annotate answer options with the intended values and possibly feedback that
+  can be delivered to the users in an interactive setting. In this section we will give
+  some infrastructure for these, we expect that this will grow over time. 
+\end{sparagraph}
+
+\begin{sfragment}{Multiple Choice Blocks}
 \begin{environment}{mcb}
   Multiple choice blocks can be formatted using the |mcb| environment, in which single
   choices are marked up with |\mcc| macro.
@@ -96,8 +116,8 @@ so that problems can be re-used in multiple environment.
   \item |feedback| for a short feedback text given to the student.
   \end{itemize}
 \end{function}
-
-If we start the solutions, then we get
+What we see when this is formatted to PDF depends on the context. In solutions mode (we
+start the solutions in the code fragment below) we get
 
 \stexexample{%
 \startsolutions
@@ -111,8 +131,8 @@ If we start the solutions, then we get
   \end{mcb}
 \end{sproblem}
 }
-without solutions (that is what the students see during the exam/quiz)\ednote{MK: that did
-not work!}
+
+In ``exam mode'' where disable solutions (here via |\stopsolutions|)
 \stexexample{%
 \stopsolutions
 \begin{sproblem}[title=Functions,name=functions1]
@@ -125,7 +145,44 @@ not work!}
   \end{mcb}
 \end{sproblem}
 }
-
+we get the questions without solutions (that is what the students see during the
+exam/quiz).
+\end{sfragment}
+
+\begin{sfragment}{Filling-In Concrete Solutions}
+The next simplest situation, where we can implement auto-grading is the case where we
+have fill-in-the-blanks 
+
+\begin{function}{\fillinsol}
+  The |\fillinsol| macro takes\Ednote{for now; more to come} an a single argument, which
+  contains a concrete solution (i.e. a number, a string, \ldots), which generates a
+  fill-in-box in test mode:
+\stexexample{%
+  \stopsolutions 
+  \begin{sproblem}[id=elefants.fillin,title=Fitting Elefants]
+    How many Elefants can you fit into a Volkswagen beetle? \fillinsol{4}
+\end{sproblem}}
+ and the actual solution in solutions mode:   
+\end{function}
+\stexexample{%
+  \begin{sproblem}[id=elefants.fillin,title=Fitting Elefants]
+    How many Elefants can you fit into a Volkswagen beetle? \fillinsol{4}
+  \end{sproblem}}
+If we do not want to leak information about the solution by the size of the blank we can
+also give |\fillinsol| an optional argument with a size: |\fillinsol[3cm]{12}| makes a box
+ three cm wide. 
+
+ Obviously, the required argument of |\fillinsol| can be used for auto-grading. For
+ concrete data like numbers, this is immediate, for more complex data like strings ``soft
+ comparisons'' might be in order. \ednote{For the moment we only assume a single concrete
+   value as correct. In the future we will almost certainly want to extend the
+   functionality to multiple answer classes that allow different feedback like im
+   MCQ. This still needs a bit of design. Also we want to make the formatting of the
+   answer in solutions/test mode configurable.}
+\end{sfragment}
+\end{sfragment}
+
+\begin{sfragment}{Including Problems}
 \begin{function}{\includeproblem}
   The |\includeproblem| macro can be used to include a problem from another file. It takes
   an optional KeyVal argument and a second argument which is a path to the file containing
@@ -144,8 +201,32 @@ The |\min| and |\pts| macros allow to specify (i.e. to print to the margin) the
 distribution of time and reward to parts of a problem, if the |pts| and |pts| options are
 set. This allows to give students hints about the estimated time and the points to be
 awarded.
+\end{sfragment}
+
+\begin{sfragment}{Testing and Spacing}
+The |problem| package is often used by the |hwexam| package, which is used to create
+homework assignments and exams. Both of these have a ``test mode'' (invoked by the
+package option |test|), where certain information --master solutions or feedback -- is
+not shown in the presentation.
+
+\DescribeMacro{\testspace}|\testspace| takes an argument that expands to a dimension, and
+leaves vertical space accordingly. Specific instances exist:
+\DescribeMacro{\testsmallspace}|\testsmallspace|,
+\DescribeMacro{\testsmallspace}|\testsmallspace|,
+\DescribeMacro{\testsmallspace}|\testsmallspace| give small (1cm), medium (2cm), and big (3cm)
+vertical space.
+
+\DescribeMacro{\testnewpage}|\testnewpage| makes a new page in |test| mode, and
+\DescribeMacro{\testemptypage}|\testemptypage| generates an empty page with the cautionary
+message that this page was intentionally left empty.
+\end{sfragment}
 
 %%% Local Variables:
 %%% mode: latex
 %%% TeX-master: "../stex-manual"
 %%% End:
+
+%  LocalWords:  solutions,notes,hints,gnotes,pts,min,boxed,test gnotes elefants,pts gnote
+%  LocalWords:  2,title exnote hint,exnote,gnote ifsolutions mcb keyvals Ttext Ftext
+%  LocalWords:  Functions,name F,feedback Nooooooooo,feedback 2,title includeproblem
+%  LocalWords:  elefants.fillin,title
-- 
cgit v1.2.3

