summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/exercisepoints/exercisepoints.tex
blob: 4cf880c264e0e69154f4623903ef6df591651896 (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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
% !TEX encoding = UTF-8 Unicode
% !TEX program = pdflatex
%
%% exercisepoints.tex
%% Documentation for the exercisepoints package
%%
%% Copyright (c) 2017-2019 Henning Kerstan
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Henning Kerstan.
%
% This work consists of the files `exercisepoints.sty' and `exercisepoints.tex'.
%


% use KOMA article in twocolumn layout
\documentclass[
  twocolumn,%
  fontsize=9pt,%        this gives roughly 80 characters per line in twocolumns
  DIV=calc,%            calculate typearea
  numbers=noendperiod%  don't print periods at end of numbers
]{scrartcl}


% font selection & set up
\usepackage{charter} % Charter as serif font (main text)
\usepackage{biolinum} % Linux Biolinum as sans serif font (headings)
\usepackage[scaled=0.85]{beramono} % Bera Mono as monospace font (code listings)
\usepackage{eulervm} % Euler virtual math fonts
\RequirePackage[T1]{fontenc} % T1 fontenc
\usepackage[final]{microtype}
\setkomafont{captionlabel}{\sffamily\small\bfseries}
\setkomafont{caption}{\sffamily\small}
\usepackage[english]{babel}


% load the exercisepoints package
\usepackage{exercisepoints} 


% load xcolor for colors in code listings
\usepackage[dvipsnames]{xcolor}


% set up code listings
% - highlight standard LaTeX keywords in bold gray
% - highlight exercisepoints keywords in bold navy blue
\newcommand{\emphstyle}{\ttfamily\color{NavyBlue}\bfseries}%
\newcommand{\keyword}[1]{{\emphstyle#1}}%
\usepackage{listings} 
\lstset{%
  language=[LaTeX]TeX,%
  basicstyle=\small\ttfamily,%
  keywordstyle=,%\color{black!70},%
  keywords={equal},%
  identifierstyle=,%
  commentstyle=\itshape\color{OliveGreen},% 
  stringstyle=,%
  showstringspaces=false,%
  emphstyle=\emphstyle,%
  breaklines=true,%
  backgroundcolor=\color{black!5},%
  numbers=none,
  xleftmargin=1ex,
  xrightmargin=1ex,
  numberstyle=\small\ttfamily, 
  numbersep=1ex,
  emph={%
    exercisepoints,
    AtBeginExercise,%
    AtEndExercise,
    AtBeginSubexercise,%
    AtEndSubexercise,%
    points,%
    itempoints,%
    totalpoints,%
    numberofexercises,%
    currentexercisetitle,%
    currentexercisepoints,%
    currentexercisenumber,%
    exercise,%
    currentsubexercisetitle,%
    currentsubexercisepoints,%
    currentsubexercisenumber,%
    subexercise,%
    bonuspoints,%
    getbonuspoints,%
    customlayout,%
    totalpointswithbonus,%
    setitempointsunit
  }
} 


% obtain package version using xstring package to obtain 17 leftmost characters in the internal package version string
\makeatletter
\usepackage{xstring}
\newcommand{\packageversion}{\StrBefore[2]{\expandafter\csname ver@exercisepoints.sty\endcsname}{ }}
\makeatother


% use forloop package to automatically loop through all exercises
\usepackage{forloop}


% use gitinfo2 package for displaying git commit information in footer
\usepackage[mark]{gitinfo2}


% math examples
\usepackage{amsmath,amssymb}


% set up metadata
\author{Henning Kerstan}
\title{%
  The exercisepoints Package\thanks{%
    \url{https://github.com/henningkerstan/exercisepoints}%
  }
}
\subtitle{\packageversion}
\date{}


% use enumitem package and set up enumerate/itemize layout
\usepackage{enumitem}
\setlist[itemize]{%
  leftmargin=*,%
  itemsep=5pt,%
  topsep=5pt,%
  parsep=0pt,%
  partopsep=0pt,%
  label=\textcolor{black}{$\triangleright$}%
}%
\setlist[enumerate]{%
  leftmargin=*,%
  itemsep=5pt,%
  topsep=5pt,%
  parsep=0pt,%
  partopsep=0pt,%
  label=\textcolor{black}{\arabic*.},%
  ref=\arabic*%
}%


% use hyperref for hyperlinks
\usepackage[
  unicode=true,%
  pdfa,%
  colorlinks=false,%
  linktoc=page,
  pdfauthor={Henning Kerstan},
  pdftitle={The exercisepoints Package}
]{hyperref}


% start of the actual document
\begin{document}
\maketitle
\begin{abstract}
\noindent\itshape The exercisepoints package provides an exercise environment and several macros to count points for exercises. The actual typesetting of an exercise can be defined by the user.
\end{abstract}

\section{Introduction and Basic Usage}
This package can be used to facilitate exercise counting and exercise point counting in a \LaTeX-document. It counts the number of exercises (for example, it counted that this document has \emph{\numberofexercises\ exercises}) and it sums all the points of all exercises (for example, the package determined that the exercises in this document have a total of \emph{\totalpoints\ points}). 

Especially for exams it is also common to have an overview of all exercises and their maximal points. This is also supported by this package by providing a macro to retrieve the points of each exercise. For example, the exercise overview for this document is given in Figure~\ref{fig:exercise-overview} below.

\newcounter{exercisenumber}
\newcounter{exercisedisplaynumber}
\setcounter{exercisedisplaynumber}{0}

\begin{figure}[h]\centering
  \begin{tabular}{l|p{1cm}|r}
    \textbf{Exercise} & \textbf{Points} & \textbf{Max. Points}\\
    \hline
    \forloop{exercisenumber}{0}{\value{exercisenumber} < \numberofexercises}{%
      \stepcounter{exercisedisplaynumber}%
      \theexercisedisplaynumber && \getpoints{\theexercisenumber}\\%
    }%
    Sum && \totalpoints\\\hline%
    Bonus && \getbonuspoints\\\hline%
    Sum with Bonus && \totalpointswithbonus%
  \end{tabular}
  \label{fig:exercise-overview}
  \caption{Overview of all exercises}
\end{figure}

\noindent This package only provides functionality for counting and adding points, the actual typesetting of the exercise can be entirely determined by the user.

\subsection{Load the Package}
To use this package type
\begin{lstlisting}
\usepackage{exercisepoints}
\end{lstlisting}
anywhere in your document's preamble. If this does not work because the package is not contained in your \LaTeX-distribution, simply copy the file `exercisepoints.sty' into the same folder as your document (or, if you plan to use it more often, copy it into your local texmf directory).

\subsection{Typeset a First Exercise}
Now you can typeset your first exercise using the following code.

\begin{lstlisting}
\begin{exercise}[Simple Addition]
  What is 1+1?\points{2.5}
\end{exercise}
\end{lstlisting}

\noindent If you typeset this without further modifications it will yield the following result.\vspace{1cm}

\begin{exercise}[Simple Addition]
  What is $1+1$?\points{2.5}
\end{exercise}
%
As you can see, inside the code we used \textcolor{NavyBlue}{\ttfamily\bfseries \textbackslash points\{2.5\}} to assign this exercise a total of 2.5 points. These points were printed flushed right in the exercise header.

\subsection{Play with the Points}
If you issue the \textcolor{NavyBlue}{\ttfamily\bfseries \textbackslash points\{...\}} macro multiple times within an exercise environment, the points will add up. Thus let us consider the following code.

\begin{lstlisting}
\begin{exercise}[Simple Equation]
  Determine a number $x$ such that $3 \cdot x = 15$\points{1.5} and explain how you did that.\points{3}
\end{exercise} 
\end{lstlisting}

\noindent This code will typeset as follows.

\begin{exercise}[Simple Equation]
  Determine a number $x$ such that $3 \cdot x = 15$\points{1.5} and explain how you did that.\points{3}
\end{exercise}

\noindent As expected, the points were added to obtain the total 1.5 + 3 = 4.5 points which again is printed in the exercise's header. 

This feature is especially handy if you have an exercise with several subparts (items). In this case you can also use the \textcolor{NavyBlue}{\ttfamily\bfseries \textbackslash itempoints\{...\}} macro which does the same as the \textcolor{NavyBlue}{\ttfamily\bfseries \textbackslash points\{...\}} macro but additionally also prints the supplied points flush right. We rewrite our previous exercise with an enumerate environment as follows.

\begin{lstlisting}
\begin{exercise}[Simple Equation]\vspace{-1.5em}
  \begin{enumerate}
    \item Determine $x$ such that $3 \cdot x = 15$.\itempoints{1.5}
    \item Explain how you arrived at your solution in the previous part.\itempoints{3}
  \end{enumerate}
\end{exercise} 
\end{lstlisting}

\noindent This code results in the following output.
\begin{exercise}[Simple Equation]\vspace{-1.5em}
  \begin{enumerate}
    \item Determine $x$ such that $3 \cdot x = 15$.\itempoints{1.5}
    \item Explain how you arrived at your solution in the previous part.\itempoints{3}
  \end{enumerate}
\end{exercise}

Note that by default this only displays the number of points in parentheses. If you want to add a unit, you can use
\begin{lstlisting}
\setitempointsunit{pt}{pts}
\end{lstlisting}
anywhere in your document which sets \emph{pt} (singular form) and \emph{pts} (plural form) as units for the itempoints. Afterwards, all itempoints will display this unit right of the number.\setitempointsunit{pt}{pts}

\noindent In fact, if we do this and assign the first part of the above exercise just one point instead of 1.5 (replacing \texttt{\textbackslash\keyword{itempoints}\{1.5\}} by \texttt{\textbackslash \keyword{itempoints}\{1\}}), it will be displayed as follows.
\begin{exercise}[Simple Equation]\vspace{-1.5em}
  \begin{enumerate}
    \item Determine $x$ such that $3 \cdot x = 15$.\itempoints{1}
    \item Explain how you arrived at your solution in the previous part.\itempoints{3}
  \end{enumerate}
\end{exercise}

\subsection{Obtain the Total Points}
If you have typeset your exercises, there are a few commands to obtain the total number of points.

\begin{itemize}
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash numberofexercises} expands to the number of all exercises in the document.
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash totalpoints} expands to the sum of all points of all exercises in the document. 
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash getpoints\{x\}} expands to the total points of the exercise number x (starting with $0$). 
\end{itemize}
Note that the information for these macros is retrieved from the .aux file so to get the right numbers here, you have to compile your document twice. As a simple example for the above macros we take the following code.


\begin{lstlisting}[emph={numberofexercises,totalpoints,getpoints}]
Exercise 0 has \getpoints{0} points, there are \numberofexercises\ exercises with a total of \totalpoints\ points.
\end{lstlisting}

\noindent This compiles to the following sentence.\smallskip

Exercise 0 has \getpoints{0} points, there are \numberofexercises\ exercises with a total of \totalpoints\ points.

\subsection{Use Bonus Points}
In some courses it is possible to obtain a bonus for the exam. This is supported by providing the commands
\begin{lstlisting}
\bonuspoints{x}
\end{lstlisting}
which will set the total amount of bonus points to $x$ bonuspoints (in this document we have used it with $x=10$\bonuspoints{10}) and
\begin{lstlisting}
\getbonuspoints
\end{lstlisting}
which retrieves the current bonus points (in this document it expands to \getbonuspoints). Please note that the {bonuspoint} command differs from the \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash points} and \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash itempoint} commands in two aspects:
\begin{itemize} 
\item Bonus points are \emph{not additive}, i.e., if you use \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash bonuspoints} multiple times in your document, only the last occurence will set the bonus points.
\item Bonus points are \emph{not} added to the total points. However, there is an additional macro 
\begin{lstlisting}
\totalpointswithbonus
\end{lstlisting}
which will expand to the sum of \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash totalpoints} and \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash getbonuspoints}. In this document it thus expands to \totalpointswithbonus.
\end{itemize}

