path: root/macros/latex/contrib/exercisepoints/exercisepoints.tex

% !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}