summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-problem.tex
blob: a90c36412d07258668ba2f544d169fd49f20e4a2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
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
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. 

\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}[for=elefants,height=3cm]
  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 situtations 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}

\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}

If we start the solutions, then 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}
}
without solutions (that is what the students see during the exam/quiz)\ednote{MK: that did
not work!}
\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}
}

\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.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../stex-manual"
%%% End: