\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. Furthermore, we can specify how long the solution to a given problem is
  estimated to take and how many points will be awarded for a perfect 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?),
  |gnotes| (do we show grading notes?), |pts| (do we display the points awarded for
  solving the problem?), |min| (do we display the estimated minutes for problem
  soling). If theses are specified, then the corresponding auxiliary parts of the problems
  are output, otherwise, they remain invisible.

  The |boxed| option specifies that problems should be formatted in framed boxes so that
  they are more visible in the text. Finally, the |test| option signifies that we are in a
  test situation, so this option does not show the solutions (of course), but leaves space
  for the students to solve them.
\end{function}

\begin{environment}{problem}
  The main environment provided by the \pkg{problem}package is (surprise surprise) the
  |problem| environment. It is used to mark up problems and exercises. The environment
  takes an optional KeyVal argument with the keys |id| as an identifier that can be
  reference later, |pts| for the points to be gained from this exercise in homework or
  quiz situations, |min| for the estimated minutes needed to solve the problem, and
  finally |title| for an informative title of the problem.
\end{environment}

\stexexample{%
\documentclass{article}
\usepackage[solutions,hints,pts,min]{problem}
\begin{document}
  \begin{sproblem}[id=elefants,pts=10,min=2,title=Fitting Elefants]
    How many Elefants can you fit into a Volkswagen beetle?
    \begin{hint}
      Think positively, this is simple!
    \end{hint}
    \begin{exnote}
      Justify your answer
    \end{exnote}
\begin{solution}
  Four, two in the front seats, and two in the back.
  \begin{gnote}
    if they do not give the justification deduct 5 pts
  \end{gnote}
\end{solution}
\end{sproblem}
\end{document}
}

\begin{environment}{solution}
  The |solution| environment can be to specify a solution to a problem. If the package
  option |solutions| is set or |\solutionstrue| is set in the text, then the solution will
  be presented in the output. The |solution| environment takes an optional KeyVal argument
  with the keys |id| for an identifier that can be reference |for| to specify which
  problem this is a solution for, and |height| that allows to specify the amount of space
  to be left in test situations (i.e. if the |test| option is set in the |\usepackage|
  statement).
\end{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 situations that may arise in
  grading.
\end{environment}

\begin{function}{\startsolutions,\stopsolutions}
  Sometimes we would like to locally override the |solutions| option we have given to the
  package. To turn on solutions we use the |\startsolutions|, to turn them off,
  |\stopsolutions|. These two can be used at any point in the documents.
\end{function}

\begin{function}{\ifsolutions}
  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.
\end{environment}

\begin{function}{\mcc}
  |\mcc[|\meta{keyvals}|]{|\meta{text}|}| takes an optional key/value argument
  \meta{keyvals} for choice metadata and a required argument \meta{text} for the proposed
  answer text. The following keys are supported
  \begin{itemize}
  \item |T| for true answers, |F| for false ones,
  \item |Ttext| the verdict for true answers, |Ftext| for false ones, and
  \item |feedback| for a short feedback text given to the student.
  \end{itemize}
\end{function}
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
\begin{sproblem}[title=Functions,name=functions1]
  What is the keyword to introduce a function definition in python?
  \begin{mcb}
    \mcc[T]{def}
    \mcc[F,feedback=that is for C and C++]{function}
    \mcc[F,feedback=that is for Standard ML]{fun}
    \mcc[F,Ftext=Nooooooooo,feedback=that is for Java]{public static void}
  \end{mcb}
\end{sproblem}
}

In ``exam mode'' where disable solutions (here via |\stopsolutions|)
\stexexample{%
\stopsolutions
\begin{sproblem}[title=Functions,name=functions1]
  What is the keyword to introduce a function definition in python?
  \begin{mcb}
    \mcc[T]{def}
    \mcc[F,feedback=that is for C and C++]{function}
    \mcc[F,feedback=that is for Standard ML]{fun}
    \mcc[F,Ftext=Nooooooooo,feedback=that is for Java]{public static void}
  \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 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. \footnote{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
  the problem (the macro assumes that there is only one problem in the include file). The
  keys |title|, |min|, and |pts| specify the problem title, the estimated minutes for
  solving the problem and the points to be gained, and their values (if given) overwrite
  the ones specified in the |problem| environment in the included file.
\end{function}

The sum of the points and estimated minutes (that we specified in the |pts| and |min| keys
to the |problem| environment or the |\includeproblem| macro) to the log file and the
screen after each run. This is useful in preparing exams, where we want to make sure that
the students can indeed solve the problems in an allotted time period.

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