\subsection{Subexercises}
If you have an exercise with many different parts (for example, if you have one overall topic with several areas), you can use the subexercise environment to structure your exercise. Subexercises work exactly as exercises, but can only be used within an exercise environment. The following is a compiled example of such an exercise.

\begin{exercise}[Calculus]
  \vspace{-1em}
  \begin{subexercise}[Derivatives]
    Determine the derivatives of the following functions.
    \begin{enumerate}
      \item $f\colon \mathbb{R} \to \mathbb{R}$, $f(x) = x^2+2x+3$ \itempoints{1}
      \item $g\colon \mathbb{R} \to \mathbb{R}$, $g(x) = \exp(x^2)$ \itempoints{3}
    \end{enumerate}
  \end{subexercise}\vspace{-1em}
  \begin{subexercise}[Maxima and Minima]
    Determine the local maximum or minimum of the function $f\colon \mathbb{R} \to \mathbb{R}, f(x) = x^2+2x+3$.\points{3}
  \end{subexercise}\vspace{-1em}
\end{exercise}

\noindent It was typeset using the following code.

\begin{lstlisting}
\begin{exercise}[Calculus]
  \vspace{-1em}
  \begin{subexercise}[Derivatives]
    Determine the derivatives of the following functions.
    \begin{enumerate}
      \item $f\colon \mathbb{R} \to \mathbb{R}$, 
            $f(x) = x^2+2x+3$ \itempoints{1}
      \item $g\colon \mathbb{R} \to \mathbb{R}$, 
            $g(x) = \exp(x^2)$ \itempoints{3}
    \end{enumerate}
  \end{subexercise}\vspace{-1em}
  \begin{subexercise}[Maxima and Minima]
    Determine the local maximum or minimum of the function 
      $f\colon \mathbb{R} \to \mathbb{R}, 
        f(x) = x^2+2x+3$.\points{3}
  \end{subexercise}
