Debian Codegraph @

texmf-dist/source/latex/examz/examz.dtx

raw
1 % \iffalse meta-comment
2 %
3 % `examz' --- 2023/06/07 Version 1.0.0
4 %
5 % Copyright (C) 2023 by Christopher McClain
6 % E-mail: [email protected]
7 % -----------------------------------------
8 %
9 % This file may be distributed and/or modified under the
10 % conditions of the LaTeX Project Public License, either
11 % version 1.3c of this license or (at your option) any later
12 % version. The latest version of this license is in:
13 %
14 % http://www.latex-project.org/lppl.txt
15 %
16 % and version 1.3 or later is part of all distributions of
17 % LaTeX version 2008 or later.
18 %
19 % \fi
20 %
21 % \iffalse
22 %<*driver>
23 \ProvidesFile{examz.dtx}
24 %</driver>
25 %<class>\NeedsTeXFormat{LaTeX2e}
26 %<class>\ProvidesClass{examz}
27 %<*class>
28 [2023/06/07 v1.0.0 Randomized exams with multiple versions]
29 %</class>
30 %
31 %<*driver>
32 \documentclass{ltxdoc}
33 \usepackage[numbered]{hypdoc}
34 \EnableCrossrefs
35 \CodelineIndex
36 \RecordChanges
37 \begin{document}
38 \DocInput{examz.dtx}
39 \end{document}
40 %</driver>
41 % \fi
42 %
43 % \changes{v1.0.0}{2023/06/07}{First public release}
44 %
45 % \GetFileInfo{examz.dtx}
46 %
47 % \DoNotIndex{\addtocounter,\arabic,\AtBeginDocument,\AtEndDocument,\begin,
48 % \BODY,\boolfalse,\booltrue,\chk@incompi,\clearcounterprefix,
49 % \Collect@Body,\counterprefix,\CurrentOption,\DeclareOption,
50 % \decr@latest@ques,\end,\endcoverpages,\find@latestques,\ifbool,
51 % \ifnumequal,\ifnumless,\ifnumodd,\ifrandomizectr,\input,
52 % \inputcountersfile,\LoadClass,\newbool,\newcommand,\newcounter,
53 % \NewEnviron,\newenvironment,\newpage,\noprintanswers,
54 % \norandomizectr,\notbool,\null,\opencountersfile,\parts,
55 % \PassOptionsToClass,\printanswers,\ProcessOptions,\question,
56 % \questions,\randomizectr,\refto@index,\relax,\renewcommand,
57 % \RequirePackage,\savecounter,\setcounter,\setcounterprefix,
58 % \setup@point@toks,\space,\subparts,\subsubparts,\thispagestyle,
59 % \typein,\typeout,\value,\whileboolexpr,\xpatchcmd,
60 % \xrandprovidecounter,\xvalue,\hrulefill,\makebox,\EnterResponse,
61 % \NumberOfVersions,\endinput}
62 %
63 % \title{^^A
64 % The \textsf{examz} class\thanks{^^A
65 % This file describes version \fileversion, last revised \filedate.^^A
66 % }^^A
67 % }
68 % \author{^^A
69 % Christopher McClain\thanks{E-mail: [email protected]}^^A
70 % }
71 %
72 % \date{Released \filedate}
73 %
74 % \maketitle
75 %
76 %\begin{abstract}
77 % The \textsf{examz} document class builds on the \textsf{exam} document class
78 % that was developed by Philip S. Hirschhorn. An author may use the class
79 % exactly as the \textsf{exam} class, but there are also additional features.
80 % The document class facilitates the writing of questions with random elements,
81 % the creation of multiple versions of an exam, and the use of separate files
82 % as question banks.
83 %\end{abstract}
84 %
85 %\tableofcontents
86 %
87 %\section{Introduction}
88 %
89 %\subsection{About}
90 %
91 % Since 1994, Philip Hirschhorn's \textsf{exam} document class has provided
92 % authors and educators with a framework for writing exams that is both highly
93 % customizable and easy to use. The \textsf{examz} document class loads the
94 % \textsf{exam} class and adds some more features. Most of these new features
95 % require the \textsf{counterz} package.
96 %
97 % First of all, the \textsf{examz} class may be loaded with new options that
98 % facilitate the use of commands from the \textsf{counterz} package for writing
99 % questions with random elements. Second, a new \textsf{versions} environment
100 % allows for the creation of multiple versions of an exam in the same document,
101 % alternating between exams and solutions, if desired. Third, the command
102 % \cs{question} may now be replaced by the command \cs{questionfrombank} which
103 % allows for random selection of questions from a user-defined question bank.
104 % Finally, a few simple macros make it even easier to modify the customized
105 % content in headers, footers, and special pages when creating new exams from
106 % previous documents.
107 %
108 % Some commands in \textsf{exam} have been patched in order to distinctly label
109 % the questions in different exam versions and their solutions (so that \LaTeX{}
110 % issues no warnings about multiply-defined labels). The optional environment
111 % \textsf{coverpages} has also been patched for two-sided documents so that the
112 % subsequent odd arabic numerals always appear on the front pages.
113 %
114 %\subsection{License}
115 %
116 % Copyright \copyright\ 2023 Christopher McClain. This software may be copied,
117 % distributed, and/or modified under the %terms of the
118 % \href{https://www.latex-project.org/lppl/}{LaTeX Project Public License},
119 % either version 1.3c of this license or any later version.
120 %
121 %\subsection{Installation}
122 %
123 % Run \LaTeX{} on examz.ins to generate the file examz.cls, and copy it to
124 % your local texmf directory. Run (pdf)\LaTeX{} on examz.dtx to generate the
125 % documentation examz.pdf. Typesetting the documentation requires the package
126 % \textsf{hypdoc} which is included in \TeX\ distributions and at
127 % \href{http://www.ctan.org} {The Comprehensive TeX Archive Network}.
128 %
129 %\section{User Guide}
130 %
131 % To use this document class, begin your document with the following line:
132 %
133 %\begin{verbatim}
134 %\documentclass{examz}
135 %\end{verbatim}
136 %
137 % \noindent
138 % This document class loads the \textsf{exam} class and admits the options for
139 % that class. See the documentation for the \textsf{exam} class for details. The
140 % \textsf{examz} class also admits the additional options \textsf{randomize},
141 % \textsf{norandomize}, \textsf{prompt}, and \textsf{complete}, all of which are
142 % discussed in this guide. This document class requires the \textsf{counterz}
143 % package, which is available at \href{http://www.ctan.org}
144 % {The Comprehensive TeX Archive Network}.
145 %
146 % In addition to its parent class \textsf{exam} and the \textsf{counterz}
147 % package, the \textsf{examz} class requires the following packages:
148 % \textsf{xparse}, \textsf{environ}, \textsf{etoolbox}, and \textsf{makecmds}
149 % (the latter two via \textsf{counterz}), all of which are included in most
150 % standard \TeX\ distributions and at \href{http://www.ctan.org}{The
151 % Comprehensive TeX Archive Network}.
152 %
153 %\subsection{Randomized Exams}\label{usr:versions}
154 %
155 % The \textsf{examz} class loads the \textsf{counterz} package which provides
156 % commands for generating, saving, recalling, manipulating, and displaying
157 % random values for counters. These commands may be incorporated into questions
158 % to generate random exams. The process of saving and recalling counters may be
159 % explicitly coded in the document, as described in the \textsf{counterz}
160 % package documentation, but the \textsf{examz} class may instead be loaded with
161 % options to automate this process.
162 %
163 % Loading the class with the option \textsf{randomize} will execute the commands
164 % \cs{randomizectr} and \cs{opencountersfile} from the \textsf{counterz}
165 % package. Loading the class with the option \textsf{norandomize} will execute
166 % the commands \cs{norandomizectr} and \cs{inputcountersfile}. If neither of
167 % these options are loaded, the default behavior is that of the option
168 % \textsf{randomize}. The reason for this is that if the document contains no
169 % randomly generated counters then this default choice will have no effect
170 % anyway, and if the document does contain randomly generated counters then the
171 % first typesetting must generate these counter values.
172 %
173 % A third option \textsf{prompt} frees the user from the burden of manually
174 % changing between \textsf{randomize} and \textsf{nonrandomize} and also
175 % protects against accidental overwriting of previously generated counter
176 % values. This option will execute the command \cs{promptrandomexam}, which
177 % is an instance of the command \cs{promptrandomizectr} from the
178 % \textsf{counterz} package, followed by one of the commands
179 % \cs{opencountersfile} or \cs{inputcountersfile} as appropriate. The terminal
180 % dialogue of \cs{promptrandomexam} can be changed with the use of
181 % \cs{renewcommand}, if desired. (See Section \ref{imp} for the implementation
182 % of \cs{promptrandomexam}.) There are additional effects from this option with
183 % regard to the \textsf{versions} environment, described below.
184 %
185 % \DescribeEnv{versions}
186 % The \textsf{versions} environment uses a loop and a counter \textit{version}
187 % to generate versions of the exam, incrementing the counter and updating the
188 % page numbers along the way. The version number may be displayed in headers or
189 % elsewhere with either \cs{theversion} or \cs{arabic}\{version\}. The
190 % environment takes an optional argument: the number of desired versions, with
191 % 1 being the default value. The environment is used as follows:
192 %
193 %\begin{verbatim}
194 %\begin{versions}[<optional number>]
195 % <exam content here>
196 %\end{versions}
197 %\end{verbatim}
198 %
199 %\noindent
200 % where \textit{exam content} refers to the \textsf{questions} environment (as
201 % defined in the \textsf{exam} package), cover pages, and anything else after
202 % \cs{begin}\{document\} that is intended to appear in the exam. When the class
203 % is randomized with the option \textsf{prompt}, the number provided by the
204 % optional argument is not used, and so there is no reason to include it.
205 % Instead, a command \cs{promptversions} inputs the number of versions using a
206 % terminal dialogue. (The dialogue can be changed by using \cs{renewcommand},
207 % if desired. See Section \ref{imp:versions} for the implementation of
208 % \cs{promptversions}.) When the exam is not randomized, the number of versions
209 % is inputted from the previously generated counters file, and so the prompt
210 % does not appear.
211 %
212 % Recall that the \textsf{examz} class inherits the options \textsf{answers}
213 % and \textsf{noanswers} from the \textsf{exam} class. The \textsf{examz} class
214 % also has an additional option called \textsf{complete}. When loaded with this
215 % option, the document alternately prints without and with solutions. (Note:
216 % This feature only takes effect when using the \textsf{versions} environment.)
217 % Moreover, when the class is loaded with the option \textsf{twoside} (inherited
218 % from its grandparent class \textsf{article}), an extra blank page is inserted
219 % at the end of each exam when necessary to ensure that the next exam starts on
220 % a front page. An exam that begins with the line
221 %
222 %\begin{verbatim}
223 %\documentclass{11pt,twoside,addpoints,prompt,complete}
224 %\end{verbatim}
225 %
226 %\noindent
227 % and uses the \textsf{versions} environment, for example, will ask the user
228 % whether to randomize, and if so, how many versions to print. Then the typeset
229 % document will include the requested number of versions, alternating between
230 % exams and solutions, with correct grade tables and no warnings about
231 % multiply-defined labels, and an extra blank page whenever an exam has an odd
232 % number of pages.
233 %
234 %\subsection{Question Banks}\label{usr:banks}
235 %
236 % Within the \textsf{questions} environment, the \textsf{examz} package offers
237 % an alternative to the command \cs{question} that allows for the random
238 % selection of a question from a question bank. The command
239 % \DescribeMacro{\questionfrombank}
240 % \cs{questionfrombank}\oarg{points}\marg{filename} has two arguments, the first
241 % of which is optional. The first (optional) argument is the point value of the
242 % question, just as with the command \cs{question} from the \textsf{exam} class.
243 % The second argument is the name of a \TeX{} file (without the .tex extension).
244 % The second argument may include a path. Suppose, for example, that the
245 % directory which contains the main exam document \textsf{Test1.tex} also
246 % contains a subdirectory named \textsf{Problems} containing the files
247 % \textsf{Solve\_Linear\_Equation.tex} and \textsf{State\_Capitals.tex}. Then
248 % the code
249 %
250 %
251 %\begin{verbatim}
252 %\documentclass{examz}
253 %\begin{document}
254 %\begin{questions}
255 % \questionfrombank{Problems/Solve_Linear_Equation}
256 % \questionfrombank{Problems/State_Capitals}
257 %\end{questions}
258 %\end{document}
259 %\end{verbatim}
260 %
261 %\noindent
262 % generates an exam with two questions, one randomly selected from each of the
263 % two specified files.
264 %
265 % When several files are contained in the same directory, the repetition of the
266 % \DescribeMacro{\setquestionpath}
267 % path name can be reduced by the command \cs{setquestionpath}\marg{path name},
268 % as illustrated by the following code:
269 %
270 %\begin{verbatim}
271 %\documentclass{examz}
272 %\begin{document}
273 % \setquestionpath{Problems/}
274 %\begin{questions}
275 % \questionfrombank{Solve_Linear_Equation}
276 % \questionfrombank{State_Capitals}
277 %\end{questions}
278 %\end{document}
279 %\end{verbatim}
280 %
281 % \noindent
282 % The command \cs{setquestionpath} can be used both inside and outside of the
283 % \textsf{questions} environment, and can be used to change the path multiple
284 % times, if desired.
285 %
286 % In order for a file to function as a question bank, it must conform to a
287 % specific (but very simple) structure. First of all, every question bank file
288 % begins with a command \cs{setnumberofquestions}\marg{number}. Second, all of
289 % \DescribeMacro{\setnumberofquestions}
290 % the questions are contained within a \textsf{questionbank} environment. Third,
291 % each individual question is contained within a \textsf{qbitem} environment.
292 % This structure is exhibited by the following code, which could be the entire
293 % contents of a file \textsf{State\_Capitals.tex} inputted by the command \cs{questionfrombank}:
294 %
295 %\begin{verbatim}
296 %\setnumberofquestions{2}
297 %\begin{questionbank}
298 %\begin{qbitem}{1}
299 % What is the capital of Maine?
300 %\end{qbitem}
301 %\begin{qbitem}{2}
302 % What is the capital of Nebraska?
303 %\end{qbitem}
304 %\end{questionbank}
305 %\end{verbatim}
306 %
307 % \DescribeEnv{questionbank}
308 % The \textsf{questionbank} environment randomly generates an integer between 1
309 % and the number specified in the preceding command \cs{setnumberofquestions}.
310 % Each instance of the environment \textsf{qbitem}\marg{item number} compares
311 % \DescribeEnv{qbitem}
312 % its numerical argument \meta{item number} to this randomly generated number
313 % and executes the environment's body of content only if the numbers match. Then
314 % the \textsf{questionbank} environment ends input so that nothing in the file
315 % after that environment will be included. Note that neither environment
316 % includes within its body the \cs{question} command; that command is already
317 % part of the command \cs{questionfrombank} which inputs the file. Also note
318 % that \cs{questionfrombank} sets the counter prefix to include the file name
319 % and exam version number, so authors should use the prefix versions of counters
320 % commands (e.g. \cs{xprovidecounter}, \cs{xarabic}, etc.) within
321 % \textsf{qbitem} environments. (See the \textsf{counterz} documentation for
322 % details.)
323 %
324 % The \textsf{qbitem} environment allows for the inclusion of the various
325 % environments for parts and solutions that are provided by the \textsf{exam}
326 % class. Recall that each of the six solutions environments admits an argument
327 % to specify the amount of solution space. (The argument is optional for all
328 % except \textsf{solutionbox}. See the \textsf{exam} documentation for details.)
329 % The \textsf{examz} class offers a command \cs{setsolutionspace}\marg{length}
330 % \DescribeMacro{\setsolutionspace} and six analogous solutions environments
331 % that pass \meta{length} to their \textsf{exam} counterparts. For example, the
332 % \DescribeEnv{qbsolution}
333 % environment \textsf{qbsolution} is equivalent to the environment
334 % \textsf{solution}\oarg{length}. The advantage of this is that the command
335 % \cs{setsolutionspace}\marg{length} can be included once in the file, above the
336 % \textsf{questionbank} environment, for example, and any subsequent adjustment
337 % of the length can be done for all of the question bank items simultaneously
338 % with a single edit rather than a comprehensive search and replace. Five other
339 % environments \textsf{qbsolutionbox}, \textsf{qbsolutionorbox},
340 % \DescribeEnv{qbsolutionbox}
341 % \textsf{qbsolutionorlines}, \textsf{qbsolutionordottedlines}, and finally
342 % \DescribeEnv{qbsolutionorbox}
343 % \textsf{qbsolutionorgrid} are similar analogues of the other \textsf{exam}
344 % class solutions environments. Just as their \textsf{exam} counterparts, these
345 % \DescribeEnv{qbsolutionorlines}
346 % environments can also be used within the \textsf{parts} environment. The
347 % \DescribeEnv{qbsolutionordottedlines}
348 % command \cs{setsolutionspace} may be used multiple times in the same file,
349 % \DescribeEnv{qbsolutionorgrid}
350 % including within the \textsf{questionbank} environment, if necessary.
351 %
352 %\subsection{Customization Macros}
353 %
354 % The \textsf{exam} document class provides the means for customizing headers,
355 % footers, special pages, etc. As an exam author makes changes to a document
356 % between exams, courses, or academic terms, the author may require frequent
357 % adjustment of certain standard content, such as the name of the exam or course
358 % in a custom header. The \textsf{examz} document class offers several macros to
359 % simplify such changes. For example, instead of explicitly including the text
360 % ``MATH 101'' in a header, an author can use the macro \cs{coursename} which
361 % can be set (and easily modified) at the beginning of the document. This is
362 % especially useful when designing for many similar courses a custom
363 % \textsf{.cls} file that loads the \textsf{examz} class and keeps the layout
364 % and customizations ``behind the scenes''. We first list and describe these
365 % macros and then provide an example of usage.
366 %
367 % \medskip
368 % \noindent
369 % \DescribeMacro{\instructorname}
370 % The default replacement text for \cs{instructorname} is ``Instructor Name''.
371 %
372 % \noindent
373 % \DescribeMacro{\setinstructorname}
374 % Use the command \cs{setinstructorname}\marg{text} to change this text.
375 %
376 % \medskip
377 % \noindent
378 % \DescribeMacro{\coursename}
379 % The default replacement text for \cs{coursename} is ``Course Name''.
380 %
381 % \noindent
382 % \DescribeMacro{\setcoursename}
383 % Use the command \cs{setcoursename}\marg{text} to change this text.
384 %
385 % \medskip
386 % \noindent
387 % \DescribeMacro{\examname}
388 % The default replacement text for \cs{examname} is ``Exam Name''.
389 %
390 % \noindent
391 % \DescribeMacro{\setexamname}
392 % Use the command \cs{setexamname}\marg{text} to change this text.
393 %
394 % \medskip
395 % \noindent
396 % \DescribeMacro{\termname}
397 % The default replacement text for \cs{termname} is ``Term Name''.
398 %
399 % \noindent
400 % \DescribeMacro{\settermname}
401 % Use the command \cs{settermname}\marg{text} to change this text.
402 %
403 % \medskip
404 % \noindent
405 % \DescribeMacro{\namespace}
406 % The default expansion of \cs{namespace} is
407 % ``Name:~\makebox[5cm]{\hrulefill}'' which is given by the code
408 % \texttt{Name:$\sim$\cs{makebox}[5cm]\{\cs{hrulefill}\}}.
409 %
410 % \noindent
411 % \DescribeMacro{\setnamespace}
412 % Use the command \cs{setnamespace}\marg{format} to change this format.
413 %
414 % \medskip
415 % \noindent
416 %\DescribeMacro{\instructions}
417 % The default replacement text for \cs{instructions} is ``Instructions Here''.
418 %
419 % \noindent
420 % \DescribeMacro{\setinstructions}
421 % Use the command \cs{setinstructions}\marg{text} to change this text, including
422 % one or more paragraphs as needed.
423 %
424 % \medskip
425 % \noindent
426 % \DescribeMacro{\covernoanswers}
427 % The command \cs{covernoanswers} can be used within the \textsf{coverpages}
428 % environment provided by the \textsf{exam} class or simply as the first page(s)
429 % of the exam. Its default expansion is empty.
430 % \DescribeMacro{\setcovernoanswers}
431 % Use the command \cs{setcovernoanswers}\marg{format} to change this format to
432 % include special headers and footers, instructions, grade/point tables, an
433 % instance of \cs{newpage}, etc.
434 %
435 % \medskip
436 % \noindent
437 % \DescribeMacro{\coveranswers}
438 % The command \cs{coveranswers} can be used within the \textsf{coverpages}
439 % environment provided by the \textsf{exam} class or simply as the first page(s)
440 % of the exam. Its default expansion is \cs{covernoanswers}.
441 % \DescribeMacro{\setcoveranswers}
442 % Use the command \cs{setcoveranswers}\marg{format} to change this format to
443 % include special headers and footers, instructions, grade/point tables, an
444 % instance of \cs{newpage}, etc.
445 %
446 % \medskip
447 % \noindent
448 % \DescribeMacro{\printcover}%
449 % The command \cs{printcover} executes either \cs{coveranswers} or
450 % \cs{covernoanswers}, depending on the value of the boolean
451 % \textsf{printanswers}. It can be used within the \textsf{coverpages}
452 % environment that is provided by the \textsf{exam} class or simply as the first
453 % page(s) of the exam.
454 %
455 % \medskip
456 % \noindent
457 %\DescribeMacro{\workspace}
458 % The command \cs{workspace} is intended to provide additional work space on the
459 % exam, perhaps at the end of the questions. Its default expansion is empty. Use
460 % the command \cs{setworkspace}\marg{format} to add a bit of text, \cs{newpage},
461 % \DescribeMacro{\setworkspace}
462 % or a custom header/footer. To include the content of \cs{workspace} only when
463 % the boolean \textsf{printanswers} is FALSE, use the command
464 % \DescribeMacro{\printworkspace}
465 % \cs{printworkspace}.
466 %
467 % \medskip
468 % One method of streamlining the work of developing many exams that use the same
469 % layout and format is to write a simple \textsf{.cls} file to use as a custom
470 % instantiation of the \textsf{examz} document class, perhaps even including
471 % frequently used packages:
472 %
473 %\begin{verbatim}
474 %\NeedsTeXFormat{LaTeX2e}
475 %\ProvidesClass{MYexamz}
476 %\DeclareOption*{\PassOptionsToClass{\CurrentOption}{examz}}
477 %\ProcessOptions\relax
478 %\LoadClass{examz}
479 %\RequirePackage{mathtools,amssymb}
480 %\pagestyle{headandfoot}
481 %\header{\coursename}{\examname}{termname}
482 %\setcovernoanswers{%
483 % \namespace
484 %
485 % \bigskip
486 % \instructions
487 %
488 % \bigskip
489 % \gradetable
490 %
491 % \firstpagefooter{Version \arabic{version}}{}{}
492 % \newpage
493 %}%
494 %\setworkspace{%
495 % \newpage
496 % \begin{center} Extra Work Space \end{center}
497 % \newpage
498 %}%
499 %\endinput
500 %\end{verbatim}
501 %
502 % \noindent
503 % Then use the custom document class \textsf{MYexamz} for the exam:
504 %
505 %\begin{verbatim}
506 %\documentclass[addpoints,prompt,complete]{MYexamz}
507 %
508 %\setcoursename{MATH 101}
509 %\setexamname{Test 1}
510 %\settermname{Spring 2023}
511 %\setinstructions{%
512 % Read each problem carefully. Show all work.
513 %}%
514 %
515 %\begin{document}
516 %\begin{versions}
517 % \printcover
518 % \setquestionpath{Problems/}
519 %\begin{questions}
520 % \questionfrombank{Solve_Linear_Equation}
521 % \questionfrombank{State_Capitals}
522 %\end{questions}
523 % \printworkspace
524 %\end{versions}
525 %\end{document}
526 %\end{verbatim}
527 %
528 % To write a new exam Test 2 in the same course, simply change the argument of
529 % \cs{setexamname} from \texttt{Test 1} to \texttt{Test 2} and use the
530 % appropriate question banks. With random counters and well-developed question
531 % banks, writing exams for the next term may be as simple as changing the
532 % term name.
533 %
534 %\StopEventually{^^A
535 % \PrintChanges
536 % \PrintIndex
537 %}
538 %
539 %\section{Implementation}\label{imp}
540 %
541 % The \textsf{examz} document class requires the packages \textsf{environ}, \textsf{xpatch}, and \textsf{counterz}, the last of which also loads the
542 % packages \textsf{etoolbox} and \textsf{makecmds}.
543 %
544 % \begin{macrocode}
545 \RequirePackage{environ}
546 \RequirePackage{xpatch}
547 \RequirePackage{counterz}
548 % \end{macrocode}
549 %
550 % This class inherits all of the options available to the \textsf{exam} class,
551 % including \textsf{answers}, \textsf{noanswers}, \textsf{cancelspace},
552 % \textsf{nocancelspace}, and \textsf{addpoints}. The class also admits
553 % several additional options, the first of which is called \textsf{complete}.
554 % This option takes effect only when using the \textsf{versions} environment
555 % (see Section \ref{imp:versions}) and will otherwise be ignored. With this
556 % option selected, the document alternately prints each exam version with and
557 % without its solutions. The default value of the associated boolean variable
558 % is FALSE. Loading the option \textsf{complete} will change this value to TRUE.
559 % This option is intended to take the place of the options \textsf{answers} and
560 % \textsf{noanswers} and will override these two options if engaged.
561 %
562 % \begin{macrocode}
563 \newbool{@examz@complete}
564 \boolfalse{@examz@complete}
565 \DeclareOption{complete}{\booltrue{@examz@complete}}
566 % \end{macrocode}
567 %
568 % Additional options are based on features of the \textsf{counterz} package. The
569 % option \textsf{randomize} will cause the command \cs{randprovidecounter} (and
570 % its derivative commands) to generate new random values whereas the option
571 % \textsf{norandomize} will cause these commands to input their values from a
572 % file. Because this file may not exist before a first typesetting, the default
573 % option is \textsf{randomize}.
574 %
575 % \begin{macrocode}
576 \randomizectr
577 \DeclareOption{randomize}{\randomizectr}
578 \DeclareOption{norandomize}{\norandomizectr}
579 % \end{macrocode}
580 %
581 %
582 % Finally, the class may be loaded with an option called \textsf{prompt}.
583 % Because the manual change of the option \textsf{randomize} may be forgotten,
584 % resulting in the loss of counter values, the option \textsf{prompt} offers a
585 % terminal-based dialogue through which randomization can be decided. This
586 % action, which is executed at the beginning of the document (see below) is
587 % based on the command \cs{promptranomizectr} from the \textsf{counterz}
588 % package.
589 %
590 % \begin{macrocode}
591 \newbool{@examz@prompt}
592 \boolfalse{@examz@prompt}
593 \DeclareOption{prompt}{\booltrue{@examz@prompt}}
594 \newcommand{\promptrandomexam}{%
595 \promptrandomizectr[\EnterResponse]{%
596 ^^J Enter 1 to randomize document.
597 ^^J Enter 2 to update without new randomization.
598 }{%
599 1%
600 }%
601 }%
602 % \end{macrocode}
603 %
604 % We now load the \textsf{exam} document class with all of these options.
605 %
606 % \begin{macrocode}
607 \DeclareOption*{%
608 \PassOptionsToClass{\CurrentOption}{exam}
609 }%
610 \ProcessOptions\relax
611 \LoadClass{exam}
612 % \end{macrocode}
613 %
614 % Next, we patch the \textsf{coverpages} environment. If the document is loaded
615 % with the option \textsf{twoside} (passed from the \textsf{article} class) and
616 % the \textsf{coverpages} environment produces an odd number of pages, then an
617 % extra blank page is inserted so that the odd arabic page numerals appear on
618 % the right page (i.e. front of the page).
619 %
620 % \begin{macrocode}
621 \xpatchcmd{\endcoverpages}{\setcounter{num@coverpages}{\value{page}}}{%
622 \ifbool{@twoside}{%
623 \ifnumodd{\value{page}}{%
624 % Do Nothing
625 }{%
626 \newpage
627 \null
628 \newpage
629 }%
630 }{%
631 % Do nothing
632 }%
633 \setcounter{num@coverpages}{\value{page}}%
634 }{}{}%
635 % \end{macrocode}
636 % If the class is loaded with the option \textsf{prompt} then we execute the
637 % command \cs{promptrandomexam}. If the user elects to not randomize the
638 % document, either by terminal input via \cs{promptrandomexam} or by instead
639 % loading the \textsf{norandomize} option, then we execute the command
640 % \cs{inputcountersfile}. (Note that this will produce an error if no counters
641 % file exists, so this option should not be used for a first typesetting.) If
642 % the user does elect to randomize the document, by terminal input or by loading
643 % the class with the option \textsf{randomize} or by loading the class with none
644 % of the options \textsf{randomize}, \textsf{norandomize}, or \textsf{prompt},
645 % then we execute the command \cs{opencountersfile}.
646 %
647 % \begin{macrocode}
648 \AtBeginDocument{%
649 \ifbool{@examz@prompt}{%
650 \promptrandomexam
651 }{%
652 }%
653 \ifrandomizectr{%
654 \opencountersfile
655 }{%
656 \inputcountersfile
657 }%
658 }%
659 % \end{macrocode}
660 %
661 %\subsection{Randomized Exams}\label{imp:versions}
662 %
663 % The counter \textit{numversions} determines how many versions of the exam will
664 % be generated. The default value of \textit{numversions} is 1.
665 %
666 % \begin{macrocode}
667 \newcounter{numversions}
668 \setcounter{numversions}{1}
669 % \end{macrocode}
670 %
671 %\begin{macro}{\promptversions}
672 %
673 % The following command is used by the \textsf{versions} environment (described
674 % below) whenever the class is loaded with the \textsf{prompt} option. Note that
675 % the counter is saved to the counters file. (See the documentation for the
676 % \textsf{counterz} package.)
677 %
678 % \begin{macrocode}
679 \newcommand{\promptversions}{%
680 \typein[\NumberOfVersions]{%
681 ^^J How many versions?
682 }%
683 \setcounter{numversions}{\NumberOfVersions}
684 \savecounter{numversions}
685 }%
686 % \end{macrocode}
687 %
688 %\end{macro}
689 %
690 % The counter \textit{version} keeps track of the exam version when printing.
691 % The value of \textit{version} is initialized as 1.
692 %
693 % \begin{macrocode}
694 \newcounter{version}
695 \setcounter{version}{1}
696 % \end{macrocode}
697 %
698 % We now patch the parent class \textsf{exam} so that corresponding questions in
699 % different versions will not be assigned the same question label. To accomplish
700 % this, we append to the question labels the value of \textit{version}. We also
701 % append an \textit{S} if the boolean \textit{answers} (from the \textsf{exam}
702 % class) is TRUE, to distinguish between versions with and without solutions
703 % when the class is loaded with the option \textsf{complete}.
704 %
705 % \begin{macrocode}
706 \xpatchcmd{\find@latestques}
707 {@\arabic{question}}
708 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
709 {}{}
710 \xpatchcmd{\decr@latest@ques}
711 {question@}
712 {question@\arabic{version}\ifbool{printanswers}{S}{}@}
713 {}{}
714 \xpatchcmd{\chk@incompi}
715 {question@}
716 {question@\arabic{version}\ifbool{printanswers}{S}{}@}
717 {}{}
718 \xpatchcmd{\questions}
719 {@\arabic{question}}
720 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
721 {}{}
722 \xpatchcmd{\parts}
723 {@\arabic{question}}
724 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
725 {}{}
726 \xpatchcmd{\subparts}
727 {@\arabic{question}}
728 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
729 {}{}
730 \xpatchcmd{\subsubparts}
731 {@\arabic{question}}
732 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
733 {}{}
734 \xpatchcmd{\setup@point@toks}
735 {@\arabic{question}}
736 {@\arabic{version}\ifbool{printanswers}{S}{}@\arabic{question}}
737 {}{}
738 \xpatchcmd{\refto@index}
739 {question@}
740 {question@\arabic{version}\ifbool{printanswers}{S}{}@}
741 {}{}
742 % \end{macrocode}
743 %
744 %\begin{macro}{\@examz@versions}
745 %
746 % The \textsf{versions} environment is defined via command \cs{@examz@versions}.
747 % The single argument of this command represents the user-provided exam content,
748 % including the \textsf{questions} environment and any pages before or after. If
749 % the class is loaded with the option \textsf{prompt} and the exam is randomized
750 % then the command first executes \cs{promptversions} to attain and save the
751 % value of the counter \textit{numversions}. The main action of the command is
752 % to use a while loop to generate versions of the exam, updating the version
753 % and page numbers along the way. When the class is loaded with the option
754 % \textsf{complete}, the document alternately prints without and with solutions,
755 % updating the version only after both printings. When the class is loaded with
756 % the option \textsf{twoside}, an extra blank page is inserted at the end of
757 % each version when necessary to ensure that the next version starts on a front
758 % page.
759 %
760 % \begin{macrocode}
761 \newcommand{\@examz@versions}[1]{%
762 \ifrandomizectr{%
763 \ifbool{@examz@prompt}{%
764 \promptversions
765 }{%
766 % Do Nothing
767 }%
768 }{%
769 % Do Nothing
770 }%
771 \ifbool{@examz@complete}{%
772 \noprintanswers
773 }{%
774 % Do Nothing
775 }%
776 \whileboolexpr{%
777 test{\ifnumless{\value{version}}{1+\value{numversions}}}
778 }{%
779 \ifbool{@twoside}{%
780 \ifnumodd{\value{page}}{%
781 % Do Nothing
782 }{%
783 \newpage
784 \null
785 \thispagestyle{empty}
786 \newpage
787 }%
788 }{%
789 % Do Nothing
790 }%
791 \setcounter{page}{1}
792 \setcounter{numquestions}{0}
793 \setcounter{numparts}{0}
794 \setcounter{numsubparts}{0}
795 \setcounter{numsubsubparts}{0}
796 \setcounter{numpoints}{0}
797 \setcounter{numbonuspoints}{0}
798 #1
799 \newpage
800 \notbool{@examz@complete}{%
801 \addtocounter{version}{1}
802 }{%
803 \notbool{printanswers}{%
804 \printanswers
805 }{%
806 \noprintanswers
807 \addtocounter{version}{1}
808 }%
809 }%
810 }%
811 }%
812 % \end{macrocode}
813 %
814 %\end{macro}
815 %
816 %\begin{environment}{versions}
817 %
818 % The \textsf{versions} environment is now defined using the previous command
819 % and the command \cs{Collect@Body}. The environment has an optional argument
820 % with which the user may specify the number of versions. If the exam is not
821 % randomized then the argument is ignored under the assumption that the needed
822 % value has been inputted from the counters file after a previous randomization.
823 % (If there is never any randomization, then there is no need for different
824 % versions, and the environment will execute with the default number of versions
825 % being one.) If the class is loaded with the option \textsf{prompt}, then this
826 % optional argument will be overridden by the number provided by the user via
827 % terminal prompt.
828 %
829 % \begin{macrocode}
830 \newenvironment{versions}[1][1]{%
831 \ifrandomizectr{%
832 \setcounter{numversions}{#1}
833 \savecounter{numversions}
834 }{%
835 % Do Nothing
836 }%
837 \Collect@Body\@examz@versions
838 }{%
839 % Empty
840 }%
841 % \end{macrocode}
842 %
843 %\end{environment}
844 %
845 % The \textsf{exam} document class exam prints in the console and log file some
846 % data that includes the number of questions, total points, etc. Here we add to
847 % that data the number of versions of the exam and whether the solutions were
848 % printed.
849 %
850 % \begin{macrocode}
851 \AtEndDocument{%
852 \typeout{%
853 This document contains \thenumversions\space
854 version\ifnumequal{\value{numversions}}{1}{}{s} of the exam
855 \ifbool{@examz@complete}{%
856 with and without solutions.
857 }{%
858 \ifbool{printanswers}{%
859 with solutions.
860 }{%
861 without solutions.
862 }%
863 }%
864 }%
865 }%
866 % \end{macrocode}
867 %
868 %\subsection{Question Banks}\label{imp:banks}
869 %
870 %\begin{macro}{\@examz@questionpath}
871 %\begin{macro}{\setquestionpath}
872 % The default value of \cs{@examz@questionpath} is empty, but authors may use
873 % the command \cs{setquestionpath}\marg{pathname} to change this.
874 %
875 % \begin{macrocode}
876 \newcommand{\@examz@questionpath}{}
877 \newcommand{\setquestionpath}[1]{%
878 \renewcommand{\@examz@questionpath}{#1}
879 }%
880 % \end{macrocode}
881 %
882 %\end{macro}
883 %\end{macro}
884 %
885 %\begin{macro}{\questionfrombank}
886 % The command \cs{questionfrombank}\oarg{points}\marg{filename} uses the
887 % command \cs{question} from the \textsf{exam} class. The first (optional)
888 % argument is the point value of the question, and the second argument is the
889 % name of the question bank file (without the .tex extension). The input uses
890 % \cs{\@examz@questionpath}. In order to avoid a conflict between question banks
891 % that use the same counter names, \cs{counterprefix} is temporarily set to
892 % include both the name of the file and the number of the version. (See the
893 % \textsf{counterz} package for more information about \cs{setcounterprefix}.)
894 %
895 % \begin{macrocode}
896 \newcommand{\questionfrombank}[2][]{%
897 \question[#1]
898 \setcounterprefix{#2_Version_\arabic{version}_}
899 \input{\@examz@questionpath #2}
900 \clearcounterprefix
901 }%
902 % \end{macrocode}
903 %
904 %\end{macro}
905 %
906 %\begin{macro}{\setnumberofquestions}
907 %
908 % The counter \textit{@examz@qbsize} is an internal counter to represent the
909 % number of questions in a question bank. The command
910 % \cs{setnumberofquestions}\marg{number} is used to set this value.
911 %
912 % \begin{macrocode}
913 \newcounter{@examz@qbsize}
914 \newcommand{\setnumberofquestions}[1]{%
915 \setcounter{@examz@qbsize}{#1}
916 }%
917 % \end{macrocode}
918 %
919 %\end{macro}
920 %
921 %\begin{environment}{questionbank}
922 %
923 % The \textsf{questionbank} environment begins by creating a random counter that
924 % is used to determine which question will be selected and ends with the command
925 % \cs{endinput} so that nothing after the environment appears in the question.
926 % \begin{macrocode}
927 \newenvironment{questionbank}{%
928 \xrandprovidecounter{Random_Question}{1}{\value{@examz@qbsize}}
929 }{%
930 \endinput
931 }
932 % \end{macrocode}
933 %
934 %\end{environment}
935 %
936 %\begin{environment}{qbitem}
937 %
938 % The environment \textsf{qbitem} is a wrapper for each option in a
939 % \textsf{questionbank} environment. The argument is an integer value that is
940 % compared to the random counter value generated by \textsf{questionbank}. The
941 % body of the environment is the content of the question. Additional counters
942 % that are created and manipulated within \textsf{qbitem} should be handled by
943 % the commands provided in the \textsf{counterz} package in order to use the
944 % counter prefix that is created by the command \cs{questionfrombank}.
945 %
946 % \begin{macrocode}
947 \NewEnviron{qbitem}[1]{%
948 \ifnumequal{\xvalue{Random_Question}}{#1}{%
949 \BODY
950 }{%
951 }
952 }
953 % \end{macrocode}
954 %
955 %\end{environment}
956 %
957 %\begin{macro}{\setsolutionspace}
958 %
959 % The command \cs{@examz@solutionspace} represents the amount of space allotted
960 % to solutions, per the various solutions environments that are defined by the
961 % \textsf{exam} document class. \cs{setsolutionspace}\marg{length} is used to
962 % set this value.
963 %
964 % \begin{macrocode}
965 \newcommand{\@examz@solutionspace}{1cm}
966 \newcommand{\setsolutionspace}[1]{%
967 \renewcommand{\@examz@solutionspace}{#1}
968 }%
969 % \end{macrocode}
970 %
971 %\end{macro}
972 %
973 % \noindent
974 % For each of the six solutions environments provided by the \textsf{exam} class
975 % there is an analogous solutions environment that automatically loads the value
976 % of \cs{SolutionSpace} for the argument.
977 %
978 %\begin{environment}{qbsolution}
979 %
980 % \textsf{qbsolution} is equivalent to
981 % \textsf{solution}[\cs{@examz@solutionspace}].
982 %
983 % \begin{macrocode}
984 \NewEnviron{qbsolution}{%
985 \begin{solution}[\@examz@solutionspace]
986 \BODY
987 \end{solution}
988 }%
989 % \end{macrocode}
990 %
991 %\end{environment}
992 %
993 %\begin{environment}{qbsolutionbox}
994 %
995 % \textsf{qbsolutionbox} is equivalent to
996 % \textsf{solutionbox}\{\cs{@examz@solutionspace}\}.
997 %
998 % \begin{macrocode}
999 \NewEnviron{qbsolutionbox}{%
1000 \begin{solutionbox}{\@examz@solutionspace}
1001 \BODY
1002 \end{solutionbox}
1003 }%
1004 % \end{macrocode}
1005 %
1006 %\end{environment}
1007 %
1008 %\begin{environment}{qbsolutionorbox}
1009 %
1010 % \textsf{qbsolutionorbox} is equivalent to
1011 % \textsf{solutionorbox}[\cs{@examz@solutionspace}].
1012 %
1013 % \begin{macrocode}
1014 \NewEnviron{qbsolutionorbox}{%
1015 \begin{solutionorbox}[\@examz@solutionspace]
1016 \BODY
1017 \end{solutionorbox}
1018 }%
1019 % \end{macrocode}
1020 %
1021 %\end{environment}
1022 %
1023 %\begin{environment}{qbsolutionorlines}
1024 %
1025 % \textsf{qbsolutionorlines} is equivalent to
1026 % \textsf{solutionorlines}[\cs{@examz@solutionspace}].
1027 %
1028 % \begin{macrocode}
1029 \NewEnviron{qbsolutionorlines}{%
1030 \begin{solutionorlines}[\@examz@solutionspace]
1031 \BODY
1032 \end{solutionorlines}
1033 }%
1034 % \end{macrocode}
1035 %
1036 %\end{environment}
1037 %
1038 %\begin{environment}{qbsolutionordottedlines}
1039 %
1040 % \textsf{qbsolutionordottedlines} is equal to
1041 % \textsf{solutionordottedlines}[\cs{@examz@solutionspace}].
1042 %
1043 % \begin{macrocode}
1044 \NewEnviron{qbsolutionordottedlines}{%
1045 \begin{solutionordottedlines}[\@examz@solutionspace]
1046 \BODY
1047 \end{solutionordottedlines}
1048 }%
1049 % \end{macrocode}
1050 %
1051 %\end{environment}
1052 %
1053 %\begin{environment}{qbsolutionorgrid}
1054 %
1055 % \textsf{qbsolutionorgrid} is equivalent to
1056 % \textsf{solutionorgrid}[\cs{@examz@solutionspace}].
1057 %
1058 % \begin{macrocode}
1059 \NewEnviron{qbsolutionorgrid}{%
1060 \begin{solutionorgrid}[\@examz@solutionspace]
1061 \BODY
1062 \end{solutionorgrid}
1063 }%
1064 % \end{macrocode}
1065 %
1066 %\end{environment}
1067 %
1068 %\subsection{Customization Macros}
1069 %
1070 %\begin{macro}{\instructorname}
1071 %\begin{macro}{\coursename}
1072 %\begin{macro}{\examname}
1073 %\begin{macro}{\termname}
1074 %\begin{macro}{\namespace}
1075 %\begin{macro}{\instructions}
1076 %\begin{macro}{\covernoanswers}
1077 %\begin{macro}{\coveranswers}
1078 %\begin{macro}{\workspace}
1079 %
1080 % The following commands define macros, with default values, for use in
1081 % formatting headers, footers, and special pages. \cs{covernoanswers} and
1082 % \cs{workspace} are empty by default, and \cs{coveranswers} is equal to
1083 % \cs{covernoanswers} by default.
1084 %
1085 % \begin{macrocode}
1086 \newcommand{\instructorname}{Instructor Name}
1087 \newcommand{\coursename}{Course Name}
1088 \newcommand{\examname}{Exam Name}
1089 \newcommand{\termname}{Term Name}
1090 \newcommand{\namespace}{Name:~\makebox[5cm]{\hrulefill}}
1091 \newcommand{\instructions}{Instructions Here}
1092 \newcommand{\covernoanswers}{}
1093 \newcommand{\coveranswers}{\covernoanswers}
1094 \newcommand{\workspace}{}
1095 % \end{macrocode}
1096 %
1097 %\end{macro}
1098 %\end{macro}
1099 %\end{macro}
1100 %\end{macro}
1101 %\end{macro}
1102 %\end{macro}
1103 %\end{macro}
1104 %\end{macro}
1105 %\end{macro}
1106 %
1107 %\begin{macro}{\setinstructorname}
1108 %\begin{macro}{\setcoursename}
1109 %\begin{macro}{\setexamname}
1110 %\begin{macro}{\settermname}
1111 %\begin{macro}{\setnamespace}
1112 %\begin{macro}{\setinstructions}
1113 %\begin{macro}{\setcoveranswers}
1114 %\begin{macro}{\setcovernoanswers}
1115 %\begin{macro}{\setworkspace}
1116 %
1117 % The following commands allow a user to redefine the above macros.
1118 % \begin{macrocode}
1119 \newcommand{\setinstructorname}[1]{\renewcommand{\instructorname}{#1}}
1120 \newcommand{\setcoursename}[1]{\renewcommand{\coursename}{#1}}
1121 \newcommand{\setexamname}[1]{\renewcommand{\examname}{#1}}
1122 \newcommand{\settermname}[1]{\renewcommand{\termname}{#1}}
1123 \newcommand{\setnamespace}[1]{\renewcommand{\namespace}{#1}}
1124 \newcommand{\setinstructions}[1]{\renewcommand{\instructions}{#1}}
1125 \newcommand{\setcovernoanswers}[1]{\renewcommand{\covernoanswers}{#1}}
1126 \newcommand{\setcoveranswers}[1]{\renewcommand{\coveranswers}{#1}}
1127 \newcommand{\setworkspace}[1]{\renewcommand{\workspace}{#1}}
1128 % \end{macrocode}
1129 %
1130 %\end{macro}
1131 %\end{macro}
1132 %\end{macro}
1133 %\end{macro}
1134 %\end{macro}
1135 %\end{macro}
1136 %\end{macro}
1137 %\end{macro}
1138 %\end{macro}
1139 %
1140 %\begin{macro}{\printcover}
1141 %
1142 % The command \cs{printcover} executes either \cs{coveranswers} or
1143 % \cs{covernoanswers}, depending on the value of the boolean
1144 % \textsf{printanswers}.
1145 %
1146 % \begin{macrocode}
1147 \newcommand{\printcover}{%
1148 \ifbool{printanswers}{\coveranswers}{\covernoanswers}
1149 }%
1150 % \end{macrocode}
1151 %
1152 %\end{macro}
1153 %
1154 %\begin{macro}{\printworkspace}
1155 %
1156 % The command \cs{printcover} executes \cs{workspace} when the boolean
1157 % \textsf{printanswers} is false and otherwise does nothing.
1158 %
1159 % \begin{macrocode}
1160 \newcommand{\printworkspace}{%
1161 \ifbool{printanswers}{}{\workspace}
1162 }%
1163 % \end{macrocode}
1164 %
1165 %\end{macro}
1166 %
1167 % \Finale
1168 \endinput