From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 .../exam-randomizechoices-doc.tex                  | 1123 ++++++++++++++++++++
 1 file changed, 1123 insertions(+)
 create mode 100644 macros/latex/contrib/exam-randomizechoices/exam-randomizechoices-doc.tex

(limited to 'macros/latex/contrib/exam-randomizechoices/exam-randomizechoices-doc.tex')

diff --git a/macros/latex/contrib/exam-randomizechoices/exam-randomizechoices-doc.tex b/macros/latex/contrib/exam-randomizechoices/exam-randomizechoices-doc.tex
new file mode 100644
index 0000000000..a8b00f9b10
--- /dev/null
+++ b/macros/latex/contrib/exam-randomizechoices/exam-randomizechoices-doc.tex
@@ -0,0 +1,1123 @@
+%%--------------------------------------------------------------------
+%%--------------------------------------------------------------------
+%% exam-randomizechoices-doc.tex
+%%
+%% This is the user's guide for the exam-randomizechoices package, 
+%% by Jesse op den Brouw
+%%
+%% The package itself is in the file exam-randomizechoices.sty.
+
+
+%% Copyright (c)2019, Jesse E. J. op den Brouw
+%%
+%% 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 2003/12/01 or later.
+%%
+%% This work consists of the files exam-randomizechoices.sty,
+%% exam-randomizechoices.tex and exam-randomizechoices-doc.tex
+
+%% This software is provided 'as is', without warranty of any kind,
+%% either expressed or implied, including, but not limited to, the
+%% implied warranties of merchantability and fitness for a
+%% particular purpose.
+
+%% Jesse op den Brouw
+%% Department of Electrical Engineering
+%% The Hague University of Applied Sciences
+%% Rotterdamseweg 137, 2628 AL, Delft
+%% Netherlands
+%% J.E.J.opdenBrouw@hhs.nl
+
+%% The newest version of this package should always be available
+%% from BitBucket: https://bitbucket.org/jesseopdenbrouw/exam-randomizechoices/src/master/
+
+%--------------------------------------------------------------------
+%--------------------------------------------------------------------
+
+\documentclass[12pt,a4paper]{exam}
+
+\newcommand{\styversion}{\fileversion}
+\newcommand{\stydate}{\filedate}
+\newcommand{\docdate}{January 9, 2019}
+%\newcommand{\docdate}{Draft: \today}
+
+\usepackage{mathtools}
+%\usepackage{amssymb}
+
+%% Set input encoding to UTF-8
+\usepackage[utf8]{inputenc}
+%% Use T1 output font encoding
+\usepackage[T1]{fontenc}
+
+%% Set page layout
+\usepackage[a4paper,left=1.0in,right=1.0in,top=1.0in,bottom=1.4in,footskip=0.5in]{geometry}
+
+%% Use package enumitem
+\usepackage{enumitem}
+                   
+%% Load English spelling
+\usepackage[english]{babel}
+
+%% Nice tables
+\usepackage{tabu}
+
+%% Colors
+\usepackage[x11names]{xcolor}
+
+%% Use the Charter font + math symbols
+\usepackage[scaled=0.9]{nimbusmono}
+\usepackage[bitstream-charter]{mathdesign}
+%% Use microtype
+\usepackage[stretch=10]{microtype}
+
+\usepackage{listings}
+\usepackage{textcomp}
+
+\lstset{ %
+  language=[AlLaTeX]TeX,
+  basicstyle=\ttfamily,
+  numbers=left,
+  numberstyle=\tiny\color{gray},
+  stepnumber=1,                           
+  numbersep=8pt,
+  showspaces=false,
+  showstringspaces=false,
+  showtabs=false,
+  frame=lines,
+  rulecolor=\color{gray},
+  tabsize=4,
+  captionpos=b,
+  breaklines=true,
+  breakatwhitespace=true,
+  title=\lstname,
+  upquote=true,
+  aboveskip=0.3\baselineskip,
+  belowskip=-.5\baselineskip,
+  escapeinside={(*}{*)}
+}
+
+\usepackage[colorlinks,linkcolor=blue]{hyperref}
+
+\usepackage{titlesec}
+\usepackage{titletoc}
+\titleformat{\section}{\fontfamily{phv}\selectfont\large\bfseries}{\thesection}{1em}{}
+\titleformat{\subsection}{\fontfamily{phv}\selectfont\bfseries}{\thesubsection}{1em}{}
+\titlespacing*{\section}{0pt}{\baselineskip}{\aftersubsection}
+\titlespacing*{\paragraph}{0pt}{1.0ex plus 1ex minus .2ex}{1.5em}
+\newlength{\aftersubtitle}
+\setlength{\aftersubtitle}{1.2\baselineskip}
+\newlength{\aftersubsection}
+\setlength{\aftersubsection}{\aftersubtitle}
+\addtolength{\aftersubsection}{-\baselineskip}
+\titlespacing*{\subsection}{0pt}{.8\baselineskip}{\aftersubsection}
+\titlespacing*{\subsubsection}{0pt}{.6\baselineskip}{0pt}
+
+%% parskip et al.                                            
+\usepackage{parskip}
+
+%% The randomization package
+\usepackage[randomize,nokeeplast]{exam-randomizechoices}
+
+%% Set seed
+\setrandomizerseed{1}
+
+% In case we're not using hyperref.sty:
+\providecommand{\texorpdfstring}[2]{#1}
+% The following can be used in \section commands
+% without generating pdf warnings:
+\newcommand{\bs}{\texorpdfstring{\char`\\}{}}
+
+
+%---------------------------------------------------------------------
+%---------------------------------------------------------------------
+%---------------------------------------------------------------------
+%---------------------------------------------------------------------
+
+\begin{document}
+\raggedbottom
+
+\cfoot[]{Page \thepage\ of \numpages}
+
+\title{The \texttt{exam-randomizechoices} package\\[2ex]\normalsize LaTeX package for creating random placed choices in multiple choice \\environments using the \texttt{exam} document class}
+
+\author{Jesse op den Brouw\\
+  Department of Electrical Engineering\\
+  The Hague University of Applied Sciences\\
+  Delft, Netherlands\\
+  \href{mailto:J.E.J.opdenBrouw@hhs.nl}{J.E.J.opdenBrouw@hhs.nl}\\[\bigskipamount]
+  Copyright \copyright \the\year\ Jesse op den Brouw\\
+  All rights reserved}
+
+\date{\docdate}
+
+\maketitle
+
+\thispagestyle{empty}
+
+%% We like the metric system...
+\vspace*{2cm}
+
+\begin{center}
+  \small
+  This is the user's guide for version~\styversion{} [\stydate] of the
+  \verb|exam-randomizechoices| package. 
+\end{center}
+
+\clearpage
+\tableofcontents
+
+\clearpage
+
+
+\section{Introduction}
+This document describes the \LaTeX\ \texttt{exam-randomizechoices} package.
+The package provides the user with four new multiple choice typesetting
+environments which place the content in a random order. It can (only) be used
+in combination with the \texttt{exam} document class. It can only
+randomize the placement of choices in multiple choice questions. The questions
+themselves can't be randomized with this package.
+
+Furthermore, the package provides a simple answer key table typesetter and has
+a command for writing the answer keys to an external file.
+
+\subsection{License and warranty}
+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 \url{http://www.latex-project.org/lppl.txt}
+and version 1.3 or later is part of all distributions of \LaTeX{}
+version 2003/12/01 or later.
+
+This work has the LPPL maintenance status ``author-maintained''.
+
+This work consists of the files \texttt{exam-randomizechoices.sty},
+\texttt{exam-randomizechoices.tex} and \texttt{exam-randomizechoices-doc.tex}
+
+This software is provided `as is', without warranty of any kind,
+either expressed or implied, including, but not limited to, the
+implied warranties of merchantability and fitness for a
+particular purpose.
+
+\subsection{Where to find}
+The development version of this package is available on BitBucket. See
+
+\url{https://bitbucket.org/jesseopdenbrouw/exam-randomizechoices/}
+
+\subsection{Acknowledgements}
+The author wishes to thank the developers of the \verb|exam| document
+class and the \verb|mcexam|, \verb|environ|, \verb|etoolbox| and \verb|pgffor|
+packages.
+
+\subsection{Warning}
+This package is experimental, so it could possibly break \LaTeX{}
+compilation. Use this package with care. Please report any problems
+to the author.
+
+Please use a recent version of the \texttt{exam} document class. This
+package is tested with version 2.603 which is available in most distributions.
+Testing with version 2.605\$\bs beta\$ is planned.
+
+\subsection{A word about reading this document}
+This document uses terminology which is described below:
+
+\begin{itemize}
+\item If you encounter the term ``the standard multiple choice environments'',
+you should read this as ``the \texttt{choices}, \texttt{oneparchoices},
+\texttt{checkboxes} and \texttt{oneparcheckboxes} environments''.
+
+\item If you encounter the term ``the new multiple choice environments'',
+you should read this as ``the \texttt{randomizechoices}, \texttt{randomizeoneparchoices},
+\texttt{randomizecheckboxes} and \texttt{randomizeoneparcheckboxes} environments''.
+
+\item If you encounter the term ``\texttt{*choices}'', you should read this as
+``\texttt{choices}, \texttt{oneparchoices}, \texttt{randomizechoices} and \texttt{randomizeoneparchoices}''.
+
+\item If you encounter the term ``\texttt{*checkboxes}'', you should read this as
+``\texttt{checkboxes}, \texttt{oneparcheckboxes}, \texttt{randomizecheckboxes} and
+\texttt{randomizeoneparcheckboxes}''.
+
+\item If you encounter the term ``command'' in the context of a backslash followed
+by a series of characters, you can read this as ``macro''. The official \TeX-name
+is ``control sequence''.
+\end{itemize}
+
+
+\section{Using the \texttt{exam} class}
+This section provides a limited introduction to the \texttt{exam} document
+class. As a novice user, please read on. If you are a experienced user,
+you may skip this section.
+
+The \verb|exam| document class is a powerful class to create exams
+with \LaTeX{}. Both open questions and multiple choice questions are
+supported. For multiple choice questions we can differentiate between
+enumerated lists or checkbox lists. The class documentation states%
+\footnote{See \url{https://ctan.org/tex-archive/macros/latex/contrib/exam}.}:
+
+\begin{quote}
+The file \verb"exam.cls" provides the \verb"exam" document class,
+which attempts to make it easy for even a \LaTeX{} novice to prepare
+exams.  Specifically, \verb"exam.cls" sets the page layout so that
+there are one inch margins\index{margins} all around (no matter what
+size paper you're using) and provides commands that make it easy to
+format questions, create flexible headers and footers, change the
+margins, and create grading tables.  In more detail:
+\begin{itemize}
+\item The class will automatically format and number the questions,
+  parts of questions, subparts of parts, and subsubparts of subparts.
+\item You can include the point value\index{points} of each question
+  (or part, or subpart, or subsubpart), with your choice of having the
+  point values printed at the beginning of the text of the question,
+  opposite that in the left margin, opposite that in the right margin,
+  or in the right margin opposite the end of the question.
+\item The class will add up the total points for each question (and
+  all of its parts, subparts, and subsubparts) and the total
+  points\index{points!total} on each page, and make those totals
+  available in macros.
+\item You can have the class print a grading table, indexed either by
+  question number or by page number.
+\item You specify the header in three parts: One part to be left
+  justified, one part to be centered, and one part to be right
+  justified, and one or all of these can be omitted.
+\item The footer is also specified in three parts: Left justified,
+  centered, and right justified.
+\item The header and footer for the first page can be different from
+  the ones used on other pages.
+\item Both headers and footers can contain more than one line. To
+  accommodate headers and footers with several lines, simple commands
+  are provided to enlarge the part of the page devoted to the header
+  and/or footer, and these commands can give one amount of space on
+  the first page and a different amount of space on all other pages.
+\item Macros are defined to enable you to state the total number of
+  pages in the exam and to change the
+  header and/or footer that appears on the last page of the exam .
+\item Macros are defined so that the headers and footers can vary
+  depending on whether the current page begins a new question or
+  continues a question that started on an earlier page (and, if one
+  continues onto the current page, to say what the number of that
+  question is).  Macros are also defined so that the headers and
+  footers can vary depending on whether a question is complete on the
+  current page or continues on to the next page (and, if one
+  continues, to say what the number of that question is).
+\item You can have a horizontal rule at the base of the header and/or
+  at the top of the footer.
+\item The exam can begin with one or more cover pages, which are
+  numbered separately from the main pages of the exam and which can
+  have headers and footers different from the ones in the main pages
+  of the exam.
+\item You can include solutions in your \LaTeX{} file and have these
+  solutions either printed or ignored (or replaced automatically by
+  space in which the students can write their answers) depending on a
+  single command.
+\end{itemize}
+\end{quote}
+
+Furthermore, not stated in this excerpt, you can typeset bonus questions
+with bonus points and grading tables with bonus points.
+
+You can load the \texttt{exam} document class the usual way. An example
+might be:
+
+\begin{lstlisting}
+\documentclass[a4paper,12pt,addpoints]{exam}
+\end{lstlisting}
+
+which loads the \texttt{exam} document class. The paper size is set to
+A4 (297 mm $\times$ 210 mm, 11.7~in $\times$ 8.3 in), the document is
+typeset with a 12 points font and the question points are calculated.
+
+
+\subsection{Typesetting multiple choice questions}
+Then, within the document body and between \texttt{\bs begin\{questions\}} and
+\texttt{\bs end\{questions\}}, you enter the questions. Only multiple choice
+questions are considered here. The \texttt{exam} document class provides four types
+of multiple choice question environments:
+
+\begin{description}[labelindent=2ex]
+\item[\texttt{choices}] The given choices are typeset in a linear, vertical list.
+Each given choice is prepended with a label name which can be set to uppercase
+letter, lowercase letter, Roman numerals (uppercase and lowercase) and the Greek
+alphabet\footnote{Provided by the \texttt{exam} document class.}.
+
+\item[\texttt{oneparchoices}] The given choices are typeset in a linear, horizontal list.
+Long lists are split over multiple lines.
+Each given choice is prepended with a label name which can be set to uppercase
+letter, lowercase letter, Roman numerals (uppercase and lowercase) and the Greek
+alphabet.
+
+\item[\texttt{checkboxes}] The given choices are typeset in a linear, vertical list.
+Each given choice is prepended with a checkbox, which defaults to a big circle. 
+
+\item[\texttt{oneparcheckboxes}] The given choices are typeset in a linear, horizontal
+list. Long lists are split over multiple lines.
+Each given choice is prepended with a checkbox, which defaults to a big circle.
+
+\end{description}
+
+ Within the environments, the
+commands \texttt{\bs choice} and \texttt{\bs CorrectChoice} designate the
+typesetting material. The difference between the two commands is discussed
+in Section~\ref{sec:solutions}.
+
+Examples of the four environments are given below.
+
+\subsection{The \texttt{choices} environment}
+
+An example of a question with the \texttt{choices} environment is:
+
+\begin{lstlisting}
+\question[5] What is the result of $1+1$?
+
+\begin{choices}
+\choice 1
+\CorrectChoice 2
+\choice 3
+\choice 4
+\end{choices}
+\end{lstlisting}
+
+which is typeset as:
+\enlargethispage{\baselineskip}
+\begin{questions}
+\setcounter{question}{0}
+\question[5] What is the result of $1+1$?
+
+\begin{choices}
+\choice 1
+\CorrectChoice 2
+\choice 3
+\choice 4
+\end{choices}
+\end{questions}
+
+\subsection{The \texttt{oneparchoices} environment}
+
+An example of a question with the \texttt{oneparchoices} environment is:
+
+\begin{lstlisting}
+\question[5] What is the result of $2+2$?
+
+\begin{oneparchoices}
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice 4
+\end{oneparchoices}
+\end{lstlisting}
+
+which is typeset as:
+
+\begin{questions}
+\setcounter{question}{1}
+\question[5] What is the result of $2+2$?
+
+\begin{oneparchoices}
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice 4
+\end{oneparchoices}
+\end{questions}
+
+Furthermore, the \texttt{exam} document class provides two ways of typesetting
+checkbox questions.
+
+\subsection{The \texttt{checkboxes} environment}
+
+An example of a vertically aligned checkbox environment is:
+
+\begin{lstlisting}
+\question[5] What is the result of $1+2$?
+
+\begin{checkboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{checkboxes}
+\end{lstlisting}
+
+which typesets to:
+
+\begin{questions}
+\setcounter{question}{2}
+\question[5] What is the result of $1+2$?
+
+\begin{checkboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{checkboxes}
+\end{questions}
+
+\subsection{The \texttt{onecheckboxes} environment}
+
+The \texttt{oneparcheckboxes} environment typesets the choices
+in al linear, horizontal way. An example is given below:
+
+\begin{lstlisting}
+\question[5] What is the result of $1+2$?
+
+\begin{oneparcheckboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{oneparcheckboxes}
+\end{lstlisting}
+
+which typesets to:
+
+\begin{questions}
+\setcounter{question}{3}
+\question[5] What is the result of $1+2$?
+
+\begin{oneparcheckboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{oneparcheckboxes}
+\end{questions}
+
+Other types of questions are not considered here.
+
+\subsection{Typesetting solutions}
+\label{sec:solutions}
+Please note the use of the \texttt{\bs choice} and \texttt{\bs CorrectChoice}
+commands. A \texttt{\bs choice} typesets as an item in the list with no special markup.
+A \texttt{\bs CorrectChoice} typesets an item in the list with special markup if
+the \texttt{exam} document class option \texttt{answers} is given, otherwise it
+typesets the same way a \texttt{\bs choice}. This special
+markup defaults to boldface for the \texttt{choices} and \texttt{oneparchoices}
+environments:
+
+\begin{lstlisting}
+\question[5] What is the result of $2+2$?
+
+\begin{choices}
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice 4
+\end{choices}
+\end{lstlisting}
+
+which is typesets as:
+
+\printanswers
+
+\begin{questions}
+\setcounter{question}{4}
+\question[5] What is the result of $2+2$?
+
+\begin{choices}
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice 4
+\end{choices}
+\end{questions}
+
+Note that item D is typeset in boldface. The \texttt{checkboxes} and \texttt{oneparcheckboxes}
+environments use a \emph{surd}\footnote{A surd is a simplistic form of a square root sign.}:
+
+\begin{lstlisting}
+\question[5] What is the result of $1+2$?
+
+\begin{oneparcheckboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{oneparcheckboxes}
+\end{lstlisting}
+
+which typesets to:
+
+\begin{questions}
+\setcounter{question}{5}
+\question[5] What is the result of $1+2$?
+
+\begin{oneparcheckboxes}
+\choice 1
+\choice 2
+\CorrectChoice 3
+\choice 4
+\end{oneparcheckboxes}
+\end{questions}
+
+\noprintanswers
+
+
+\section{Using the package \texttt{exam-randomizechoices}}
+Although the \texttt{exam} document class is a very powerful tool to
+create exams, it does not provide options to typeset the content of the
+standard multiple choice environments in a random order\footnote{It
+also doesn't provides options to randomize questions.}. This package
+addresses this situation.
+
+\subsection{New multiple choice environments}
+Basically, this package provides the user with four new multiple choice
+environments:
+
+\begin{description}[labelindent=2ex]
+\item[\texttt{randomizechoices}] This is the randomizing counterpart of the
+\texttt{choices} environment. It typesets the given items in a random order.
+
+\item[\texttt{randomizeoneparchoices}] This is the randomizing counterpart of the
+\texttt{oneparchoices} environment. It typesets the given items in a random order.
+
+\item[\texttt{randomizecheckboxes}] This is the randomizing counterpart of the
+\texttt{checkboxes} environment. It typesets the given items in a random order.
+
+\item[\texttt{randomizeoneparcheckboxes}] This is the randomizing counterpart of the \linebreak
+\texttt{oneparcheckboxes} environment. It typesets the given items in a random order.
+
+\end{description}
+
+
+\subsection{Using the new multiple choice environments}
+We will discuss the \texttt{randomizechoices} environment only. The other
+environment work alike.
+
+You can use the new multiple choice environments in the same way as the non-randomizing counterparts.
+So an example of the \texttt{randomizechoices} environment might be:
+
+\begin{lstlisting}
+\question[5] What is the result of $1+1$?
+
+\begin{randomizechoices}
+\choice 1
+\CorrectChoice 2
+\choice 3
+\choice 4
+\end{randomizechoices}
+\end{lstlisting}
+
+which \emph{possibly} is typeset as:
+
+\begin{questions}
+\setcounter{question}{6}
+\question[5] What is the result of $1+1$?
+
+\begin{randomizechoices}
+\choice 1
+\CorrectChoice 2
+\choice 3
+\choice 4
+\end{randomizechoices}
+\end{questions}
+
+Here we can see that the resulting output is typeset in a different order
+then the choices are given. We say \emph{possibly} because the output
+depends on the state of the pseudo random generator (see Section~\ref{sec:seeding}).
+
+\subsection{Arguments to the new multiple choice environments}
+The new multiple choice environments accept (a combination of) the following optional arguments
+which are local to the environment currently being typeset:
+
+\begin{description}[labelindent=2ex]
+\item[randomize] The typesetting material is randomized. This is the default
+behaviour of the package.
+\item[norandomize] Randomization is turned off.
+Useful if you wish to see the typesetting in the given order.
+\item[keeplast] The last given item in the entered order is not part of the
+randomization process. This way you can keep the last item always the last item.
+\item[nokeeplast] The last given item is used in the randomization process. This
+is the default behaviour of the package.
+
+\end{description}
+
+Sometimes you want the last given item to stick on its place. This is useful
+if you want to use an choice item if none of the other choices are correct:
+
+\begin{lstlisting}
+\question[5] What is the result of $2+5$?
+
+\begin{randomizechoices}[keeplast]
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice None of the above answers is correct.
+\end{randomizechoices}
+\end{lstlisting}
+
+which possibly is typeset as:
+
+\begin{questions}
+\setcounter{question}{7}
+\question[5] What is the result of $1+1$?
+
+\begin{randomizechoices}[keeplast]
+\choice 1
+\choice 2
+\choice 3
+\CorrectChoice None of the above answers are correct.
+\end{randomizechoices}
+\end{questions}
+
+Note that the last item can also be a \texttt{\bs choice} command. Also note
+that if randomization is turned off, the \texttt{keeplast} option has no effect.
+
+\subsection{Loading the package}
+The package is loaded using the well-known \texttt{\bs{usepackage}} command:
+
+\begin{lstlisting}
+\usepackage[(* \emph{\textrm{option list}} *)]{exam-randomizechoices}
+\end{lstlisting}
+
+The package depends on the \texttt{exam} document class being loaded beforehand. If this
+is not the case, the package will throw an error and stops the compilation
+immediately.
+
+
+\subsection{Package options}
+
+The options in \emph{\textrm{option list}} can be any combination of:
+
+\begin{description}[labelindent=2ex]
+\item[randomize] This option globally turns on the randomizing of the choices given for all
+available typesetting environments. Randomization is turned on by default.
+
+\item[norandomize] This option globally turns off the randomizing of the choices for all
+available typesetting environments. This option is useful for inspecting the resulting
+PDF output file with typesetting the choices in the order they were entered.
+
+\item[keeplast] This option globally turns on the preservation of the last entered
+item in the new environments.
+
+\item[nokeeplast] This option globally turns off the preservation of the last entered
+item in the new environments. This is the default behaviour.
+
+\item[overload] This option makes the standard multiple choice environments behave
+the same as the new environment counterparts, i.e.\@ the the standard multiple choice
+environments are overloaded (or redefined). This is useful if you wish to use an old
+exam and randomize the choices of the questions.
+
+\item[nooverload] This option suppresses the overloading of the standard multiple choice
+environments so you have to use the new multiple choice environments if you want to
+randomize the choices to the questions. Overloading is turned off by default.
+
+\item[\texttt{debug}] This option causes the package to emit a lot of debug messages.
+The messages are written to the log file by the \texttt{\bs{PackageWarning}}
+command. Most IDE's, such as TeXMaker, will display the messages in the transcript pane.
+Debug is turned off by default. There is no \texttt{nodebug} option.
+
+\end{description}
+
+If you load the package with no options, it behaves as:
+
+\begin{lstlisting}
+\usepackage[randomize,nokeeplast,nooverload]{exam-randomizechoices}
+\end{lstlisting}
+
+
+\subsection{Overloading the standard multiple choice environments}
+If the package option \texttt{overload} is in effect, the standard multiple choice
+environments are overloaded (or redefined) by the new multiple choice environments,
+i.e. the standard multiple choice environment behave the same as their
+randomizing counterparts. This way the user can typeset old exams or when creating
+an exam from a repository of (old) questions. Please note that the overloaded
+multiple choice environments now accept arguments just as their randomizing
+counterparts do.
+
+
+\subsection{Seeding rhe pseudo random generator}
+\label{sec:seeding}
+To get a consistent randomization, you must seed the pseudo random generator
+with the same seed every time you compile your document. You can set the
+seed using the \texttt{\bs setrandomizerseed} macro. The macro has a mandatory
+argument that is an integer between 0 and $2^{31}-1$, \TeX's largest integer.
+Internally, the PGF macro \texttt{\bs pgfmathsetseed} is called, and it is
+flagged that you applied a seed. If you fail to do so, the seeding value is
+\texttt{\bs time}$\times$\texttt{\bs year} as stated by the PFG manual%
+\footnote{Version 3.0.1a, page 940.}. \LaTeX\ compilers keep track of
+time by an integer that holds the minutes counted since midnight. The integer is
+incremented every time the time passes a minute boundary. So the scenario
+can be that you compile your document a couple of times with no apparent
+differences between runs. But if the time passes a minute boundary, the
+next time you compile your document you'll see that the environment items
+have been rearranged.
+
+\subsection{Printing the key table}
+The package provides the typesetting of a basic key table in vertical direction.
+Please note that only the environments \texttt{randomizechoices},
+\texttt{randomizeoneparchoices}, \texttt{choices} (if overloaded) and
+\texttt{oneparchoices} (if overloaded) can have valid keys in the key table.
+The \texttt{*checkboxes} environments can't 
+have keys because of the typesetting regime used by the \texttt{exam}
+document class. The \texttt{*choices} environments use an internal counter
+to keep track of the choice currently being typeset. Using this counter, a
+label can be provided with a \texttt{\bs label} command.
+The \texttt{*checkboxes} environments don't use an internal counter so 
+labelling them would lead to a reference to the current question (or part,
+or sub part or sub-sub part). Labelling the correct choices (with the
+\texttt{\bs CorrectChoice} command) is automatically handled by the
+package.
+
+At the end of the exam, issue the commands:
+
+\begin{lstlisting}
+\ifprintanswers
+   \printkeytable
+\fi
+\end{lstlisting}
+
+to print the key table. The \texttt{\bs ifprintansers} command is only true if the
+\texttt{exam} document class \texttt{ansers} option is set, thereby preventing
+accidental typesetting the key table. If an correct choice can't be labelled, the
+table entry will contain \textbf{??}, otherwise it will contain the used typesetting scheme
+(which is \texttt{\bs Alph} by default).
+The key table is typeset using the \texttt{tabular}
+environment, so it can be wrapped in a \texttt{table} environment.
+
+An example of a key table is presented below. Note the \textbf{??} in the
+Answer column. This is the result of using the standard multiple choice
+environments (they are not overloaded, so no label is applied).
+
+\printkeytable
+
+The text in the table header row can be changed using two command: the command
+\texttt{\bs keylistquestionname} sets the text above the question numbers, which
+defaults to ``Question'', the command \texttt{\bs keylistkeyname} sets the text
+above the keys, which defaults to ``Key''. A typical use could be:
+
+\begin{lstlisting}
+\keylistquestionname{Exercise}
+\keylistkeyname{Answer Key}
+\end{lstlisting}
+
+\subsection{Writing the keys to a file}
+The package provides the writing of the keys to the file.
+Please note that only the environments \texttt{randomizechoices},
+\texttt{randomizeoneparchoices}, \texttt{choices} (if overloaded) and
+\texttt{oneparchoices} (if overloaded) can have valid keys in the key list.
+
+Writing a key list file is started by the command:
+
+\begin{lstlisting}
+\writekeylist[(*\textsl{\textrm{filename}}*)]{(*\textsl{\textrm{command name}}*)}
+\end{lstlisting}
+
+The optional parameter \emph{filename} is the name of the file. If you don't
+provide a filename, \texttt{\bs jobname.keylist} will be used,
+where \texttt{\bs jobname} is the name of your \LaTeX{} file you are compiling.
+The \emph{command name} is used in the key list file. An example of a key list file
+is presented below. In essence, the file contains a \texttt{\bs gdef} command
+that assigns the key list to the supplied command name (in this case
+\texttt{\bs mykeylist}).
+
+\writekeylist{\mykeylist}
+\vspace*{\baselineskip}
+\lstinputlisting[caption=]{\jobname.keylist}
+
+\vspace*{1.5\baselineskip}
+The key list itself is constructed as a comma-separated list. The question
+number and answer keys are separated with a `/'. This makes it easy to
+parse the list with PGF's \texttt{\bs foreach} command:
+
+\begin{lstlisting}
+\input{\jobname.keylist}
+
+\foreach \num/\key in \mykeylist {
+	\textcolor{red!\num0!blue} {question \num\ has key \key} \\
+}
+\end{lstlisting}
+
+Executing this code results in:
+
+\input{\jobname.keylist}
+
+\foreach \num/\key in \mykeylist {
+	\textcolor{red!\num0!blue} {question \num\ has key \key} \\
+}
+
+The key list file can safely be deleted. It is generated each time the
+\texttt{\bs writekeylist} command is executed. Edits to the file are lost.
+
+\subsection{There should be only one correct answer}
+As stated in the title of this section, each multiple choice question
+should have one, and only one correct answer. The packages issues a
+warning if a question has zero or more than one correct answer, but it
+doesn't stop compilation. If a question has no correct answer there
+will be a \textbf{??} in the printed key table and a ? in the key list
+file. If a question has two or more correct answers, the last correct
+answer being typeset will be printed in the key table and is written to
+the key list file.
+
+Also note that using the \textsl{parts} environment to typeset multiple
+multiple choice questions is not supported because the automatic
+labelling mechanism supports only at the question level.
+
+\subsection{Verbatim environments}
+Verbatim environments such as \texttt{verbatim} and \texttt{lstlistings}
+are currently \emph{not} supported in the new and (overloaded) standard multiple
+choice environments. This is due to the way the contents of these environments
+are collected. The \texttt{\bs verb} command is also not supported by the package
+but \texttt{\bs lstinline} is. An example, translated to English from a Dutch exam
+on the ATmega32 microcontroller chip:
+
+\begin{lstlisting}
+\question[5]
+The individual pins of Port D can be configured as input or output.
+The single bits of Port D are called PD7, PD6, PD5, PD4, PD3, PD2,
+PD1 and PD0. Which of the following alternatives configures PD0, PD1,
+PD6 and PD7 as output and the remaining pins as input?
+
+\begin{randomizechoices}
+\choice \lstinline|out DDRD,0x3c|
+\CorrectChoice \lstinline|ldi r20,0xc3| \par \lstinline|out DDRD,r20|
+\choice \lstinline|out PORTD,0x3c|
+\choice \lstinline|ldi r20,195| \par \lstinline|PORTD,r20|
+\end{randomizechoices}
+\end{lstlisting}
+
+typesets possibly to:
+
+\begin{questions}
+\setlength{\parskip}{0pt}
+\setcounter{question}{8}
+\question[5]
+The individual pins of Port D can be configured as input or output. The single bits
+of Port D are called PD7, PD6, PD5, PD4, PD3, PD2, PD1 and PD0. Which of the
+following alternatives configures PD0, PD1, PD6 and PD7 as output and the remaining
+pins as input?
+
+%%Original Dutch text
+%%De individuele pinnen van Port D kunnen als ingang of uitgang geconfigureerd worden. De
+%%enkelvoudige bits van Port D worden PD7, PD6, PD5, PD4, PD3, PD2, PD1, PD0 genoemd.
+%%Welk van de volgende alternatieven configureert PD0, PD1, PD6 en PD7 als uitgang en de
+%%overige pinnen als ingang?
+%
+%\hspace*{\baselineskip}
+
+\begin{randomizechoices}[norandomize]
+	\choice \lstinline|out DDRD,0x3c|
+	\CorrectChoice \lstinline|ldi r20,0xc3| \par \lstinline|out DDRD,r20|
+    \choice \lstinline|out PORTD,0x3c|
+	\choice \lstinline|ldi r20,195| \par \lstinline|PORTD,r20|
+\end{randomizechoices}
+\end{questions}
+
+\subsection{Accessing the internal labels}
+Each \texttt{\bs question} command is accompanied with a label of the form
+\texttt{question@}$x$ as provided by the \texttt{exam} document class, where
+$x$ is the decimal number of the question. A \texttt{\bs CorrectChoice}
+command is provided with a label (by this package) of the form \linebreak \texttt{question@}$x$%
+\texttt{@correctchoice} where $x$ is again the decimal number of the question.
+The user can access these labels by using the \texttt{\bs ref} command as shown
+below:
+
+\begin{lstlisting}
+The question number is~\ref{question@9} and the correct answer
+is~\ref{question@9@correctchoice}.
+\end{lstlisting}
+
+which typesets to:
+
+The question number is~\ref{question@9} and the correct answer
+is~\ref{question@9@correctchoice}.
+
+There is no need to change the cat code of `@'.
+
+\subsection{Error messages}
+The package will throw you some error messages in case something is wrong. The
+message below is printed only at start up.
+
+\begin{description}[labelindent=2ex]
+\item[\texttt{The exam class is not loaded. Emergency stop!}] --- You didn't load
+the \texttt{exam} document class prior to loading the package. As a result of that,
+the package can't continue and stops compiling your document. Note that a document
+class can be based on the \texttt{exam} document class and will load it for you.
+
+\end{description}
+
+The next messages will only be printed if the new multiple choice environments
+are used \emph{or} if the standard multiple choice environments are used when
+overloaded: 
+
+\begin{description}
+\item[\texttt{You should NOT define \string\inaccessible. Emergency stop!}] ---
+The packages relies on the fact that \texttt{\bs inaccessible} is not defined. It is
+used by the list parser to designate \texttt{\bs CorrectChoice} and
+\texttt{\bs correctchoice}. Normally, a user doesn't define this command.
+As a result of that, the package can't continue and stops compiling your document.
+
+%% Next two are turned into warningz
+%%%\item[\texttt{You need exactly one \string\CorrectChoice, I found} $x$
+%%%      \texttt{in question} $y$] --- You should provide only one correct
+%%%answer in a multiple choice question. Compilation does continue.
+%%%
+%%%\item[\texttt{You need at least two choices in question} $x$] --- You didn't
+%%%provide two or more choices, so there's nothing to choose from. Compilation
+%%%does continue.     
+
+\item[\texttt{Something's wrong, perhaps a missing \string\choice\ or \string\CorrectChoice\ or ...}] --- You used text before an initial \texttt{\bs choice}, \texttt{\bs CorrectChoice}
+or \texttt{\bs correctchoice}. Analogue to the famous missing \texttt{\bs item} messages.
+Compilation does continue.
+ 
+\item[\texttt{Cannot write key list file}] --- Writing of files is disabled so the key list file can't be generated. Compilation does continue.
+ 
+\end{description}
+
+
+
+\section{Some internal details of the package}
+This section provides some internal details on the operation of the package.
+
+\subsection{Used packages}
+The package loads the following packages:
+
+\begin{description}[labelindent=2ex]
+\item[\texttt{environ}] This package is used for defining the new environments. It provides
+the powerful \texttt{NewEnviron} and \texttt{RenewEnviron} commands.
+\item[\texttt{etoolbox}] This package provides some useful commands, notably on the parsing of lists.
+\item[\texttt{pgffor}] This package provides the powerful \texttt{\bs foreach} loop
+construct. In turn, this package loads the \texttt{pgfmath} package which supplies
+the \texttt{\bs pgfmathsetseed} and \linebreak \texttt{\bs pgfmathrandominteger} commands.
+\end{description}
+
+\subsection{Defining the \texttt{randomize*} environments}
+Defining the \texttt{randomize*} environments is done with the \texttt{NewEnviron}
+and \texttt{RenewEnviron} commands. As an example we discuss the
+\texttt{randomizechoices} environment.
+
+We define this environment as follows (not overloaded):
+
+\begin{lstlisting}
+\NewEnviron{randomizechoices}[1][]{
+  %%
+  %% Create a random list
+  \erc@createrandomlist[#1]%
+  %%
+  %% Start the choices environment
+  \begin{choices}%
+    % Execute the list
+    \erc@typesetchoices%
+  \end{choices}%
+}
+\end{lstlisting}
+
+Now the \texttt{NewEnviron} command has a very useful property in that
+when expanded it places its content in the command \texttt{\bs BODY}.
+So when the environment is used as in:
+
+\begin{lstlisting}
+\begin{randomizechoices}
+\choice one
+\choice two
+\CorrectChoice three
+\choice four
+\end{randomizechoices
+\end{lstlisting}
+
+the \texttt{\bs BODY} command now contains (comments and newlines are stripped):
+
+\begin{lstlisting}
+\choice one \choice two \CorrectChoice three \choice four
+\end{lstlisting}
+
+Using the command as in:
+
+\begin{lstlisting}
+\BODY
+\end{lstlisting}
+
+simply expands the command. Now all the \texttt{randomize*} environments
+are defined this way, so we need a generic command that parses \texttt{\bs BODY} and
+provides a command that contains the randomized version of \texttt{\bs BODY}. This is
+handled by the command \texttt{\bs erc@createrandomlist}. What \texttt{\bs erc@createrandomlist}
+basically does is:
+
+\begin{enumerate}
+\item Parses the supplied options and sets internal flags for later use.
+\item Replaces every occurrence of \texttt{\bs CorrectChoice} and
+      \texttt{\bs correctchoice} in \texttt{\bs BODY} 
+      with \texttt{\bs choice \bs inaccessible}.
+\item Disassembles \texttt{\bs BODY} into a set of commands by splitting on the list
+      separator \texttt{\bs choice}. \texttt{\bs choice} is removed.
+\item Randomizes the order of the set of commands.
+\item Assembles the set of commands to the new command \texttt{\bs erc@typesetchoices},
+      thereby appending a \texttt{\bs label} to the correct choice. The ``command''
+      \texttt{\bs inaccessible} is replaced by \texttt{\bs CorrectChoice}. The
+      other commands are prepended with \texttt{\bs choice}.
+\end{enumerate}
+
+Of course this behaviour can be altered by options. For example, if the option
+\texttt{norandomize} is passed, \texttt{\bs BODY} is not randomized but labelling still
+takes place.
+
+Please note: We need to replace \texttt{\bs CorrectChoice} with \texttt{\bs choice \bs inaccessible}
+because the list parser can only handle one list separator at a time. The very misunderstood command
+\texttt{\bs inaccessible}\footnote{This sequence of characters sometimes appear in error messages
+generated by \LaTeX.} is likely not to be entered by the user but if the user enters \texttt{\bs inaccessible}
+directly after a \texttt{\bs choice} command, this is converted to \texttt{\bs CorrectChoice}
+in step 5. Of course this is not a bug, but a feature.
+
+After \texttt{\bs erc@createrandomlist} has done it's job, the command \texttt{\bs erc@typesetchoices}
+is simply expanded within a \texttt{choices} environment.
+
+Now if the global \texttt{overload} option is in effect, some more trickery is needed. First, a copy
+of the \texttt{choices} environment is created using \texttt{\bs let}:
+
+\begin{lstlisting}
+%% Save choices environment
+\let\@oldchoices\choices
+\let\end@oldchoices\endchoices
+\end{lstlisting}
+
+Using \texttt{\bs let} doesn't create problems, because the \texttt{choices} environment
+doesn't support options. See \url{https://tex.stackexchange.com/questions/116670/}.
+Next, the \texttt{\bs choices} environment is redefined:
+
+\begin{lstlisting}
+%% Renew the choices environment
+\RenewEnviron{choices}[1][]{
+
+  %% Create a random list
+  \erc@createrandomlist[#1]
+
+  %% Start the choices environment
+  \begin{@oldchoices}
+     % Execute the list
+     \erc@typesetchoices
+  \end{@oldchoices}
+}
+\end{lstlisting}
+
+Note that now the \texttt{\bs choices} environment can handle the same options as the
+\texttt{randomizechoices} environment.
+
+\subsection{Note on the key table}
+The code of the key table is first collected using a series of \texttt{\bs gappto} and
+\texttt{\bs xappto} commands. Using these commands is far more easy then typesetting it
+directly from the package. See \url{https://tex.stackexchange.com/questions/367979/}
+why. Notably the use of \texttt{\bs begin}, \texttt{\bs foreach} and \texttt{\bs hline}
+is problematic.
+
+\subsection{Verbatim environments}
+Verbatim environments are currently not supported. This is due to the way \texttt{\bs NewEviron}
+collects its contents. A \texttt{\bs NewEnviron} is not really an environment at all, but a
+command. One solution is to write the contents to a file and then include the file. This is
+being investigated. See
+% \url{https://tex.stackexchange.com/questions/51239/verbatim-in-environ-s-body}.
+\url{https://tex.stackexchange.com/questions/51239/}.
+
+Also the \texttt{\bs verb} command is not supported, but \texttt{\bs lstinline} is.
+
+\section{A personal note}
+I've been using the \texttt{exam} document class for five years now. What I like most
+is the consistent typesetting of my exams. I don't use sub parts and sub-sub parts
+because in my opinion this not the right way to prepare an exam. I've written a
+department consistent class that provides the department's cover pages and some
+other typesetting trickery. This class is used by a small core \TeX\ users. Regrettably,
+the majority of my colleagues use Word *cough*.
+
+\end{document}
\ No newline at end of file
-- 
cgit v1.2.3