\end{exercise}
\end{lstlisting}

\noindent Note that it is only possible to use the subexercise environment within an exercise environment and it is not possible to nest subexercise environments.

\section{Exercise Layout}
This package only provides a minimal layout style for an exercise which is \emph{not meant to be actually used}. It is just included to test the package functionality.

\subsection{Disable the Built In Layout}
If you define your own layout, you can load the package (but it is not necessary) with the \textcolor{NavyBlue}{\ttfamily\bfseries customlayout} option, i.e. by issuing the command 
\begin{lstlisting}
\usepackage[customlayout]{exercisepoints}
\end{lstlisting}
which disables the built in exercise style. Note that in this case your document will only compile exercises or subexercises if you have defined the respective layout. Otherwise compilation will stop with a package error message.

\subsection{Define Your Own Layout}
In order to define how your exercise looks like, you can use the two commands listed below.
\begin{lstlisting}
\AtBeginExercise{%
  % your code
}

\AtEndExercise{%
  % your code
}
\end{lstlisting}
For example, the minimal example style is implemented using the following code.
\begin{lstlisting}
\AtBeginExercise{%
  ~\smallskip\\\sffamily%
  \ifthenelse{\equal{\currentexercisetitle}{}}%
    {\textbf{Exercise~\currentexercisenumber}}%
    {%
      \textbf{Exercise~\currentexercisenumber:} %
      \currentexercisetitle%
    }%
  \,~\hfill\textbf{(\currentexercisepoints~Points)}%
  \smallskip\\\noindent\normalfont%
}
\AtEndExercise{~\smallskip\\}%
\end{lstlisting}
As you can see, there are three useful macros that can be used for defining the exercise layout:
\begin{itemize}
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentexercisetitle} expands to the exercise title supplied as (optional) argument to the exercise environment.
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentexercisenumber} expands to the current internal exercise number (starting at $0$). 
  \item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentexercisepoints} expands to the current exercise total points. Note that this is retrieved from the .aux file so to get the right number here, you have to compile your document twice.
