summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-problem.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/stex-problem.tex')
-rw-r--r--macros/latex/contrib/stex/doc/packages/stex-problem.tex97
1 files changed, 89 insertions, 8 deletions
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