From 6d44c638512eb736c41551c5887b4475a14935bf Mon Sep 17 00:00:00 2001 From: Norbert Preining 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