\end{itemize}

\noindent For subexercises you have essentially the same commands, i.e., you have the commands 
\begin{itemize}
\item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash AtBeginSubexercise\{...\}},
\item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash AtEndSubexercise\{...\}}, 
\item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentsubexercisenumber}, 
\item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentsubexercisepoints} and 
\item \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentsubexercisetitle}
\end{itemize}
which work as their counterparts for exercises.

\subsection{Example Layout Using (Sub-)Sections}
One option for a custom layout could be to use sections for exercises and subsections for subexercises. This can be achieved using the following code.

\begin{lstlisting}
\usepackage[customlayout]{exercisepoints}
\AtBeginExercise{%
  \section{\texorpdfstring{%
    \currentexercisetitle\hfill%
    (\currentexercisepoints~Points)}{%
    \currentexercisetitle (\currentexercisepoints~Points)}%
  }
}
\AtEndExercise{\clearpage}
\AtBeginSubexercise{%
  \subsection{\texorpdfstring{%
    \currentsubexercisetitle\hfill%
    (\currentsubexercisepoints~Points)}{%
    \currentsubexercisetitle %
    (\currentsubexercisepoints~Points)}%
  }
}
\AtEndSubexercise{}
\end{lstlisting}

\section{Copyright and License}
Copyright \copyright\ 2017--2019 Henning Kerstan.\medskip

\noindent This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 of this license or (at your option) any later version. The latest version of this license is in\medskip

   \url{http://www.latex-project.org/lppl.txt}\medskip

\noindent and version 1.3 or later is part of all distributions of LaTeX version 2005/12/01 or later.\medskip

\noindent This work has the LPPL maintenance status `maintained'.\medskip

\noindent The Current Maintainer of this work is Henning Kerstan.\medskip

\noindent This work consists of the files `exercisepoints.sty' and `exercisepoints.tex'.


\section{Version History}
\begin{description}
\item[\packageversion] Revised README.md.
\item[2019/01/02 v1.2.2] Slight revision of documentation.
\item[2018/08/15 v1.2.1] Renamed the package from \emph{hkexercise} to \emph{exercisepoints} to comply with CTAN rules (see \url{https://ctan.org/file/help/ctan/CTAN-upload-addendum})
\item[2017/02/27 v1.2.0] Added the \texttt{\textbackslash\keyword{setitempointsunit}\{...\}} command.
\item[2017/07/02 v1.1.0] This version introduces subexercises. Moreover several checks were added to avoid use of commands like \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentexercisepoints} outside of exercise environments and to prevent nesting of exercises. New option \textcolor{NavyBlue}{\ttfamily\bfseries customlayout} disables built in exercise layout. Added \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash bonuspoint} commands.
\item[2017/06/26 v1.0.1] Redefined \textcolor{NavyBlue}{\ttfamily\bfseries\textbackslash currentexercisepoints} so it can be used within section command. 
\item[2017/06/26 v1.0] The initial version of this package is published on GitHub.
\end{description}
\end{document}