From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining 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