\def\ouexamdate{30 August 2019}
\def\ouexamversion{2.4.2}
\def\ouexamshortdate{2019/08/30}
% \iffalse meta-comment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Copyright 1999--2019 Nigel Stanger and University of Otago
%% 
%% You may use this package freely, and also distribute it
%% provided that you don't change it, make any money off
%% it or pretend that you wrote it.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{doc}
\DisableCrossrefs
\CodelineNumbered
\RecordChanges

\renewcommand{\rmdefault}{ppl}
\usepackage{graphicx}
\usepackage{microtype}
% change hyperref options as required
\usepackage[colorlinks,pdfpagemode=UseNone,urlcolor=blue,
            linkcolor=blue,pdfauthor={Nigel Stanger}]{hyperref}

\title{The \textsf{ouexam} document class, v\ouexamversion}
\author{Nigel Stanger\\nigel.stanger@otago.ac.nz}
\date{\ouexamdate}

\begin{document}
\maketitle
\DocInput{ouexam.dtx}
\end{document}
%</driver>
%
% \fi
%
%% \CheckSum{1147}
%%
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
% \MakeShortVerb{\|}
% 
% \changes{1.0}{1999/04/15}{Initial version}
%
% \begin{abstract}
% This document class allows you to create Otago University final
% examination papers using \LaTeXe\@. It implements the major formatting
% requirements specified by the University, provides useful
% macros to ease the process of building the title page and automatically
% deals with fiddly little issues such as question and section numbering,
% the number of pages in the paper, printing ``\textbf{TURN OVER}'' in the
% bottom right corner of every page except the last one and ensuring that the
% total number of marks for a question adds up to the expected number.
% \end{abstract}
% 
% 
% \tableofcontents
% 
% 
% \section{Overview}
% 
% \changes{2.1}{2004/04/10}{Added requirements and installation instructions}
% \changes{2.3}{2012/09/04}{Dropped vanilla \LaTeX\ for building docs.}
% \subsection{Requirements and installation}
% 
% The \textsf{ouexam} package requires the \textsf{verbatim},
% \textsf{fontenc}, \textsf{lmodern} and \textsf{textcomp} packages, all
% of which should come standard with most \TeX\ installations. To build
% the documentation and example files, you will need at least version 1.1
% of the \textsf{listings} package, and the \textsf{pdfjam} tool.
% 
% Installation is relatively simple:
% \begin{enumerate}
% 
%   \item Unpack the distribution archive and \texttt{cd} to the
%   distribution directory.
%   
%   \item \texttt{make}.
%   
%   \item \texttt{make install TEXMF\_INSTALL=/path/to/texmf}.
%   \texttt{/path/to/texmf} should be the root of your preferred
%   \texttt{texmf} tree (e.g., \texttt{/usr/share/texmf}). You may need
%   to do this as root depending on which \texttt{texmf} tree you are
%   installing into. You can also define \texttt{TEXMF\_INSTALL} as an
%   environment variable then simply type \texttt{make install}.
% 
% \end{enumerate}
% You can, of course, always install manually if you wish.
% 
% 
% \changes{2.0}{2002/01/11}{Note on backwards compatibility}
% \subsection{Important note on backwards compatibility}
% 
% Version 2.0 of \textsf{ouexam} introduced several major changes from earlier
% versions. Consequently, documents created using an earlier version of
% \textsf{ouexam} are \emph{incompatible} with version 2.0 or later. Versions 2.0
% and greater of \textsf{ouexam} will detect attempts to process a version 1.x
% document and display an error message.
% 
% The older version (1.2) is still available and can be downloaded from the same
% location as the current version. To process older version documents, just copy
% the version 1.2 |ouexam.cls| file into the same directory as the document file.
% \TeX\ searches the current directory first, so this copy will take precedence
% over any other installed version of \textsf{ouexam}.
% 
% 
% \subsection{Class options}
%
% This document class is based on the \textsf{article} class and accepts
% most of the options accepted by \textsf{article} (the \textsf{twoside},
% \textsf{10pt} and \textsf{11pt} options are ignored). The standard
% options are \textsf{onecolumn}, \textsf{oneside}, \textsf{a4paper} and
% \textsf{12pt}. In addition, \textsf{ouexam} accepts the following
% ``native'' class options:
% \begin{description}
%   \item[\textsf{draft}] \DescribeMacro{draft} This option has the usual
%   effects that you would expect for \textsf{draft} mode in the
%   \textsf{article} class, plus \fbox{DRAFT} is printed in
%   the footer of every page. Note that if you use the \textsf{graphicx}
%   package and turn on the \textsf{draft} option in \textsf{ouexam}, all
%   included graphics will be drawn in draft mode unless you specify the
%   |draft=false| option to \cs{includegraphics}.
% 
%   \item[\textsf{markingschedule}] \DescribeMacro{markingschedule}
%   Rather than write a separate marking schedule for an examination paper, you
%   can use the \textsf{marking} environment to embed marking information
%   within questions (see 
%   \hyperref[Sec:Questions:Marking]{section~\ref*{Sec:Questions:Marking}}).
%   By default this information is not printed (for obvious reasons!), but
%   when it comes time to print a marking schedule for the examination,
%   including the \textsf{markingschedule} class option in the
%   \cs{usepackage} command will cause \textsf{ouexam} to print the hidden
%   content. It will also print \fbox{MARKING SCHEDULE} in the header of
%   every page.
%   
%   \item[\textsf{times}] \DescribeMacro{times}
%   The Examinations Office prefers all examination papers to be set in 12pt
%   Palatino. However, if this is not available, they will accept 13pt Times
%   instead. The \textsf{times} class option enables the latter, but should
%   only be used if Palatino is not available.
%   
%   \item[\textsf{embargo}] \DescribeMacro{embargo}
%   Specify this option if the examination paper is to be embargoed. This will add a field for the candidate to enter their student ID in the top right of the title page, and automatically insert an instruction under ``other instructions'' to hand in the entire examination paper.
% \end{description}
% 
% 
% \subsection{Required packages}
% 
% This class requires the \textsf{verbatim} package in order to implement
% the marking schedule functionality. It also expects modern \LaTeX\ font
% handling capabilities, and therefore requires the \textsf{fontenc},
% \textsf{textcomp} and \textsf{lmodern} classes. \textsf{pgfkeys} is used
% for key-value option handling.
% 
% 
% \subsection{Page margins}
% 
% This class assumes A4 paper. You will probably get weird results if you try
% to do anything different. The margins are set up as follows: top and bottom
% 2cm (headers and footers are inside this margin), left and right 2.54cm (1in).
% 
% 
% \subsection{Page styles}
% 
% There are two page styles defined in this class:
% \begin{description}
%   \item[\textsf{plain}] \DescribeMacro{plain} This is a slight modification of the \textsf{plain} page style from \textsf{article}. It produces pages that have the page number centered at the bottom, the paper number in the top right corner and the text ``\textbf{TURN OVER}'' in the bottom right of every page except the last page, which has ``\textbf{END}'' instead. This is the default page style.
% 
%   \item[\textsf{titlepage}] \DescribeMacro{titlepage} This is similar to \textsf{plain} but without the page header, and is used for the title page of the paper. You will normally not use this yourself, because the \cs{maketitlepage} macro handles this automatically (see \hyperref[Sec:TitlePage]{section~\ref*{Sec:TitlePage}}).
% \end{description}
% 
% 
% \section{Writing an examination paper}
% 
% 
% \changes{2.0.2}{2002/05/11}{Moved title page subsection}
% \subsection{The title page}
% \label{Sec:TitlePage}
% 
% This class defines a collection of macros that let you fill in the various
% parts of the examination title page. This is analogous to the process you use
% to generate the title of a document in, for example, the \textsf{article} class
% (using \cs{title}, \cs{author}, \cs{date} and \cs{maketitle}). That is, you
% issue the macros described below in the document preamble, then issue a
% \cs{maketitlepage} in the document body.
% 
% The \DescribeMacro{\examyear} \cs{examyear} macro lets you specify the year
% in which the examination is being held, for example, |\examyear{2016}|. This
% macro is mandatory.
% 
% The \DescribeMacro{\department} \cs{department} macro lets you specify the
% name of the department that produced the examination paper, for example,
% |\department{Information| |Science}|. This macro is mandatory.
% 
% The \DescribeMacro{\papernumber} \cs{papernumber} macro lets you specify
% the paper number that the examination is for, for example,
% |\papernumber{COMP 101}|. This macro is mandatory. Note that when you
% specify semester information using \cs{semester}, this is appended to
% the paper number in the page header. For example, if you specify
% |\papernumber{COMP 101}| and |\semester{2}|, the header will contain
% ``COMP 101 (Semester Two)'' rather than just ``COMP 101''.
% 
% The \DescribeMacro{\papertitle} \cs{papertitle} macro lets you specify the
% title of the paper, for example, 
% |\papertitle{Systems Analysis and Design Methods}|. This macro is mandatory.
% 
% \changes{2.0.2}{2002/08/22}{Added `FY' to \cs{semester} macro description}
% Some papers are offered in more than one semester. The
% \DescribeMacro{\semester} \cs{semester} macro lets you specify which
% semester the examination is for. The argument can be either ``1'' or ``2''
% for semesters 1 and 2, ``SS'' for summer school, ``FY'' for a full-year
% paper or ``SP'' for a special examination, for example, |\semester{2}|.
% Invalid values for the argument cause a warning to be raised. This macro is
% optional---if you omit it, no semester information is generated.
% 
% The \DescribeMacro{\timeallowed} \cs{timeallowed} macro lets you specify the
% length of the examination in hours, for example, |\timeallowed{2}|. This
% macro is optional---if you omit it, it defaults to three (3) hours.
% 
% If calculators are permitted in the examination, use the 
% \DescribeMacro{\allowcalculators}
% \DescribeMacro{\permitcalculators}
% \cs{allowcalculators} macro (\cs{permitcalculators} will also work).
% This macro is optional---if you omit it, a sentence is inserted saying
% that calculators are \emph{not} permitted. The macro has a
% single optional argument that specifies the kind of calculators
% permitted. If omitted, it defaults to ``any'' (see below). Otherwise,
% this argument must be one of the following values:
% \begin{description}
% 
%   \item[\textsf{none}] A sentence is inserted noting that no calculators are
%   permitted.
% 
%   \item[\textsf{scientific}] A sentence is inserted noting that only approved
%   scientific calculators are permitted.
% 
%   \item[\textsf{graphing}] A sentence is inserted noting that only approved
%   scientific and graphing calculators are permitted.
% 
%   \item[\textsf{any}] (default) A sentence is inserted noting that any
%   calculator that does not have a communication capability is
%   permitted.
% 
% \end{description}
% 
% The \DescribeMacro{\instructions} \cs{instructions} macro lets you specify
% instructions on how candidates should complete the
% examination, for example, |\instructions{Answer ALL| |questions.}|. This macro
% is optional. Note that the content of the instructions can be just about
% anything. It is up to you to control formatting, such as how you want lines
% broken, etc. This also true of the \cs{material}, \cs{copiesof} and
% \cs{otherinstructions} macros described below.
% 
% The \DescribeMacro{\material} \cs{material} macro lets you specify any
% additional material that candidates are provided in addition to the
% examination paper itself, for example, |\material{SQL schema definition}|.
% This macro is optional.
% 
% The \DescribeMacro{\copiesof} \cs{copiesof} macro lets you specify any
% material that candidates are allowed to bring into the examination, for
% example, |\copiesof{McFadden \&| |Hoffer, 5th edition}|. This macro is
% optional.
% 
% The \DescribeMacro{\otherinstructions} \cs{otherinstructions} macro lets you specify any other instructions not covered by any of the above, for example, |\otherinstructions{No smoking| |allowed.}|. This macro is optional. Note that if the examination is embargoed using the \textsf{embargo} class option, additional instructions will be automatically inserted here.
% 
% Once you have specified the content of the title page using the above
% macros, you simply issue a \DescribeMacro{\maketitlepage} \cs{maketitlepage}
% to generate the front page of the examination (cf. \cs{maketitle}). The title
% page generated meets University formatting requirements.
% Note that the number of pages in the examination paper is generated
% and inserted into the title page automatically---you do not need to specify
% it manually.
% 
% 
% \subsection{Sections}
% \label{Sec:Sections}
% 
% Examination papers may optionally have multiple sections, ``numbered'' A, B, etc. Rather than redefine the existing \LaTeX\ section macros, \textsf{ouexam} defines an \DescribeEnv{examsection} \textsf{examsection} environment that generates a new section. The \textsf{examsection} environment has three mandatory arguments:
% \begin{enumerate}
%   \item The expected number of marks for the question. If you leave this argument empty it defaults to zero. By default, \textsf{ouexam} keeps a running total of the \emph{actual} number of marks encountered within a section, which is compared with the value of this argument when the environment is closed (use the \textsf{don't verify total} option to disable this; see below). An error is raised if the values are not equal. The running total is also typeset right-justified at the end of the section in the form ``\textbf{[SECTION A TOTAL 20 MARKS]}'' (unless the \textsf{hide total} option is specified; see below) as an additional verification (or just ``\textbf{[TOTAL 20 MARKS]}'' if the \textsf{hide title} option is specifed; see below).
% 
%   \item Instructions for answering questions in this section, such as ``\textbf{ANSWER ANY \underline{TWO} QUESTIONS.}''. The argument will be typeset in \textbf{bold face}. If you leave this argument empty it defaults to ``\textbf{ANSWER \underline{ALL} QUESTIONS (TOTAL xx MARKS).}'' (the marks total is omitted if it is zero or if the \textsf{hide total} option is specified; see below).
% 
%   \item A description of the topic of the section (this could also be used to provide further, more detailed instructions). This can be left empty.
% \end{enumerate}
%
% The optional argument to \textsf{examsection} is a list of option keywords that control its behaviour. The available options are:
% \begin{description}
%   \item[\textsf{show title}] \DescribeMacro{show title}\DescribeMacro{hide title} Print the title of the section (enabled by default). Specify \textsf{hide title} to suppress this.
%
%   \item[\textsf{show total}] \DescribeMacro{show total}\DescribeMacro{hide total} Print a summary at the end of the section of the number of marks in the section (enabled by default). Specify \textsf{hide total} to suppress this. This option does not cascade to any questions within the section.
%
%   \item[\textsf{verify total}] \DescribeMacro{verify total}\DescribeMacro{don't verify total} Calculate the running total of marks for questions within the section, and verify that this matches the expected number of marks. Specify \textsf{don't verify total} to suppress this (this also implies \textsf{hide total}).
% \end{description}
%
% Every section begins on a new page, and the section title is formatted as ``\textbf{\underline{Section A}}'', in \cs{large} size, unless the \textsf{hide title} option is specified. For example: \\
% 
% \noindent|\begin{examsection}{25}{}{These questions are remarkably boring.}| \\
% \hspace*{1cm}\vdots \\
% |\end{examsection}| \\
% 
% \noindent will produce the following (assuming that the actual number of
% marks in the question is correct):
% 
% \begin{center}
%   \fbox{%
%   \begin{minipage}{0.9\columnwidth}
%     {\large\noindent\textbf{\underline{Section~A}}} \\[0.5\baselineskip]
%     \textbf{ANSWER \underline{ALL} QUESTIONS (TOTAL 25 MARKS).} \\
%     These questions are remarkably boring. \\
%     \hspace*{2cm}\vdots \\
%     \mbox{}\hfill\textbf{[SECTION A TOTAL 25 MARKS]}
%   \end{minipage}
%   }
% \end{center}
%
% \noindent whereas |\begin{examsection}[hide title]{25}{}{...}| will produce:
% 
% \begin{center}
%   \fbox{%
%   \begin{minipage}{0.9\columnwidth}
%     \textbf{ANSWER \underline{ALL} QUESTIONS (TOTAL 25 MARKS).} \\
%     These questions are remarkably boring. \\
%     \hspace*{2cm}\vdots \\
%     \mbox{}\hfill\textbf{[TOTAL 25 MARKS]}
%   \end{minipage}
%   }
% \end{center}
%
% 
% \subsection{Questions}
% \label{Sec:Questions}
% 
% \textsf{ouexam} provides three environments for building examination
% questions: \DescribeEnv{question} \textsf{question},
% \DescribeEnv{subquestion} \textsf{subquestion} and \textsf{subsubquestion},
% which correspond to top-level questions, parts of questions, and
% \DescribeEnv{subsubquestion} sub-parts of questions respectively. They
% produce questions that are numbered according to University examination
% formatting requirements. Note that questions are normally numbered
% sequentially throughout the entire paper regardless of any section
% boundaries.
% 
% All three environments have a single mandatory argument which is the
% expected number of marks for the question, part or sub-part. If this
% argument is left empty it will default to zero (this has the side effect of
% not printing the marks total at the end of the question). This argument works
% in much the same way as the first argument to the \textsf{examsection}
% environment (see \hyperref[Sec:Sections]{section~\ref*{Sec:Sections}}):
% \textsf{ouexam} keeps a running total of the number of marks encountered
% within each question part and sub-part, and compares this total with the
% expected value when the environment closes. Where appropriate, the running
% total is typeset right-justified in the form ``(5 marks)''. For example:
% \begin{verbatim}
% \begin{question}{5}
%   \begin{subquestion}{2}
%     Why is the sky blue?
%   \end{subquestion}
%   \begin{subquestion}{3}
%     Explain in detail how the sky can be made pink.
%   \end{subquestion}
% \end{question}
% \begin{question}{1}
%   Define the term ``floccinaucinihilipilification''.
% \end{question}
% \end{verbatim}
% 
% \noindent will produce the following:
% \begin{center}
%   \fbox{%
%   \begin{minipage}{0.9\columnwidth}
%     \begin{enumerate}
%       \item
%       \begin{enumerate}
%         \item Why is the sky blue? \hfill (2 marks)
% 
%         \item Explain in detail how the sky can be made pink. \hfill (3
%         marks)
%       \end{enumerate}
% 
%       \item Define the term ``floccinaucinihilipilification''. \hfill (1
%       mark)
%     \end{enumerate}
%   \end{minipage}
%   }
% \end{center}
% 
% The \textsf{question} environments handle formatting of marks totals
% automatically, including considerations such as:
% \begin{itemize}
%   \item whether or not to print the number of marks for a question at all (they should not be printed if the question has sub-parts, and will also not be printed if the number of marks is zero, or if the \textsf{hide marks} option is specified; see below);
% 
%   \item whether to print ``mark'' or ``marks'' (e.g., question 2 above); and
% 
%   \item where to position the number of marks relative to the question,
%   depending on how full the last line of the question is.
% \end{itemize}
% \changes{2.4.2}{2019/08/30}{Refactored marks printing.}
% If you want to change the way marks are typeset (positioning, appearance, etc.), you can redefine the \DescribeMacro{printmarks} \textsf{printmarks} macro, but be aware that \textsf{printmarks} does a lot for you (see Section~\ref{sec-src-questions})! (There will probably be a more flexible solution in a future version for changing the way marks are typeset.)
%
% The optional argument to the various \textsf{question} environments is a list of option keywords that control its behaviour. The available options are:
%
% \begin{description}
%   \item[\textsf{show marks}] \DescribeMacro{show marks}\DescribeMacro{hide marks} Print the number of marks for the question (enabled by default). Specify \textsf{hide marks} to suppress them. This option is available for the \textsf{question}, \textsf{subquestion}, and \textsf{subsubquestion} environments. Note that the marks will \emph{always} be suppressed when a question has sub-questions, or if its expected number of marks is set to zero.
%
%   \item[\textsf{show total}] \DescribeMacro{show total}\DescribeMacro{hide total} Print a summary at the end of the question of the number of marks in the section (enabled by default). This option does not cascade to any sub-questions within the question. This option is available for the \textsf{question} and \textsf{subquestion} environments only (a \textsf{subsubquestion} has no sub-components to total). Specify \textsf{hide total} to suppress this.
%
%   \item[\textsf{verify total}] \DescribeMacro{verify total}\DescribeMacro{don't verify total} Calculate the running total of marks for sub-questions within the question, and verify that this matches the expected number of marks. Specify \textsf{don't verify total} to suppress this (this also implies \textsf{hide total}). This option is available for the \textsf{question} and \textsf{subquestion} environments only (a \textsf{subsubquestion} has no sub-components to total).
% \end{description}
% 
% \changes{2.4}{2013/05/31}{Enforced proper question environment nesting.}
% The various \textsf{question} environments must be correctly nested in order for the features described above to work correctly, i.e., \textsf{question} at the top level, followed by \textsf{subquestion} and \textsf{subsubquestion}. Any variation to this nesting order will cause an error.
% 
% \changes{2.4}{2013/06/13}{Added \cs{questionskip} to control spacing between questions.}
% You can control the spacing between top-level questions by redefining the \DescribeMacro{\questionskip} \cs{questionskip} length. It defaults to \cs{baselineskip}. Note that this applies only to the \textsf{question} environment; there are no equivalent lengths for \textsf{subquestion} or \textsf{subsubquestion}.
% 
% 
% \changes{2.2}{2010/04/26}{Added time allocation macros.}
% \subsection{Time allocations}
% \label{Sec-Questions-Time}
% 
% If you wish to suggest a time allocation for completing a question, use the \DescribeMacro{\timeallocation} \cs{timeallocation} macro. The only argument is the number of minutes to be allocated for this question. The macro will output the time allocation in the form: \textbf{[The suggested time allocation for this question is \emph{t} minutes.]}
% 
% If you wish to allow a certain amount of time for candidates to read some text, use the \DescribeMacro{\readingtime} \cs{readingtime} macro. The only argument is the number of minutes to be allocated for reading time. The macro will output the reading time in the form: \textbf{[Allow \emph{t} minutes reading time.]}
% 
% Both macros assume the base unit to be minutes; if you wish to change this you will need to redefine the macros. Otherwise, the argument can be almost anything: text, numbers, etc.
% 
% \textsf{ouexam} currently does not check that time allocations sum correctly. This may be implemented in a future version.
%
% 
% \subsection{Marking schedule information}
% \label{Sec:Questions:Marking}
% 
% Rather than writing a separate marking schedule for an examination paper,
% you can use the \DescribeEnv{marking} \textsf{marking} environment to embed
% marking information within questions. By default this information is not
% printed (for obvious reasons!), but when it comes time to print a marking
% schedule for the examination, use the \textsf{markingschedule} class option
% to print the hidden content. The marking information will be set in
% \emph{italics} to differentiate it from the main body of the examination,
% and \fbox{MARKING SCHEDULE} will also be printed in the header of every
% page.
% 
% \changes{2.1}{2004/04/10}{Added driver file tip}
% A useful tip for writing examination papers is to create two separate
% ``driver'' documents that are set up the document class for the
% ``plain'' and ``marking schedule'' versions of the examination,
% respectively. Each should then include a separate document that contains
% the actual content of the examination paper, for example:
% 
% \begin{verbatim}
% \documentclass[markingschedule]{ouexam}
% 
% \input{exampaper} % contains the actual examination content
% \end{verbatim}
% 
% Doing this enables you to build the ``plain'' and ``marking schedule''
% versions independently, without overwriting each other or having to
% change the original source file. Simply run \LaTeX\ on the appropriate
% driver file to produce the version that you want. See the example files
% that came with the \textsf{ouexam} distribution for an example of this
% approach in action.
% 
% 
% \subsection{Miscellaneous}
% 
% Most examinations are marked out of 100, and \textsf{ouexam} defaults to
% this. However, if you want an examination that is marked out of some other
% number, for example, 90 marks, you can specify this using the
% \DescribeMacro{\examoutof} \cs{examoutof} macro. Thus, |\examoutof{90}|
% will set the expected number of marks for the examination to 90. This value
% is used by \textsf{ouexam} to verify that the marks for all the questions
% add up to the expected number of marks for the examination.
% 
% 
% \section{Errors and warnings}
% 
% In this section are described the error messages and warning produced by
% \textsf{ouexam}, and the reasons why they occur.
% 
% 
% \subsection{Error messages}
% 
% \noindent\texttt{OBSOLETE (\ldots): this document was written for an
% earlier} \\
% \texttt{version of ouexam \ldots} \\
% You are trying to use v2.0 or later of \textsf{ouexam} with a document that was written for \textsf{ouexam} v1.2 or earlier. Versions 2.0 and later of \textsf{ouexam} are \emph{fundamentally incompatible} with earlier versions. The only solutions here are either to revert to \textsf{ouexam} v1.2 or earlier (you can put a copy of the class file in the same directory as the document), or rewrite the document to conform to the current version of \textsf{ouexam}. You should be able to download a copy of v1.2 from the same location that you found the current version. \\
% 
% \noindent\texttt{no \cs{examyear} was specified} \\
% \noindent\texttt{no \cs{department} was specified} \\
% \noindent\texttt{no \cs{papernumber} was specified} \\
% \noindent\texttt{no \cs{papertitle} was specified} \\
% You have not specified one of these macros. All four of these macros are mandatory and must be included in the preamble of any \textsf{ouexam} document. \\
% 
% 
% \noindent\texttt{question environment nested inside another question, subquestion or \\*
% \hspace*{1em}subsubquestion environment} \\
% \noindent\texttt{subquestion environment either outside a question environment, or \\*
% \hspace*{1em}nested inside another subquestion or subsubquestion environment} \\
% \noindent\texttt{subsubquestion environment either outside a subquestion \\*
% \hspace*{1em}environment, or nested inside another subsubquestion environment} \\
% These errors all mean that you have incorrectly nested your \textsf{question} environments in some way. \textsf{question}s must always appear at the outermost level, \textsf{subquestion}s must always appear inside \textsf{question}s, and \textsf{subsubquestion}s must always appear inside \textsf{subquestion}s. Any other kind of nesting is an error. \\
% 
% 
% \subsection{Warnings}
% 
% \noindent\texttt{actual number of marks for exam (\ldots) does not match expected \\*
% \hspace*{1em}number of marks (\ldots)} \\
% The actual number of marks supplied for the whole examination (calculated by summing the marks for all the questions) is not the same as the expected total for the examination. Adjust the marks for the questions until the totals match. \\
% 
% \noindent\texttt{actual mark (\ldots) for section \ldots\ does not match expected \\*
% \hspace*{1em}mark (\ldots)} \\
% The actual number of marks supplied for a particular section (calculated by summing the marks for all the questions in that section) is not the same as the expected total for that section. Adjust the marks for the questions in the section concerned until the totals match. The section number is given in the warning. \\
% 
% \noindent\texttt{actual mark (\ldots) for question \ldots\ does not match expected \\*
% \hspace*{1em}mark (\ldots)} \\
% The actual number of marks supplied for a particular question (calculated by summing the marks of all its sub-parts) is not the same as the expected total for that question. Adjust the marks for the sub-parts of the question until the totals match. The question number is given in the warning. \\
% 
% \changes{2.0.2}{2002/08/22}{Added `FY' to \cs{semester} error description}
% \noindent\texttt{invalid value `\ldots' for \cs{semester}; valid values are `1', `2', \\*
% \hspace*{1em}`SS', `FY' and `SP'. No semester information will be printed} \\
% You have provided an invalid value as the argument to the \cs{semester} macro. The allowed values are ``1'' (semester one), ``2'' (semester two), ``SS'' (summer school), ``FY'' (full-year) and ``SP'' (special examination). Any other values will be ignored. Note that these are case-sensitive, for example, `sp' is invalid.  \\
% 
% \changes{2.1}{2004/04/05}{Added error description for \cs{allowcalculators}}
% \noindent\texttt{invalid value `\ldots' for \cs{allowcalculators}; valid values are \\*
% \hspace*{1em}`none', `any' and `approved'. No calculators will be permitted} \\
% You have provided an invalid value as the argument to the \cs{allowcalculators} macro. The allowed values are ``none'' (no calculators permitted), ``any'' (any calculator permitted) and ``approved'' (only approved calculators permitted). Any other values will be ignored, and \textsf{ouexam} will assume that no calculators are permitted. Note that these are case-sensitive, for example, `NONE' is invalid.  \\
% 
% 
% \section{Example}
% 
% \changes{1.1}{1999/04/20}{Updated example}
% \changes{2.0}{2002/01/25}{Updated example}
% \changes{2.1}{2004/04/10}{Updated example}
% The code given below is for the first three pages of the INFO~321 2001
% final examination. The output produced by this source is shown in
% \hyperref[Fig.Example]{figure~\ref*{Fig.Example} on
% page~\pageref*{Fig.Example}}. Particular points to note in this example
% are:
% \begin{itemize}
% 
%   \item The number of hours is not specified, so it defaults to three.
% 
%   \item This examination allows only approved calculators.
%   
%   \item The \textsf{listings} package (v1.1 or later) is used to
%   typeset code listings.
% 
%   \item The argument of the \cs{instructions} macro can be just about
%   anything, as can the arguments of the \cs{material}, \cs{copiesof} and
%   \cs{otherinstructions} macros. In this example, the \cs{instructions}
%   macro has been omitted, causing \textsf{ouexam} to output the default
%   instructions.
% 
%   \item Marking schedule information has been embedded within the
%   questions. \hyperref[Fig.Example2]{Figure~\ref*{Fig.Example2} on
%   page~\pageref*{Fig.Example2}} shows the output produced by this source
%   when the \textsf{markingschedule} class option is used.
% 
% \end{itemize}
% The full source for this example may be found in the
% \texttt{example*.tex} files that came with this distribution.
% 
% \small
% \begin{verbatim}
% \documentclass{ouexam}
% 
% \usepackage{graphicx}
% \usepackage{listings}
% 
% \examyear{2001}
% \department{Information Science}
% \papernumber{INFO 321}
% \papertitle{Database Systems}
% \allowcalculators[approved]
% 
% \begin{document}
% 
% \lstloadlanguages{ODL,OQL,[Oracle8]SQL,[Oracle8]PLSQL}
% \lstset{basicstyle=\sffamily, showstringspaces=false, tabsize=2,
%   xleftmargin=1cm, belowskip=0pt, commentstyle=\itshape,
%   numbers=left, numberstyle=\scriptsize, numbersep=5pt,
%   columns=fullflexible,}
% 
% \maketitlepage
% 
% \begin{examsection}{25}{}{Questions in this section (total 25 marks) 
%   relate to physical database design and tuning.}
% 
% 
% 
% \begin{question}{10}
% 
%   A major U.S. mail order firm is having performance problems with queries
%   on the \textsf{Customer} table in its Oracle8 order-processing database.
%   Consider the following information about the \textsf{Customer} table,
%   then answer the questions below: \\
% 
%   \textsf{\textbf{Customer}(\underline{customer\_no}, name, address, city,
%   state, country, phone, email, status)}
% 
%   \begin{itemize}
%     \item \textsf{customer\_no} is the primary key and because this is an
%     Oracle8 database, a unique B-tree index has been automatically created
%     on this column.
% 
%     \item \textsf{status} is a single character column that holds one of
%     the values `I' (inactive), `B' (bronze), `S' (silver) or `G' (gold).
%     The value of this column is determined by a customer's order history.
% 
%     \item About 10\% of customers are inactive, about 50\% have bronze
%     status, about 35\% have silver status and about 5\% have gold status.
% 
%     \item The average row size is about 200 bytes and there are
%     approximately 5,000,000 rows.
% 
%     \item The \textsf{Customer} table is heavily queried (averaging thirty
%     new queries per minute) by four different groups of employees. Group~1
%     queries only inactive customers, group~2 queries only bronze status
%     customers and groups~3 and~4 both query only silver and gold status
%     customers. Members of any group may query the table at any time and
%     queries often overlap.
% 
%     \item UPDATE, INSERT and DELETE operations on the table are uncommon.
% 
%     \item Very few queries are for individual customers; rather, most
%     queries are based on various combinations of values from
%     \textsf{status}, \textsf{city}, \textsf{state} and \textsf{country}.
%   \end{itemize}\medskip
% 
%   \begin{subquestion}{3}
%     Describe and justify an \emph{index-based} physical tuning solution
%     that will improve the performance of queries on the \textsf{Customer}
%     table. (No code is required.)
%     \begin{marking}
%       Since queries tend to be on combinations of several low-cardinality
%       columns [1] and the table is very large [1], the most effective
%       solution would be to place bitmap indexes on status, city, state and
%       country [1].
% 
%       B-tree indexes on any of the individual columns would not be ideal
%       because of their low cardinality. A possible alternative is a
%       composite B-tree index on all four columns [1 for suggesting this if
%       appropriate], but this is not ideal and would be much larger than
%       the four bitmap indexes [1 for this explanation if appropriate].
%       Hashing is definitely \emph{not} an option, because very few queries
%       are exact match.
%     \end{marking}
%   \end{subquestion}
% 
%   \begin{subquestion}{7}
%     \begin{subsubquestion}{5}\label{nonindex}
%       Assuming that there are two identical fast disks available, describe
%       and justify two alternative \emph{non index-based} physical tuning
%       solutions that will improve the performance of queries on the
%       \textsf{Customer} table. For each solution include details of how
%       the two disks will be used. (No code is required.)
%       \begin{marking}
%         Alternative 1: partition the table across the two disks based on
%         status (four partitions, one for each status value) [1]. This will
%         allow simultaneous parallel access to different parts of the table
%         by the different groups [1]. Since two groups both access silver
%         and gold customers, it makes sense to put the silver customers on
%         disk one and the gold customers on disk two. Bronze customers
%         account for 50\% of the table, so it makes sense to also put them
%         on disk two (as the gold customers are the smallest group), and
%         put the inactive customers on disk one with the silver customers.
%         [1 for any sensible partitioning scheme]
%   
%         Alternative 2: replicate the table across both disks (one replica
%         on each disk) [1]. This will also provide simultaneous parallel
%         access to the data (hard to tell whether this would be better or
%         worse than the partitioning above) [1].
%   
%         Note that any solution must be capable of being implemented in
%         Oracle8.
%       \end{marking}
%     \end{subsubquestion}
% 
%     \begin{subsubquestion}{2}
%       Briefly discuss the relative advantages and/or disadvantages of the
%       two alternative solutions you described in part~(\ref{nonindex})
%       above.
%       \begin{marking}
%         The partitioning solution given above doesn't really help with the
%         bronze customer rows---we would need random horizontal
%         partitioning to really help with this, which Oracle8 doesn't
%         support. More generally, Oracle8 does not migrate rows into the
%         correct partition if a customer's status changes, so the data will
%         need to be reloaded occasionally [1].
% 
%         For replication, we have the usual problem of keeping the replicas
%         synchronised if they are both read/write. This is somewhat
%         mitigated by the fact that there are only two copies [1].
%       \end{marking}
%     \end{subsubquestion}
%   \end{subquestion}
% \end{question}
% 
% \newpage
% \begin{question}{10}
%   There are two generic parameters that affect the structure of a B-tree
%   index.
% 
%   \begin{subquestion}{6}
%     Identify these two parameters and describe what each parameter
%     specifies. Use diagrams to illustrate your answer.
%     \begin{marking}
%       \emph{Node size} [1] specifies the maximum number of pointers in
%       each index node [1]. Suitable diagram [1].
% 
%       \emph{Percentage fill} [1] specifies the number of pointers in each
%       index node that are allocated when a node is created [1]. In effect,
%       it determines the amount of free space left in each node. Suitable
%       diagram [1].
%     \end{marking}
%   \end{subquestion}
%   
%   \begin{subquestion}{4}
%     For each of the two parameters, discuss the practical effect(s) of:
%     \begin{subsubquestion}{2}
%       high values of the parameter; and
%       \begin{marking}
%         Large node size reduces the height of the B-tree, resulting in
%         potentially fewer I/Os to access a leaf node [$\frac{1}{2}$]. It
%         can however increase the number of rows locked in a single leaf
%         node [$\frac{1}{2}$].
%   
%         High percent fill means that most pointers in a node will be
%         allocated when the node is created [$\frac{1}{2}$]. This leaves
%         little free space in the B-tree for new key values or key values
%         that change [$\frac{1}{2}$].
%       \end{marking}
%     \end{subsubquestion}
%     \begin{subsubquestion}{2}
%       low values of the parameter.
%       \begin{marking}
%         Small node size increases the height of the B-tree, resulting in
%         potentially more I/Os to access a leaf node [$\frac{1}{2}$]. The
%         number of rows locked in a single leaf node will be reduced
%         [$\frac{1}{2}$].
%   
%         Low percent fill means that most pointers in a node will not be
%         allocated when the node is created [$\frac{1}{2}$]. This leaves
%         little free space in the B-tree for new key values or key values
%         that change [$\frac{1}{2}$].
%       \end{marking}
%     \end{subsubquestion}
%   \end{subquestion}
% \end{question}
%   
%   
%   
% \begin{question}{5}\label{clusterq}
% 
%   \begin{subquestion}{2}
%     Define what is meant by the term ``clustering'' in the context of
%     physical database design and tuning, and explain why it is beneficial.
% 
%     \begin{marking}
%       Clustering is the grouping of related rows physically near to each
%       other on disk [1] so that they may be retrieved in as few I/Os as
%       possible (ideally one)---beneficial because of the slowness of disk
%       I/O compared to memory I/O [1].
%     \end{marking}
%   \end{subquestion}
%   
%   \begin{subquestion}{3}\label{clusterqcode}
%     Consider the following Oracle8 SQL table definition:
%     
%     \begin{lstlisting}[language={[Oracle8]SQL}]{}
% create table enrolment
% (  student_id char(7),
%   paper_code char(7),
%   enrol_year number(4),
%   
%   primary key (student_id, paper_code, enrol_year)
% );
%     \end{lstlisting}
% 
%     The \textsf{Enrolment} table is often queried for all rows relating to
%     a particular student in a particular year (for example, student
%     1234567 in 1998, student 9876543 in 2000, etc.). Write appropriate
%     Oracle8 SQL code that will cluster the rows of the table in such a way
%     as to support these types of query (you do not need to calculate
%     cluster sizes). Relevant Oracle8 syntax diagrams are given on the next
%     page.
%     \begin{marking}
%       \begin{lstlisting}[language={[Oracle8]SQL}]{}
% create cluster enrolment_cluster (student_id char(7), year number(4));
% 
% create index enrol_cluster_index on cluster enrolment_cluster;
% 
% create table enrolment
% (  student_id char(7),
%   paper_code char(7),
%   enrol_year number(4),
%   
%   primary key (student_id, paper_code, enrol_year)
% ) cluster enrolment_cluster(student_id, enrol_year);
%       \end{lstlisting}
%     \end{marking}
%     [1] each for correct cluster, cluster index and table clustering.
%   \end{subquestion}
% 
% \end{question}
% 
% \end{examsection}
%       .
%       .
%       .
% \end{document}
% \end{verbatim}
% \normalsize
% 
% \begin{figure}
%   \fbox{\includegraphics[scale=0.28]{eg1-1}}
%   \hfill
%   \fbox{\includegraphics[scale=0.28]{eg1-2}}
%   
%   \begin{center}
%     \fbox{\includegraphics[scale=0.28]{eg1-3}}
%   \end{center}
% 
%   \caption{Output produced by \textsf{ouexam}.}
%   \label{Fig.Example}
% \end{figure}
% 
% \begin{figure}
%   \fbox{\includegraphics[scale=0.28]{eg2-2}}
%   \hfill
%   \fbox{\includegraphics[scale=0.28]{eg2-3}}
% 
%   \bigskip
%   
%   \fbox{\includegraphics[scale=0.28]{eg2-4}}
%   \hfill
%   \fbox{\includegraphics[scale=0.28]{eg2-5}}
% 
%   \caption{Output produced by \textsf{ouexam} when
%       \textsf{markingschedule} is used.}
%   \label{Fig.Example2}
% \end{figure}
% 
% 
% \StopEventually{\PrintChanges\PrintIndex}
% 
% \changes{2.0}{2002/01/10}{Revamped and tided up documentation and code}
% 
% \section{The code}
% 
% \subsection{Preamble}
% 
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1998/06/01]
\ProvidesClass{ouexam}[\ouexamshortdate\space %
                       v\ouexamversion\space Otago %
                       University examination paper]
%    \end{macrocode}
% 
% \begin{macro}{\@ouexam@obsolete}
% \changes{2.0}{2002/01/10}{New \cs{@unsupported} macro}
% \changes{2.4}{2013/06/07}{Renamed \cs{@unsupported} macro to \cs{@ouexam@obsolete}.}
% This macro is used to handle documents written for older versions of \textsf{ouexam}. All obsolete macros map to this macro, which prints out an appropriate error message. It needs to be defined early because it is used to trap use of the obsolete \textsf{multichoice} class option.
%
%    \begin{macrocode}
\def\@ouexam@obsolete#1#2{\ClassError{ouexam}{%
  ^^JOBSOLETE (#1)^^J%
  This document was written for an earlier version of ouexam and is^^J%
  not compatible with ouexam v\ouexamversion. Please either update^^J%
  your document or use ouexam v#2 or earlier to process it.^^J%
  Version #2 can be downloaded from the same location as %
  version\space\ouexamversion}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@ouexam@unused}
% \changes{2.4}{2013/06/07}{New \cs{@ouexam@unused} macro.}
% This macro is used to warn the user about class options that are not used by this class, and that will therefore be ignored. All unused macros map to this macro, which prints out an appropriate warning message.
%
%    \begin{macrocode}
\def\@ouexam@unused#1{\OptionNotUsed\ClassWarning{ouexam}{%
  specified option ``#1'' is not used by ouexam^^J%
  and will therefore be ignored}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{multichoice}
% \changes{1.1}{1999/04/20}{New class option}
% \changes{2.0}{2000/09/04}{Removed option}
% The \textsf{multichoice} class option is no longer supported, but rather than just breaking older documents, we can at least try to present a reasonable error message.
%
%    \begin{macrocode}
\DeclareOption{multichoice}{%
  \@ouexam@obsolete{multichoice class option}{1.2}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{twoside}
% \changes{1.1}{1999/04/20}{Switched off option}
% This document class is based on the \textsf{article} class and accepts any of the options accepted by \textsf{article}. The \textsf{twoside} option does not really make sense, however---all Otago examination papers are printed single-sided anyway, and the format is such that two-sided printing would look no different. The \textsf{twoside} option is therefore not used in this class.
%
%    \begin{macrocode}
\DeclareOption{twoside}{\@ouexam@unused{twoside}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{twocolumn}
% \changes{2.3}{2013/06/07}{Turned off \textsf{twocolumn} option.}
% The \textsf{twocolumn} option also does not make much sense for Otago examination papers.
%
%    \begin{macrocode}
\DeclareOption{twocolumn}{\@ouexam@unused{twocolumn}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{10pt}
% \begin{macro}{11pt}
% \changes{2.3}{1999/04/20}{Turned off \textsf{10pt} and \textsf{11pt}
% options.}
% The Examinations Office specifies a minimum of 12pt for the font size, so the \textsf{10pt} and \textsf{11pt} options are not used in this class.
%
%    \begin{macrocode}
\DeclareOption{10pt}{\@ouexam@unused{10pt}}
\DeclareOption{11pt}{\@ouexam@unused{11pt}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{draft}
% \changes{2.0}{2001/05/15}{New class option}
% \begin{macro}{\if@draft}
% \changes{2.0}{2001/05/15}{New switch for \textsf{draft}}
% The \textsf{draft} option determines whether the examination is to be printed
% in draft mode (default off). The \cs{if@draft} switch is used to determine
% whether this is in effect (default false). Draft mode has the usual effects
% that you would expect for draft mode in the \textsf{article} class, plus
% \fbox{DRAFT} is printed in the footer of every page.
%
%    \begin{macrocode}
\newif\if@draft \@draftfalse
\DeclareOption{draft}{%
  \@drafttrue\PassOptionsToClass{\CurrentOption}{article}%
}
%    \end{macrocode}
% 
% Note that if you use the \textsf{graphicx} package and turn on the
% \textsf{draft} option in \textsf{ouexam}, all included graphics will
% be drawn in draft mode unless you specify the |draft=false| option to the
% \cs{includegraphics} macro. The amount of effort required to fix what is
% a relatively small issue isn't really worth it, so this will not change.
% \end{macro}
% \end{macro}
% 
% \begin{macro}{markingschedule}
% \changes{2.0}{2000/09/05}{New class option}
% \begin{macro}{\if@markingschedule}
% \changes{2.0}{2000/09/05}{New switch for \textsf{markingschedule}}
% The \textsf{markingschedule} option determines whether marking schedule
% information is printed in addition to the questions (default off). The
% \cs{if@markingschedule} switch is used to determine whether this is in effect
% (default false).
%
%    \begin{macrocode}
\newif\if@markingschedule \@markingschedulefalse
\DeclareOption{markingschedule}{\@markingscheduletrue}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{times}
% \changes{2.3}{2012/09/03}{New \textsf{times} class option.}
% \begin{macro}{\if@times}
% \changes{2.3}{2012/09/03}{New switch for \textsf{times}.}
% The \textsf{times} option formats the examination paper using 13pt Times. If this
% option is not specified, then the examination paper is formatted using 12pt Palatino.
%
%    \begin{macrocode}
\newif\if@times \@timesfalse
\DeclareOption{times}{\@timestrue}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{embargo}
% \changes{2.4}{2016/09/26}{New \textsf{embargo} class option.}
% \begin{macro}{\if@embargo}
% \changes{2.4}{2016/09/26}{New switch for \textsf{embargo}.}
% Specify the \textsf{embargo} option if the examination paper is to be embargoed. This will print a field for the candidate to enter their student ID in the top right corner of the title page, and add relevant text to the other instructions section of the title page.
%
%    \begin{macrocode}
\newif\if@embargo \@embargofalse
\DeclareOption{embargo}{\@embargotrue}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% All other options are passed directly to the \textsf{article} class:
%
%    \begin{macrocode}
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}}
\ProcessOptions
%    \end{macrocode}
%
% \changes{1.1}{1999/04/20}{Default font \(\Rightarrow\) 12pt}
% The defaults for this class are \textsf{onecolumn}, \textsf{oneside},
% \textsf{a4paper} and \textsf{12pt}. The font size is the only one that might
% need to change.
%
%    \begin{macrocode}
\LoadClass[onecolumn,oneside,a4paper,12pt]{article}
%    \end{macrocode}
% 
% 
% \subsection{Required packages}
% 
% \changes{2.0}{2001/05/08}{Removed \textsf{calc} and
% \textsf{ifthen} dependencies}
% The \textsf{verbatim} package, is used to implement the \textsf{marking}
% environment:
%
%    \begin{macrocode}
\RequirePackage{verbatim}
%    \end{macrocode}
%
% \changes{2.3}{2012/09/04}{Added requirement for \textsf{fontenc},
% \textsf{textcomp} and \textsf{lmodern} packages.}
%
% Running under vanilla OT1 encoding often causes all sorts of font substitution
% warnings, so the \textsf{fontenc} (with \textsf{T1} option), \textsf{textcomp}
% and \textsf{lmodern} packages are used to bring \textsf{ouexam}'s font
% handling up to more modern standards.
%
%    \begin{macrocode}
\RequirePackage[T1]{fontenc}
\RequirePackage{textcomp}
\RequirePackage{lmodern}
%    \end{macrocode}
%
% \changes{2.4}{2016/05/03}{Added requirement for \textsf{pgfkeys}.}
%
% Options to the \textsf{examsection} and various \textsf{question} environments require \textsf{pgfkeys} to provide a more powerful interface.
%
%    \begin{macrocode}
\RequirePackage{pgfkeys}
%    \end{macrocode}
% 
%
% \changes{2.4}{2012/09/04}{Added setup for \textsf{pgfkeys}.}
% \subsection{\textsf{pgfkeys} setup}
%
% Separate key paths are defined for each of the environments that need them, in order to provide greater flexibility. Otherwise, options could cascade from the containing environment to its sub-environments. For example, we may wish to suppress the marks total for individual questions, but enable it for the enclosing section.
%
% \subsubsection{\texttt{/exam section/}}
%
%    \begin{macrocode}
\newif\ifexamsection@showtitle
\newif\ifexamsection@showtotal
\newif\ifexamsection@verifytotal
\pgfkeys{%
  /exam section/.cd,%
%    \end{macrocode}
% |show title| toggles the display of section titles.
%    \begin{macrocode}
  show title/.is if=examsection@showtitle,%
  show title/.default=true,%
%    \end{macrocode}
% |show total| toggles the display of an overall marks total for a section.
%    \begin{macrocode}
  show total/.is if=examsection@showtotal,%
  show total/.default=true,%
%    \end{macrocode}
% |verify total| (if |true|) causes \textsf{examsection} to calculate a running total of all question marks within it and verify that this total matches the expected number of marks for the section. Setting this to |false| is useful for cases like optional questions, where the running total will normally sum to more than the expected number of marks. Obviously it's then up to the examination author to verify the totals make sense!
%    \begin{macrocode}
  verify total/.is if=examsection@verifytotal,%
  verify total/.default=true,%
%    \end{macrocode}
% Define some useful shortcut styles for disabling options.
%    \begin{macrocode}
  hide title/.style={show title=false},%
  hide total/.style={show total=false},%
  don't verify total/.style={verify total=false,show total=false},%
%    \end{macrocode}
% Initialise defaults:
%    \begin{macrocode}
  show title,%
  show total,%
  verify total%
}
%    \end{macrocode}
%
% \subsubsection{\texttt{/question/}}
%
%    \begin{macrocode}
\newif\ifquestion@showmarks
\newif\ifquestion@showtotal
\newif\ifquestion@verifytotal
\pgfkeys{%
  /question/.cd,%
%    \end{macrocode}
% |show marks| toggles the display of marks for an individual question.
%    \begin{macrocode}
  show marks/.is if=question@showmarks,%
  show marks/.default=true,%
%    \end{macrocode}
% |show total| toggles the display of an overall marks total for a question that has sub-parts (this also implies |show marks=false|, but we can't do that here). (Note that this doesn't actually do anything yet!)
%    \begin{macrocode}
  show total/.is if=question@showtotal,%
  show total/.default=true,%
%    \end{macrocode}
% |verify total| works similarly to \textsf{examsection}.
%    \begin{macrocode}
  verify total/.is if=question@verifytotal,%
  verify total/.default=true,%
%    \end{macrocode}
% Define some useful shortcut styles for disabling options.
%    \begin{macrocode}
  hide marks/.style={show marks=false},%
  hide total/.style={show total=false},%
  don't verify total/.style={verify total=false,show total=false},%
%    \end{macrocode}
% Initialise defaults:
%    \begin{macrocode}
  show marks,%
  hide total,%
  verify total%
}
%    \end{macrocode}
%
% \subsubsection{\texttt{/subquestion/}}
%
%    \begin{macrocode}
\newif\ifsubquestion@showmarks
\newif\ifsubquestion@showtotal
\newif\ifsubquestion@verifytotal
\pgfkeys{%
  /subquestion/.cd,%
%    \end{macrocode}
% |show marks| works similarly to \textsf{question}.
%    \begin{macrocode}
  show marks/.is if=subquestion@showmarks,%
  show marks/.default=true,%
%    \end{macrocode}
% |show total| works similarly to \textsf{question}.
%    \begin{macrocode}
  show total/.is if=subquestion@showtotal,%
  show total/.default=true,%
%    \end{macrocode}
% |verify total| works similarly to \textsf{examsection}.
%    \begin{macrocode}
  verify total/.is if=subquestion@verifytotal,%
  verify total/.default=true,%
%    \end{macrocode}
% Define some useful shortcut styles for disabling options.
%    \begin{macrocode}
  hide marks/.style={show marks=false},%
  hide total/.style={show total=false},%
  don't verify total/.style={verify total=false,show total=false},%
%    \end{macrocode}
% Initialise defaults:
%    \begin{macrocode}
  show marks,%
  hide total,%
  verify total%
}
%    \end{macrocode}
%
% \subsubsection{\texttt{/subsubquestion/}}
%
% Sub-sub-questions don't have sub-components, so |show total| and |verify total| are unnecessary.
%
%    \begin{macrocode}
\newif\ifsubsubquestion@showmarks
\pgfkeys{%
  /subsubquestion/.cd,%
%    \end{macrocode}
% |show marks| works similarly to \textsf{question}.
%    \begin{macrocode}
  show marks/.is if=subsubquestion@showmarks,%
  show marks/.default=true,%
%    \end{macrocode}
% Define some useful shortcut styles for disabling options.
%    \begin{macrocode}
  hide marks/.style={show marks=false},%
%    \end{macrocode}
% Initialise defaults:
%    \begin{macrocode}
  show marks%
}
%    \end{macrocode}
% 
%
% \changes{2.3}{2012/09/04}{Added font setup for \textsf{times} class
% option.}
% \subsection{Font setup}
% 
% The Examinations Office allows for two standard font styles: 12pt Palatino
% (preferred) or 13pt Times New Roman. The former is the default; the latter is
% only used if the \textsf{times} class option is used, and we need to
% explicitly define all the standard sizes. The following is extrapolated from
% the definitions in the \textsf{article} class and seems about right:
%
%    \begin{macrocode}
\if@times%
  \usepackage{mathptmx}%
  \renewcommand{\normalsize}{\fontsize{13}{15.7}\selectfont}%
  \renewcommand{\tiny}{\fontsize{\@viipt}{\@viiipt}\selectfont}%
  \renewcommand{\scriptsize}{\fontsize{\@ixpt}{11}\selectfont}%
  \renewcommand{\footnotesize}{\fontsize{\@xpt}{\@xiipt}\selectfont}%
  \renewcommand{\small}{\fontsize{\@xipt}{13.6}\selectfont}%
  \renewcommand{\large}{\fontsize{\@xivpt}{18}\selectfont}%
  \renewcommand{\Large}{\fontsize{\@xviipt}{22}\selectfont}%
  \renewcommand{\LARGE}{\fontsize{\@xxpt}{25}\selectfont}%
  \renewcommand{\huge}{\fontsize{\@xxvpt}{30}\selectfont}%
  \let\Huge=\huge%
\else%
  \usepackage{mathpazo}%
\fi%
%    \end{macrocode}
% 
% 
% \subsection{Page setup}
% 
% \begin{macro}{\oddsidemargin}
% \begin{macro}{\topmargin}
% \begin{macro}{\textwidth}
% \begin{macro}{\textheight}
% A4 paper is assumed (since this class is intended only for Otago examination
% papers, this seems a reasonable assumption). The margins are top and bottom
% 2cm, left and right 2.54cm (1in).
%
%    \begin{macrocode}
\setlength{\oddsidemargin}{0cm}
\setlength{\topmargin}{-0.54cm}
\setlength{\textwidth}{15.92cm}
\setlength{\textheight}{25.7cm}
\advance\textheight by-\headheight
\advance\textheight by-\headsep
\advance\textheight by-\footskip
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% 
% \subsection{Page styles}\label{pagestyles}
%
% \begin{macro}{\ps@lastpage}
% \changes{2.1.1}{2006/08/21}{Updated to display ``\textbf{END}''}
% \changes{2.4}{2013/06/06}{Replaced the \textsf{lastpage} page style with direct manipulation of the footer contents in the \textsf{plain} page style, as \cs{pagestyle} and \cs{thispagestyle} don't affect automatically generated float pages on the last page of the document.}
% \end{macro}
% \changes{2.3}{2012/09/03}{Rearranged headers and footers to conform to the latest formatting requirements. Swapped \fbox{MARKING SCHEDULE} and \fbox{DRAFT} between header and footer so that the page number doesn't get overprinted.}
% \changes{2.4}{2016/08/26}{Added support to \textsf{titlepage} page style for new \textsf{embargo} class option.}
% 
%\begin{macro}{\if@lastpagetext}
%\begin{macro}{\if@lastpagefloat}
% These two switches are used in some slightly convoluted logic to ensure that ``\textbf{END}'' is printed on the last page of the document (see below for details).
%    \begin{macrocode}
\newif\if@lastpagetext \@lastpagetextfalse
\newif\if@lastpagefloat \@lastpagefloatfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\ps@plain}
% \changes{2.0}{2001/05/17}{Added support for \textsf{draft} and \textsf{markingschedule}}
% \changes{2.0}{2002/01/15}{Ensured page number is always centered}
% The \textsf{plain} page style is based on that in the \textsf{article} class, and produces pages with the page number centered at the bottom, the paper number in the top right corner and the text ``\textbf{TURN OVER}'' in the bottom right. If semester information is specified, this is included in parentheses after the paper code, for example, ``COMP 101 (Semester Two)''. \fbox{MARKING SCHEDULE} is printed at top left if the \textsf{markingschedule} class option is used.
%    \begin{macrocode}
\def\ps@plain{%
  \def\@oddhead{\@markingschedule\hfill\@pnumber%
      \ifx\@semester\@empty\else\ (\@semester)\fi}%
  \let\@evenhead\@oddhead%
  \def\@oddfoot{%
%    \end{macrocode}
% 
% Note that we have to get a bit clever to ensure that the page number is properly centered in the page footer. The naive solution is just to use \cs{hfill}s, but this will cause the page number to shift around depending on the length of \cs{@pnumber}. The \textsf{fancyhdr} package will do this for us, but it seems a bit of overkill to require this package merely so that we can ensure that the page number remains centered. Instead, we've borrowed the relevant technique from that class, which draws the left, centre and right bits of the footer as three overlapping boxes. You just have to be careful that the value of \cs{@pnumber} isn't so long that it overwrites the page number.
%    \begin{macrocode}
    \rlap{\parbox[b]{\columnwidth}{\raggedright\@draft\strut}}\hfill%
    \parbox[b]{\columnwidth}{\centering\textrm{\thepage}\strut}\hfill%
    \llap{\parbox[b]{\columnwidth}{\raggedleft\textbf{%
%    \end{macrocode}
% 
% An additional complication is that only the very last page of the document should have ``\textbf{END}'' displayed in the footer instead of ``\textbf{TURN OVER}''. This turns out to be a lot harder than you might think! Simply applying a \textsf{lastpage} page style \cs{AtEndDocument} works fine, \emph{except} when you have unprocessed floats at the end of the document. These are placed on one or more automatically-generated float pages at the end, which \cs{pagestyle} and \cs{thispagestyle} don't affect. That is, a \textsf{lastpage} page style simply doesn't work in this situation.
% 
% The solution is therefore to not use a page style, but rather check in the \textsf{plain} page style whether or not this is the last page, because the page style macro will be expanded for every float page that is generated. Again, this isn't as simple as it sounds! The logic goes like this:
% 
% \begin{itemize}
% 
%   \item If there are no unprocessed floats, meaning that the last page of the document will be a text page (indicated by \cs{@lastpagetexttrue}), then output ``\textbf{END}''.
% 
%   \item If there are unprocessed floats, meaning that the last page of the document will be a float page (indicated by \cs{@lastpagefloattrue}), then:
% 
%   \begin{itemize}
% 
%     \item If a float page is currently being generated (which is indicated by \cs{@fcolmadetrue} from \texttt{latex.ltx}), then:
% 
%     \begin{itemize}
%     
%       \item If there are no more unprocessed floats (\cs{@deferlist} is empty), output ``\textbf{END}''.
%       
%       \item Otherwise, output ``\textbf{TURN OVER}''.
%     
%     \end{itemize}
% 
%     \item Otherwise, output ``\textbf{TURN OVER}''.
% 
%   \end{itemize}
% 
%   \item Otherwise, output ``\textbf{TURN OVER}''.
% 
% \end{itemize}
%    \begin{macrocode}
      \if@lastpagetext END%
      \else\if@lastpagefloat\if@fcolmade\ifx\@deferlist\@empty END%
                                        \else TURN OVER\fi%
                            \else TURN OVER\fi%
            \else TURN OVER\fi%
      \fi}}}%
    }%
  \let\@evenfoot\@oddfoot%
}
%    \end{macrocode}
% \end{macro}
%
% \textsf{plain} is the default page style:
% 
%    \begin{macrocode}
\pagestyle{plain}
%    \end{macrocode}
% 
% \cs{AtEndDocument}, we need to set the \texttt{lastpage} switches accordingly. The \cs{@deferlist} macro from \texttt{latex.ltx} holds a list of unprocessed floats. If this is empty, there's nothing more to do and can we just set \cs{@lastpagetexttrue}. If the list still contains unprocessed floats, set \cs{@lastpagefloattrue} then \cs{clearpage} to flush them out. We also need to decrement the page counter by one, otherwise it ends up being one too many, which is presumably a side effect of the explicit \cs{clearpage}.
%    \begin{macrocode}
\AtEndDocument{%
  \ifx\@deferlist\@empty%
    \@lastpagetexttrue%
  \else%
    \@lastpagefloattrue%
    \clearpage%
    \addtocounter{page}{-1}%
  \fi%
}
%    \end{macrocode}
% 
% \begin{macro}{\ps@titlepage}
% \changes{2.0}{2001/05/17}{Added support for \textsf{draft} and \textsf{markingschedule}}
% The \textsf{titlepage} page style is similar to \textsf{plain}, but without the header. If the examination is embargoed, insert a field for the candidate to write in their student ID in the top right corner.
%    \begin{macrocode}
\def\ps@titlepage{%
  \def\@oddhead{%
    \@markingschedule%
    \if@embargo\hfill\large\textbf{Student ID:} \rule{4cm}{0.8pt}\fi%
  }%
  \let\@evenhead\@oddhead%
  \def\@oddfoot{\@draft\hfill\textbf{TURN OVER}}%
  \let\@evenfoot\@oddfoot%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Various counters}
% 
% Earlier versions of \textsf{ouexam} used the \textsf{enumerate}
% environment to build questions, which meant that special counters were not
% required. This version of the class, however, uses a different mechanism for
% building questions, so we need to define custom counters for several things.
% 
% \begin{macro}{question}
% \begin{macro}{subquestion}
% \changes{2.0}{2000/09/11}{New counter}
% \changes{2.0.1}{2000/04/30}{References now print as ``(a)'', not ``1(a)''}
% \begin{macro}{subsubquestion}
% \changes{2.0}{2000/09/11}{New counter}
% \changes{2.0.1}{2000/04/30}{Fixed ``(i)'' incorrectly printing as ``(a)''}
% \changes{2.0.1}{2000/04/30}{References now print as ``(i)'', not ``1(a)(i)''}
% First, we define three counters for the three possible levels of question:
% top-level question, second-level sub-question or third-level sub-sub-question:
%    \begin{macrocode}
\newcounter{question}
\newcounter{subquestion}[question]
\newcounter{subsubquestion}[subquestion]
%    \end{macrocode}
% The three question levels are numbered as 1., (a) and (i) respectively, so we
% also need to redefine the associated \cs{the} and \cs{label} macros
% appropriately:
%    \begin{macrocode}
\renewcommand{\thequestion}{\arabic{question}}
\newcommand{\labelquestion}{\hfil\arabic{question}.}

\renewcommand{\thesubquestion}{(\alph{subquestion})}
\newcommand{\labelsubquestion}{\hfil(\alph{subquestion})}

\renewcommand{\thesubsubquestion}{(\roman{subsubquestion})}
\newcommand{\labelsubsubquestion}{\hfil(\roman{subsubquestion})}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{examexpected}
% \changes{2.0}{2000/09/11}{New counter}
% The |examexpected| counter stores the total expected number of marks for the
% examination, and defaults to 100:
%    \begin{macrocode}
\newcounter{examexpected}
\setcounter{examexpected}{100}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{examoutof}
% \changes{2.0}{2000/09/11}{New macro}
% To specify that an examination is out of some number of marks other than
% 100, use the \cs{examoutof} macro to set the value:
%    \begin{macrocode}
\newcommand{\examoutof}[1]{\setcounter{examexpected}{#1}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{sectexpected}
% \changes{2.0}{2002/01/09}{New counter}
% \begin{macro}{qexpected}
% \changes{2.0}{2000/09/11}{New counter}
% \begin{macro}{subqexpected}
% \changes{2.0}{2000/09/11}{New counter}
% \begin{macro}{subsubqexpected}
% \changes{2.0}{2000/09/11}{New counter}
% The next four counters perform the same function as the |examexpected| counter
% for sections, questions, sub-questions and sub-sub-questions respectively. No
% macros are required to set these values as they are set automatically by the
% question-building environments.
% 
%    \begin{macrocode}
\newcounter{sectexpected}
\newcounter{qexpected}
\newcounter{subqexpected}
\newcounter{subsubqexpected}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{lastexpected}
% \changes{2.0}{2000/09/11}{New counter}
% The |lastexpected| counter records the expected marks total for the last
% question. This will eventually be used to verify that the marks total for a
% marking schedule equals the marks total for the corresponding question, but
% this hasn't been implemented yet.
% 
%    \begin{macrocode}
\newcounter{lastexpected}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{xsection}
% \changes{2.0}{2002/01/29}{New counter}
% Set up a counter for the section ``number'' and define it so that it prints out as an upper case letter rather than a number. We could just redefine the |section| counter, but that interferes with the section numbering in the documentation, and we can't have that, can we? |:)|
% 
%    \begin{macrocode}
\newcounter{xsection}
\setcounter{xsection}{0}
\renewcommand{\thexsection}{\Alph{xsection}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{examrunning}
% \changes{2.0}{2000/09/11}{New counter}
% \begin{macro}{sectrunning}
% \changes{2.0}{2002/01/09}{New counter}
% \changes{2.4}{2016/05/03}{\texttt{sectrunning} now resets when the \texttt{xsection} counter increments.}
% \begin{macro}{qrunning}
% \changes{2.0}{2000/09/11}{New counter}
% \begin{macro}{subqrunning}
% \changes{2.0}{2000/09/11}{New counter}
% These four counters keep track of the running total of marks for the current examination, section, question and subquestion respectively. This is later compared against the corresponding expected total. A running total is not needed for sub-sub-questions because they do not have sub-parts. The |sectrunning|, |qrunning|, and |subqrunning| counters are reset when the associated counters are incremented.
% 
%    \begin{macrocode}
\newcounter{examrunning}
\setcounter{examrunning}{0}
\newcounter{sectrunning}[xsection]
\newcounter{qrunning}[question]
\newcounter{subqrunning}[subquestion]
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{hassubs}
% \changes{2.0}{2000/09/11}{New counter}
% \begin{macro}{hassubsubs}
% \changes{2.0}{2000/09/11}{New counter}
% These two counters are used to track whether questions and
% sub-questions have sub-parts. Counters are used rather than booleans because
% counters are set globally and booleans are not (or at least do not appear to
% be). Both counters reset when the associated question counters are
% incremented.
% 
%    \begin{macrocode}
\newcounter{hassubs}[question]
\newcounter{hassubsubs}[subquestion]
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{qdepth}
% \changes{2.4}{2013/05/31}{New \texttt{qdepth} counter.}
% This counter is incremented every time a \textsf{question}, \textsf{subquestion} or \textsf{subsubquestion} environment is opened, and decremented every time these environments close. It measures the nesting depth of questions, and is used to check that we do not have things like a \texttt{subquestion} not enclosed by a \texttt{question}, or a \texttt{question} nested inside another \texttt{question}. Note that this counter does \emph{not} reset inside any other environment.
% 
%    \begin{macrocode}
\newcounter{qdepth}
\setcounter{qdepth}{0}
%    \end{macrocode}
% \end{macro}
% 
% At the end of the document, check that the running total of marks for the
% examination matches what we were expecting:
% 
%    \begin{macrocode}
\AtEndDocument{%
  \ifnum\theexamexpected=\theexamrunning%
  \else\ClassWarning{ouexam}{%
    actual number of marks for exam (\theexamrunning) does not^^J%
    match expected number of marks (\theexamexpected)}%
  \fi%
}
%    \end{macrocode}
%
% 
% \subsection{Question-building environments and associated items}\label{sec-src-questions}
% 
% \begin{macro}{\questionskip}
% \changes{2.4}{2013/06/13}{Added \cs{questionskip} to control spacing between questions.}
% \cs{questionskip} is the minimum amount of space between the end of one question and the start of the next. It defaults to the value of \cs{baselineskip}.
%    \begin{macrocode}
\newlength{\questionskip}
\setlength{\questionskip}{\baselineskip}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\printmarks}
% \changes{2.4.2}{2019/08/30}{Refactored marks printing.}
% \cs{printmarks} prints the marks at the end of a \{sub-, subsub-\}question, and you can redefine it to change how marks are printed. The total number of marks for the question is printed right-justified on the line as ``(\emph{m} marks)'' where \emph{m} is the value of the relevant question counter (|qrunning|, |subqrunning|, or |subsubqexpected|), \emph{unless} the number of marks is zero or |show marks=false|, in which case nothing is printed. The macro determines whether to print ``mark'' or ``marks'' automatically, and figures out whether the number of marks will fit on the last line of the question or needs to be placed on the next line. The code for handling the line breaking is derived from an example on page 106 of \emph{The \TeX{}book}, with the addition of a \cs{leavevmode} to prevent \cs{unskip} (which can't be used in vertical mode) from crashing when the marks immediately follow a |verbatim| type environment. This may cause slightly more vertical space after environments (e.g., lists) than is ideal, but not enough to be a major problem.
%    \begin{macrocode}
\newcommand{\printmarks}[1]{%
  \leavevmode\unskip\nobreak\hfil\penalty50\hskip2em\hbox{}\nobreak%
  \hfil(#1~\ifnum#1=1 mark\else marks\fi)%
  \parfillskip=0pt \finalhyphendemerits=0 \par%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{question}
% \changes{2.0}{2000/09/11}{No longer redefines \textsf{enumerate}}
% \changes{2.0}{2001/05/15}{Penalty handling for correct marks placement}
% \changes{2.0}{2001/05/15}{Total marks only printed if no sub-questions}
% \changes{2.3.2}{2014/10/09}{Fixed crashing bug with verbatim environments
% appearing at the end of questions.}
% \changes{2.4}{2013/05/31}{Check question depth when opening the environment.}
% \changes{2.4}{2015/08/19}{Changed how question marks are positioned.}
% \changes{2.4}{2016/05/02}{Only output question marks if they're greater than zero.}
% \changes{2.4.2}{2019/08/30}{Refactored marks printing.}
% The \textsf{question} environment specifies a top-level question, and produces questions numbered in the form ``1.'', ``2.'', etc. It has one mandatory argument, the number of marks allocated to the question, which is used to initialise the |qexpected| counter\footnote{If it were not for the fact that you can only refer to environment arguments in the environment preamble, the \texttt{qexpected} counter would be unnecessary.}. If the argument is left empty, default to zero for the number of marks:
% 
%    \begin{macrocode}
\newenvironment{question}[2][]{%
  \def\@keyargs{#1}%
  \ifx\@keyargs\@empty\else\pgfqkeys{/question}{#1}\fi%
%    \end{macrocode}
% If the argument for the number of marks is left empty, default to zero.
%    \begin{macrocode}
  \def\@nummarks{#2}%
  \ifx\@nummarks\@empty\setcounter{qexpected}{0}%
  \else\setcounter{qexpected}{#2}\fi%
%    \end{macrocode}
% If the expected number of marks is zero, suppress all marks display.
%    \begin{macrocode}
  \ifnum\theqexpected=0%
    \pgfqkeys{/question}{show marks=false,show total=false}%
  \fi%
%    \end{macrocode}
% |show total=true| implies |show marks=false|. It would be nice if this could just be handled in the pgfkeys initialisation, but it looks like you can't have a key with both code and a value.
%    \begin{macrocode}
  \ifquestion@showtotal\pgfqkeys{/question}{show marks=false}\fi%
%    \end{macrocode}
% 
% Check that the environment is being opened at the correct depth. The \textsf{question} environment should normally only be opened at depth 0:
%    \begin{macrocode}
  \ifnum\theqdepth=0%
  \else\ClassError{ouexam}{%
    question environment nested inside another question,^^J%
    subquestion or subsubquestion environment}%
  \fi%
  \addtocounter{qdepth}{1}%
%    \end{macrocode}
% 
% For each top-level question, we increment the |question| counter, which also
% resets the |hassubs| and |qrunning| counters to zero:
%    \begin{macrocode}
  \refstepcounter{question}%
%    \end{macrocode}
% The question itself is built using a single-item \textsf{list} environment.
%    \begin{macrocode}
  \begin{list}{\labelquestion}{\settowidth{\labelwidth}{88.}}%
    \item \ignorespaces%
%    \end{macrocode}
% 
% When the environment closes, the following things happen:
% \begin{enumerate}
%   \item If the question has no sub-questions, the value of the |qexpected| counter is added to |examrunning| and |sectrunning| (unless |verify total=false| for the current section), and |qrunning| is set to the value of |qexpected|.
% 
%    \begin{macrocode}
}{%
    \ifnum\thehassubs=0%
      \ifexamsection@verifytotal%
        \addtocounter{examrunning}{\value{qexpected}}%
        \addtocounter{sectrunning}{\value{qexpected}}%
      \fi%
      \setcounter{qrunning}{\value{qexpected}}%
%    \end{macrocode}
% 
%   The total number of marks for the question is then typeset.
% 
%    \begin{macrocode}
      \ifquestion@showmarks%
        \printmarks{\theqrunning}%
      \fi%
%    \end{macrocode}
% 
%   \item If |show total=true|, then typeset the running total for the question, similar to that for sections.
%
%    \begin{macrocode}
      \ifquestion@showtotal%
        \par\hfill%
        \textbf{[QUESTION \thequestion\ TOTAL %
          \theqrunning\ MARKS]}%
      \fi%
%    \end{macrocode}
% 
%   \item If the question \emph{does} have sub-questions, then |qrunning|, |examrunning| and |sectrunning| have already been set by the various sub-environments. The value of |qrunning| is then compared with |qexpected|, and a warning is raised if they do not match. The total number of marks for the question is \emph{not} printed in this case. If |verify total=false|, |qrunning| is just set to the value of |qexpected|.
% 
%    \begin{macrocode}
    \else%
      \ifquestion@verifytotal%
      \else\setcounter{qrunning}{\value{qexpected}}\fi%
      \ifnum\theqrunning=\theqexpected%
      \else\ClassWarning{ouexam}{%
        actual mark (\theqrunning) for question %
        \thequestion\space does not match^^J%
        expected mark (\theqexpected)}%
      \fi%
    \fi%
%    \end{macrocode}
% 
%   \item |lastexpected| is set to the value of |qexpected| so it can be used in any subsequent \textsf{marking} environment.
% 
%    \begin{macrocode}
    \setcounter{lastexpected}{\value{qexpected}}%
  \end{list}%
%    \end{macrocode}
% 
%   \item |qdepth| is decremented.
% 
%   \item \cs{questionskip} vertical space is inserted.
% 
%    \begin{macrocode}
  \addtocounter{qdepth}{-1}%
  \vskip\questionskip%
}
%    \end{macrocode}
% 
% \end{enumerate}
% \end{environment}
% 
% \begin{environment}{subquestion}
% \changes{2.0}{2000/09/11}{No longer redefines \textsf{enumerate}}
% \changes{2.0}{2001/05/13}{Penalty handling for correct marks placement}
% \changes{2.3.2}{2014/10/09}{Fixed crashing bug with verbatim environments
% appearing at the end of subquestions.}
% \changes{2.4}{2013/05/31}{Check question depth when opening the environment.}
% \changes{2.4}{2015/08/19}{Changed how question marks are positioned.}
% \changes{2.4}{2016/05/02}{Only output question marks if they're greater than zero.}
% \changes{2.4.2}{2019/08/30}{Refactored marks printing.}
% The \textsf{subquestion} environment is the analogue of \textsf{question} for
% sub-questions. On initialisation, it sets |subqexpected| to the value of the
% mandatory argument (defaulting to zero if the argument is empty), increments
% the |hassubs| counter so that the enclosing \textsf{question} environment can
% react appropriately, increments |subquestion| (thus resetting |hassubsubs| and
% |subqrunning| to zero) and opens a single-item list with numbering of the form
% ``(a)'', ``(b)'', etc.
% 
%    \begin{macrocode}
\newenvironment{subquestion}[2][]{%
  \def\@keyargs{#1}%
  \ifx\@keyargs\@empty\else\pgfqkeys{/subquestion}{#1}\fi%
  \def\@nummarks{#2}%
  \ifx\@nummarks\@empty\setcounter{subqexpected}{0}%
  \else\setcounter{subqexpected}{#2}\fi%
  \ifnum\thesubqexpected=0%
    \pgfqkeys{/subquestion}{show marks=false,show total=false}%
  \fi%
  \ifsubquestion@showtotal\pgfqkeys{/subquestion}{show marks=false}\fi%
%    \end{macrocode}
% Increment |hassubs| so that the enclosing \textsf{question} environment can react appropriately:
%    \begin{macrocode}
  \addtocounter{hassubs}{1}%
%    \end{macrocode}
% The \textsf{subquestion} environment should normally only be opened at depth 1:
%    \begin{macrocode}
  \ifnum\theqdepth=1%
  \else\ClassError{ouexam}{%
    subquestion environment either outside a question^^J%
    environment, or nested inside another subquestion or^^J%
    subsubquestion environment}%
  \fi%
  \addtocounter{qdepth}{1}%
  \refstepcounter{subquestion}%
  \begin{list}{\labelsubquestion}{\settowidth{\labelwidth}{(m)}}%
    \item \ignorespaces%
}{%
%    \end{macrocode}
% 
% When the environment closes, if performs similar checks to the
% \textsf{question} environment. If the sub-question has no sub-sub-questions,
% the value of |subqexpected| is added to |qrunning| and |sectrunning|:
% 
%    \begin{macrocode}
    \ifnum\thehassubsubs=0%
      \ifexamsection@verifytotal%
        \addtocounter{examrunning}{\value{subqexpected}}%
        \addtocounter{sectrunning}{\value{subqexpected}}%
      \fi%
%    \end{macrocode}
%
% If the parent question is |verify total=false|, don't add the marks for this sub-question to the parent's running total.
%
%    \begin{macrocode}
      \ifquestion@verifytotal%
        \addtocounter{qrunning}{\value{subqexpected}}%
      \fi%
      \setcounter{subqrunning}{\value{subqexpected}}%
%    \end{macrocode}
% Then the number of marks or the running total for the sub-question are typeset:
%    \begin{macrocode}
      \ifsubquestion@showmarks%
        \printmarks{\thesubqrunning}%
      \fi%
      \ifsubquestion@showtotal%
        \par\hfill%
        \textbf{[QUESTION \thequestion(\alph{subquestion})\ TOTAL %
          \thesubqrunning\ MARKS]}%
      \fi%
%    \end{macrocode}
% 
% If the sub-question \emph{does} have sub-sub-questions, check the running total
% against the expected number and raise an error if they don't match.
%    \begin{macrocode}
    \else%
      \ifsubquestion@verifytotal%
      \else\setcounter{subqrunning}{\value{subqexpected}}\fi%
      \ifnum\thesubqrunning=\thesubqexpected%
      \else\ClassWarning{ouexam}{%
        actual mark (\thesubqrunning) for question %
        \thequestion\thesubquestion\space does not match^^J%
        expected mark (\thesubqexpected)}%
      \fi%
    \fi%
%    \end{macrocode}
% Finally, set |lastexpected| to the value of |qexpected| so it can be used
% in any subsequent \textsf{marking} environment.
%    \begin{macrocode}
    \setcounter{lastexpected}{\value{subqexpected}}%
  \end{list}%
  \addtocounter{qdepth}{-1}%
}
%    \end{macrocode}
% \end{environment}
% 
% \begin{environment}{subsubquestion}
% \changes{2.0}{2000/09/11}{No longer redefines \textsf{enumerate}}
% \changes{2.0}{2001/05/13}{Penalty handling for correct marks placement}
% \changes{2.3.2}{2014/10/09}{Fixed crashing bug with verbatim environments
% appearing at the end of subsubquestions.}
% \changes{2.4}{2013/05/31}{Check question depth when opening the environment.}
% \changes{2.4}{2015/08/19}{Changed how question marks are positioned.}
% \changes{2.4}{2016/05/02}{Only output question marks if they're greater than zero.}
% \changes{2.4.2}{2019/08/30}{Refactored marks printing.}
% This is similar to both \textsf{question} and \textsf{subquestion}, and
% generates an appropriately numbered sub-sub-question (``(i)'', ``(ii)'', etc.).
%    \begin{macrocode}
\newenvironment{subsubquestion}[2][]{%
  \def\@keyargs{#1}%
  \ifx\@keyargs\@empty\else\pgfqkeys{/subsubquestion}{#1}\fi%
  \def\@nummarks{#2}%
  \ifx\@nummarks\@empty\setcounter{subsubqexpected}{0}%
  \else\setcounter{subsubqexpected}{#2}\fi%
  \ifnum\thesubsubqexpected=0%
    \pgfqkeys{/subsubquestion}{show marks=false}%
  \fi%
%    \end{macrocode}
% Increment |hassubsubs| so that the enclosing \textsf{subquestion} environment
% can react appropriately:
%    \begin{macrocode}
  \addtocounter{hassubsubs}{1}%
  \refstepcounter{subsubquestion}%
%    \end{macrocode}
% The \textsf{subsubquestion} environment should normally only be opened at depth 2:
%    \begin{macrocode}
  \ifnum\theqdepth=2%
  \else\ClassError{ouexam}{%
    subsubquestion environment either outside a subquestion^^J%
    environment, or nested inside another subsubquestion environment}%
  \fi%
  \addtocounter{qdepth}{1}%
  \begin{list}{\labelsubsubquestion}{\settowidth{\labelwidth}{(viii)}}%
    \item \ignorespaces%
}{%
%    \end{macrocode}
% 
% Closing this environment is a bit simpler than the previous two because we
% don't need to check whether the sub-sub-question has any sub-components (this
% never happens). All we have to do is set the appropriate counters and typeset
% the number of marks.
% 
%    \begin{macrocode}
    \ifexamsection@verifytotal%
      \addtocounter{examrunning}{\value{subsubqexpected}}%
      \addtocounter{sectrunning}{\value{subsubqexpected}}%
    \fi%
    \ifquestion@verifytotal%
      \addtocounter{qrunning}{\value{subsubqexpected}}%
    \fi%
    \ifsubquestion@verifytotal%
      \addtocounter{subqrunning}{\value{subsubqexpected}}%
    \fi%
    \ifsubsubquestion@showmarks%
      \printmarks{\thesubsubqexpected}%
    \fi%
    \setcounter{lastexpected}{\value{subsubqexpected}}%
  \end{list}%
  \addtocounter{qdepth}{-1}%
}
%    \end{macrocode}
% \end{environment}
% 
% 
% \subsection{Draft examination printing}
% 
% \begin{macro}{\@marking}
% \changes{2.0}{2001/05/17}{New macro}
% Specifying the \textsf{draft} option causes \textsf{ouexam} to print
% \fbox{DRAFT} in large letters in the footer of every page. This is drawn by
% the \cs{@draft} macro, which is included in the page footer definition of
% all the page styles for this class (see
% \hyperref[pagestyles]{section~\ref*{pagestyles}}). \textbf{Note:} Because
% the \cs{@draft} macro is included in the page footer, it will usually
% overflow the page boundaries, causing ``|Overfull \vbox|'' warnings. Note
% the extra set of braces to limit the scope of the \cs{Huge}.
% 
%    \begin{macrocode}
\if@draft\def\@draft{{\Huge\fbox{DRAFT}}}
\else\let\@draft\@empty
\fi
%    \end{macrocode}
% \end{macro}
% 
% 
% \changes{2.2}{2010/04/26}{Added time allocation macros.}
% \subsection{Time allocations}
% 
% \begin{macro}{\timeallocation}
% The \cs{timeallocation} macro takes a single argument representing the number of minutes suggested time allocation for a question, and outputs it in the form: \textbf{[The suggested time allocation for this question is \emph{t} minutes.]} The argument is not checked and can be anything (numbers, text). The macro will need to be redefined if either units other than minutes or different phrasing are required.
%    \begin{macrocode}
\newcommand{\timeallocation}[1]{%
  \textbf{[The suggested time allocation for answering this question %
           is #1 minutes.]}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\readingtime}
% The \cs{readingtime} macro takes a single argument representing the number of minutes reading time allocated to some part of the examination, and outputs it in the form: \textbf{[Allow \emph{t} minutes reading time.]} The argument is not checked and can be anything (numbers, text). The macro will need to be redefined if either units other than minutes or different phrasing are required.
%    \begin{macrocode}
\newcommand{\readingtime}[1]{\textbf{[Allow #1 minutes reading time.]}}
%    \end{macrocode}
% \end{macro}
% 
% \textsf{ouexam} currently does not check that any of these time allocations sum to the correct total. If implemented, this would work in a similar way to how marks totals are checked, and would be keyed in some way off \cs{@hours}.
% 
% 
% \subsection{Marking schedule information}
% 
% \begin{environment}{marking}
% \changes{1.2}{1999/10/26}{New environment}
% \begin{macro}{\@markingschedule}
% \changes{2.0}{2000/09/11}{Print ``MARKING SCHEDULE'' on every page if \textsf{markingschedule} is specified}
% The \textsf{marking} environment allows the specification of marking
% schedule information in the same location as the questions. If the
% \textsf{markingschedule} class option is specified, marking schedule
% information is printed in italics. In addition, \fbox{MARKING SCHEDULE} is
% printed in large letters in the header of every page. This is drawn by the
% \cs{@markingschedule} macro, which is included in the page header
% definition of all the page styles for this class (see
% \hyperref[pagestyles]{section~\ref*{pagestyles}}). Note the extra set of
% braces to limit the scope of the \cs{Huge}.
% 
%    \begin{macrocode}
\if@markingschedule
  \newenvironment{marking}{\itshape}{\normalfont}
  \def\@markingschedule{{\Huge\fbox{MARKING SCHEDULE}}}
\else
%    \end{macrocode}
% 
% Normally \textsf{marking} just maps to the \textsf{comment} environment from
% Rainer Sch\"{o}pf's \textsf{verbatim} package, i.e., marking information is not
% printed:
% 
%    \begin{macrocode}
  \let\marking\comment
  \let\endmarking\endcomment
  \let\@markingschedule\@empty
\fi
%    \end{macrocode}
% \end{macro}
% \end{environment}
% 
% 
% \subsection{Section handling}
% 
% \begin{environment}{examsection}
% \changes{2.0}{2002/01/09}{New environment}
% \changes{2.4}{2016/05/03}{Added key-value options.}
% \begin{macro}{\@defsecinst}
% \changes{2.0}{2002/01/09}{New macro}
% The \textsf{examsection} environment specifies a major section of an
% examination paper. Sections are sequentially numbered ``A'', ``B'', etc.
% The environment has three mandatory arguments:
% 
% \begin{enumerate}
%   \item The expected number of marks for the section.
% 
%   \item The instructions for this section. This defaults to ``ANSWER ALL QUESTIONS (TOTAL xx MARKS).'' if left blank (the marks total is also suppressed by |hidetotal|). To change the default text, redefine the \cs{@defsecinst} macro:
%    \begin{macrocode}
\def\@defsecinst{%
    ANSWER \underline{ALL} QUESTIONS%
    \ifexamsection@showtotal\ (TOTAL \thesectexpected\ MARKS)\fi.%
}
%    \end{macrocode}
% 
%   \item A description of the contents of the section which may be left blank.
% \end{enumerate}
%
% The optional argument to \textsf{examsection} is a list of keys that control its behaviour. The available keys are |show title| (default, opposite |hide title|), |show total| (default, opposite |hide total|), and |verify total| (default, opposite |don't verify total|).
% 
%    \begin{macrocode}
\newenvironment{examsection}[4][]{%
  \def\@keyargs{#1}%
  \ifx\@keyargs\@empty\else\pgfqkeys{/exam section}{#1}\fi%
%    \end{macrocode}
% Every section begins on a new page regardless.
%    \begin{macrocode}
  \newpage%
%    \end{macrocode}
% If the argument for the number of marks is left empty, default to zero.
%    \begin{macrocode}
  \def\@nummarks{#2}%
  \ifx\@nummarks\@empty\setcounter{sectexpected}{0}%
  \else\setcounter{sectexpected}{#2}\fi%
%    \end{macrocode}
% If the expected number of marks is zero, suppress the marks total.
%    \begin{macrocode}
  \ifnum\thesectexpected=0\pgfqkeys{/exam section}{show total=false}\fi%
  \refstepcounter{xsection}%
%    \end{macrocode}
% If |verify total=false|, set the section running total to the expected total, and add the same amount to the exam running total. Questions inside the section will honour this and not add their marks to either the section or exam running totals.
%    \begin{macrocode}
  \ifexamsection@verifytotal\setcounter{sectrunning}{0}%
  \else%
    \setcounter{sectrunning}{\value{sectexpected}}%
    \addtocounter{examrunning}{\value{sectexpected}}%
  \fi%
%    \end{macrocode}
% The section title is formatted as ``\textbf{\underline{Section A}}'', in
% \cs{large} size. Suppressed if |hide title| is specified.
%    \begin{macrocode}
  \ifexamsection@showtitle%
    {\large\noindent\textbf{\underline{Section~\thexsection}}}%
    \\[0.5\baselineskip]%
  \fi%
  \def\@usersecinst{#3}%
  \noindent\textbf{\ifx\@usersecinst\@empty\@defsecinst%
                   \else\@usersecinst\fi%
  }\par%
  \def\@usersectopic{#4}%
  \noindent\ifx\@usersectopic\@empty%
           \else\par\noindent\@usersectopic\fi \\%
}{%
%    \end{macrocode}
% 
% When the environment closes, the value of |sectrunning| is compared against
% |sectexpected|, and a warning is raised if they do not match.
%    \begin{macrocode}
  \ifnum\thesectrunning=\thesectexpected%
  \else\ClassWarning{ouexam}{%
    actual mark (\thesectrunning) for section %
    \thexsection\space does not match^^J%
    expected mark (\thesectexpected)}%
  \fi%
%    \end{macrocode}
% The total number marks for the section is printed in the form ``\textbf{[SECTION A TOTAL \emph{m} MARKS]}'' where \emph{m} is the value of |sectrunning|. The section number is suppressed if |show title=false|, while the entire total is suppressed if |show total=false|.
% 
%    \begin{macrocode}
  \ifexamsection@showtotal%
    \bigskip\hfill%
    \textbf{[\ifexamsection@showtitle{SECTION \thexsection\ }\fi%
             TOTAL \thesectrunning\ MARKS]%
    }%
  \fi%
}
%    \end{macrocode}
% \end{macro}
% \end{environment}
% 
% 
% \subsection{Title page generation}
% 
% \begin{macro}{\examyear}
% \begin{macro}{\@year}
% \changes{2.0.2}{2002/08/22}{Restored \cs{@eha} at end of \cs{ClassError}}
% The \cs{examyear} macro specifies the year in which the examination is being held. It redefines the \cs{@year} macro which is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\examyear}[1]{\def\@year{#1}}
%    \end{macrocode}
% This macro is required:
%    \begin{macrocode}
\def\@year{%
  \ClassError{ouexam}{no \protect\examyear\space was specified}\@eha%
}
%    \end{macrocode}
% I currently don't know what \cs{@eha} does, but \cs{@year} crashes without it! It seems to be required if there's a \cs{protect}. The same applies for \cs{@dept}, \cs{@pnumber}, and \cs{@ptitle} below.
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\department}
% \begin{macro}{\@dept}
% \changes{2.0.2}{2002/08/22}{Restored \cs{@eha} at end of \cs{ClassError}}
% The \cs{department} macro specifies the name of the department, and is required. It redefines the \cs{@dept} macro which is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\department}[1]{\def\@dept{#1}}
\def\@dept{%
  \ClassError{ouexam}{no \protect\department\space was specified}\@eha%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\papernumber}
% \begin{macro}{\@pnumber}
% \changes{2.0.2}{2002/08/22}{Restored \cs{@eha} at end of \cs{ClassError}}
% The \cs{papernumber} macro specifies the paper number, and is required. It redefines the \cs{@pnumber} macro which is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\papernumber}[1]{\def\@pnumber{#1}}
\def\@pnumber{%
  \ClassError{ouexam}{no \protect\papernumber\space was specified}\@eha%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\papertitle}
% \begin{macro}{\@ptitle}
% \changes{2.0.2}{2002/08/22}{Restored \cs{@eha} at end of \cs{ClassError}}
% The \cs{papertitle} macro specifies the title of the paper, and is required. It redefines the \cs{@ptitle} macro which is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\papertitle}[1]{\def\@ptitle{#1}}
\def\@ptitle{%
  \ClassError{ouexam}{no \protect\papertitle\space was specified}\@eha%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\semester}
% \changes{2.0}{2002/01/14}{Support for summer school and special exams}
% \changes{2.0.2}{2002/08/22}{Added full-year support}
% \begin{macro}{\@semester}
% The \cs{semester} macro specifies which semester the examination is for.
% Legal values for the argument are ``1'', ``2'', ``SS'' for summer school,
% ``FY'' for full-year or ``SP'' for a special examination---anything else is
% ignored.
%    \begin{macrocode}
\def\@ONE{1}
\def\@TWO{2}
\def\@SS{SS}
\def\@FY{FY}
\def\@SP{SP}
%    \end{macrocode}
% This macro redefines the \cs{@semester} macro which is used in
% \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\semester}[1]{%
  \def\@sem{#1}%
  \ifx\@sem\@ONE\def\@semester{Semester One}%
  \else\ifx\@sem\@TWO\def\@semester{Semester Two}%
  \else\ifx\@sem\@SS\def\@semester{Summer School}%
  \else\ifx\@sem\@FY\def\@semester{Full Year}%
  \else\ifx\@sem\@SP\def\@semester{Special Examination}%
  \else\ClassWarning{ouexam}{%
    invalid value `#1' for \protect\semester;^^J%
    valid values are `1', `2', `SS', `FY' and `SP'. No semester^^J%
    information will be printed}%
  \fi\fi\fi\fi\fi%
}
%    \end{macrocode}
% \cs{semester} is optional---if you omit it or give it an invalid argument,
% \cs{@semester} remains empty.
%    \begin{macrocode}
\let\@semester\@empty
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\timeallowed}
% \begin{macro}{\@hours}
% The \cs{timeallowed} macro specifies the length of the examination in hours.
% It redefines the \cs{@hours} macro which is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newcommand{\timeallowed}[1]{\def\@hours{#1}}
%    \end{macrocode}
% \cs{timeallowed} is optional---if you omit it, \cs{@hours} defaults to ``3'':
%    \begin{macrocode}
\def\@hours{3}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{num.pages}
% \changes{1.1}{1999/04/20}{Renamed from \texttt{page.last}}
% \changes{2.4}{2013/06/05}{Added check for \textsf{hyperref} being loaded.}
% There is no macro to specify the number of pages in the examination because it is done automatically by inserting a \cs{newlabel} that refers to the last page directly into the |.aux| file. The \textsf{hyperref} package redefines the \cs{newlabel} macro (in particular it increases the number of arguments), so we need to test whether \textsf{hyperref} is loaded and write the appropriate string to the |.aux| file. We borrow a technique from the \textsf{pageslts} package of checking for the existence of \cs{Hy@Warning}. (Ideally we would use \cs{if@packageloaded}, but this can't be used after \cs{AtBeginDocument}, and can be foiled by a package loading \textsf{hyperref} \cs{AtBeginDocument}.)
%    \begin{macrocode}
\AtEndDocument{%
  \@ifundefined{Hy@Warning}{% hyperref not loaded
    \immediate\write\@auxout{\string\newlabel{num.pages}{{}{\thepage}}}%
  }{% hyperref loaded
    \immediate\write\@auxout{\string\newlabel{num.pages}{{}{\thepage}{}{}{}}}%
  }%
}
%    \end{macrocode}
% This label is then referenced in \cs{@maketitlepage}.
% \end{macro}
% 
% \begin{macro}{num.questions}
% \changes{1.1}{1999/04/20}{New label for number of questions}
% \changes{2.4}{2013/06/05}{Added check for \textsf{hyperref} being loaded.}
% Similarly, there is no macro to specify the number of questions in the examination. This is calculated using the same method as for the number of pages.
%    \begin{macrocode}
\AtEndDocument{%
  \@ifundefined{Hy@Warning}{%
    \immediate\write\@auxout{\string\newlabel{num.questions}{{}{\thequestion}}}%
  }{%
    \immediate\write\@auxout{\string\newlabel{num.questions}{{}{\thequestion}{}{}{}}}%
  }%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\instructions}
% \begin{macro}{\@instructions}
% The \cs{instructions} macro specifies instructions on how candidates should
% answer questions. It redefines the \cs{@instructions} macro that is used in
% \cs{@maketitlepage}:
%    \begin{macrocode}
\def\@instructions{Answer \underline{ALL} questions.}
%    \end{macrocode}
% \cs{instructions} is optional. If you omit it, \cs{@instructions} defaults
% to ``Answer \underline{ALL} questions.'' 
%    \begin{macrocode}
\newcommand{\instructions}[1]{\def\@instructions{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@NA}
% \changes{2.1.3}{2009/04/28}{Added \cs{@NA} macro.}
% The \cs{@NA} macro enables us to easily assign and test for the default value
% (``Nil'') for some of the title page macros. (There is certain text that
% should not be output when particular macros are allowed to default.)
%    \begin{macrocode}
\def\@NA{Nil}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\material}
% \begin{macro}{\@material}
% \changes{2.1.3}{2009/04/28}{Changed default to ``N/A'' for \cs{material}.}
% \changes{2.4.2}{2019/08/30}{Changed default to ``Nil'' for \cs{material}.}
% The \cs{material} macro lets specifies any additional material that candidates
% are provided in addition to the examination paper itself, and is optional.
% It redefines the \cs{@material} macro that is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\let\@material\@NA
\newcommand{\material}[1]{\def\@material{#1}}
%    \end{macrocode}
% If you omit it, it defaults to ``Nil''.
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@inspection}
% \changes{2.4}{2016/08/27}{Refactored ``subject to inspection'' generation.}
% Various items on the title page may have ``(Subject to inspection by the examiners)'' or similar text printed below them. Redefine the \cs{@inspection} macro to change this text. (Implemented as a separate macro to enable more flexible formatting.)
%    \begin{macrocode}
\def\@inspection{(Subject to inspection by the examiners)}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\allowcalculators}
% \changes{2.1}{2004/04/05}{Conformed to new University calculator regulations}
% \begin{macro}{\@calculators}
% \changes{2.1}{2004/04/05}{Conformed to new University calculator regulations}
% \changes{2.1.2}{2008/08/14}{Ensured that the correct default is set regardless of whether the calculators macro is called.}
% \changes{2.4}{2016/08/27}{Implemented updated calculator rules for 2016 onwards.}
% \changes{2.4}{2016/08/27}{Incorporated ``subject to inspection'' line.}
% The \cs{allowcalculators} macro specifies whether or not calculators are
% allowed in the examination (\cs{permitcalculators} is a synonym). If
% \cs{allowcalculators} is omitted, \cs{@calculators} defaults to ``No
% calculators are permitted.'':
%    \begin{macrocode}
\def\@calculators{No calculators permitted.}
%    \end{macrocode}
% Issuing an \cs{allowcalculators[none]} does nothing, as the default is to disallow calculators anyway. Issuing an \cs{allowcalculators} or \cs{allowcalculators[any]} redefines \cs{@calculators} to ``Any model of calculator may be used provided it is battery powered, silent, truly portable and free of communication capabilities.'' Issuing an \cs{allowcalculators[scientific]} redefines \cs{@calculators} to ``Only calculators on the University of Otago list of approved scientific calculators may be used (any version of the following models: Casio FX82, Casio FX95, Casio FX100, Casio FX570, Sharp EL531).'' Issuing an \cs{allowcalculators[graphing]} redefines \cs{@calculators} to ``Only calculators appearing on the University of Otago list of approved scientific and graphing calculators may be used (any version of the following models: Casio FX82, Casio FX95, Casio FX100, Casio FX570, Casio FX9750, Casio FX9860, Sharp EL531).'' \emph{\textbf{[Deprecated from 2016; maintained for backwards compatibility only]} Issuing an \cs{allowcalculators[approved]} redefines \cs{@calculators} to ``Only calculators on the University of Otago list of approved calculators may be used.''}:
%    \begin{macrocode}
\def\@CalcNONE{none}
\def\@CalcANY{any}
\def\@CalcAPPROVED{approved}
\def\@CalcSCIENTIFIC{scientific}
\def\@CalcGRAPHING{graphing}

\let\@calc\@CalcNONE
\newcommand{\allowcalculators}[1][any]{%
  \def\@calc{#1}%
  \ifx\@calc\@CalcNONE%
  \else\ifx\@calc\@CalcANY\def\@calculators{Any model of calculator may be %
    used provided it is battery powered, silent, truly portable and free of %
    communication capabilities.\\[0.5\baselineskip]%
    \mbox{}\hfill\@inspection}%
  \else\ifx\@calc\@CalcAPPROVED\def\@calculators{Only calculators on %
    the University of Otago list of approved calculators may be used.\\%
    \mbox{}\hfill\@inspection}%
  \else\ifx\@calc\@CalcSCIENTIFIC\def\@calculators{Only calculators on the %
    University of Otago list of approved scientific calculators may be used %
    (any version of the following models: Casio FX82, Casio FX95, Casio FX100, %
    Casio FX570, Sharp EL531).\\%
    \mbox{}\hfill\@inspection}%
  \else\ifx\@calc\@CalcGRAPHING\def\@calculators{Only calculators on the %
    University of Otago list of approved scientific and graphing calculators %
    may be used (any version of the following models: Casio FX82, Casio FX95, %
    Casio FX100, Casio FX570, Casio FX9750, Casio FX9860, Sharp EL531).\\[0.5\baselineskip]%
    \mbox{}\hfill\@inspection}%
  \else\ClassWarning{ouexam}{%
    invalid argument `#1' for^^J%
    \protect\allowcalculators; valid values are `none', `any', `scientific', and `graphing'.^^J%
    No calculators will be permitted}%
  \fi\fi\fi\fi\fi%
}
%    \end{macrocode}
% \cs{@calculators} is used in \cs{@maketitlepage}.
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\permitcalculators}
% \changes{2.1}{2004/04/05}{New synonym for \cs{allowcalculators}}
% \cs{permitcalculators} is a synonym for \cs{allowcalculators}.
%    \begin{macrocode}
\let\permitcalculators\allowcalculators
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\copiesof}
% \begin{macro}{\@copiesof}
% \changes{2.1.3}{2009/04/28}{Changed default to ``N/A'' for \cs{copiesof}.}
% \changes{2.4}{2016/08/27}{Incorporated ``subject to inspection'' line.}
% \changes{2.4.2}{2019/08/30}{Changed default to ``Nil'' for \cs{copiesof}.}
% The \cs{copiesof} macro specifies any material that candidates are allowed to
% bring into the examination, and is optional. It redefines the \cs{@copiesof}
% macro that is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\newlength{\@inspectionwidth}
\settowidth{\@inspectionwidth}{\@inspection}

\let\@copiesof\@NA
\newcommand{\copiesof}[1]{\def\@copiesof{%
  #1%
%    \end{macrocode}
% We do some clever jiggery-pokery here (from \texttt{http://tex.stackexchange.com/questions/107726/how-to-get-the-natural-width-of-the-last-box-in-a-paragraph}) to insert extra vertical space between the text and the ``subject to inspection'' line if they overlap horizontally.
%    \begin{macrocode}
  {\abovedisplayshortskip\z@\abovedisplayskip\z@%
   \belowdisplayshortskip\z@\belowdisplayskip\z@%
   $$\global\dimen\@ne\predisplaysize%
   \xdef\tmp{%
     \predisplaysize\the\predisplaysize%
     \prevgraf\the\prevgraf\relax}%
   $$\vskip\dimexpr-\parskip-\baselineskip\relax}\tmp%
  \ifdim\dimexpr\linewidth-\dimen\@ne\relax<\@inspectionwidth%
    \vskip0.5\baselineskip%
  \fi%
  \mbox{}\hfill\@inspection%
}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\otherinstructions}
% \begin{macro}{\@otherinst}
% \changes{2.1.3}{2009/04/28}{Changed default to ``N/A'' for \cs{otherinstructions}.}
% \changes{2.4.2}{2019/08/30}{Changed default to ``Nil'' for \cs{otherinstructions}.}
% The \cs{otherinstructions} macro specifies any other instructions not covered
% by any of the above, and is optional. It redefines the \cs{@otherinst}
% macro that is used in \cs{@maketitlepage}:
%    \begin{macrocode}
\let\@otherinst\@NA
\newcommand{\otherinstructions}[1]{\def\@otherinst{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\maketitlepage}
% The \cs{maketitlepage} macro is the \textsf{ouexam} analogue of \cs{maketitle}.
% It takes all of the information provided by the above macros and generates a
% properly formatted examination title page. If you want to design your own title
% page styles, redefine \cs{@maketitlepage} (this is not normally recommended
% however).
%    \begin{macrocode}
\newcommand{\maketitlepage}{\@maketitlepage}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@maketitlepage}
% \changes{1.1}{1999/04/20}{Renamed from \cs{maketitlepage}}
% \changes{2.3.1}{2014/09/15}{Removed ``Paper'' from the title box.}
% \changes{2.4}{2013/06/05}{Added check for \textsf{hyperref} being loaded.}
% The \cs{@maketitlepage} macro generates an examination title page that meets the Otago University requirements for final examination papers. You can redefine this if you want to change the format, but normally you would not do this.
%    \begin{macrocode}
\def\@maketitlepage{%
  \thispagestyle{titlepage}%
%    \end{macrocode}
% The header information for the examination is printed centered at the top
% of the page. The department, paper number and paper title (and the semester
% information if required) are placed inside a double box.
%    \begin{macrocode}
  \begin{center}%
    {\Large \textbf{UNIVERSITY OF OTAGO EXAMINATIONS \@year}}%
    \\[\baselineskip]%
    \fbox{\framebox[\linewidth]{%
      \begin{tabular}{c}%
        \\%
        {\large \@dept} \\%
        \\%
        {\large \@pnumber} \\%
        \\%
        {\large \@ptitle} \\%
        \ifx\@semester\@empty\else\@semester \\ \fi%
        \\%
      \end{tabular}%
    }}%
    \mbox{}\\[\baselineskip]%
%    \end{macrocode}
% Next, the time allowed for completing the examination:
%    \begin{macrocode}
    \textbf{(TIME ALLOWED: \@hours\ HOURS)}%
    \\[\baselineskip]%
  \end{center}%
%    \end{macrocode}
% The number of pages is automatically calculated, as described earlier. All we need to do is \cs{pageref} the |num.pages| label that we wrote into the |.aux| file, or \cs{pageref*} if \textsf{hyperref} is loaded to inhibit hyperlink generation.
%    \begin{macrocode}
  \underline{This examination paper comprises %
    \@ifundefined{Hy@Warning}%
      {\pageref{num.pages}}%
      {\pageref*{num.pages}} %
    pages.%
  }%
  \\[\baselineskip]%
%    \end{macrocode}
% Print out the instructions for answering questions:
%    \begin{macrocode}
  \underline{Candidates should answer questions as follows:}%
  \\[\baselineskip]%
  \hspace*{\parindent}%
  \begin{minipage}{\dimexpr\textwidth-\parindent}%
    \@instructions%
  \end{minipage}%
  \\[\baselineskip]%
%    \end{macrocode}
% Print out any provided material:
%    \begin{macrocode}
  \underline{The following material is provided:}%
  \\[\baselineskip]%
  \hspace*{\parindent}%
  \begin{minipage}{\dimexpr\textwidth-\parindent}%
    \@material%
  \end{minipage}%
  \\[\baselineskip]%
%    \end{macrocode}
% Print out use of calculators section:
%    \begin{macrocode}
  \underline{Use of calculators:} \\[\baselineskip]%
  \hspace*{\parindent}%
  \begin{minipage}{\dimexpr\textwidth-\parindent}%
    \@calculators%
  \end{minipage}%
  \\[\baselineskip]%
%    \end{macrocode}
% \changes{2.1.3}{2009/04/28}{Fixed vertical spacing.}
% \changes{2.1.2}{2008/08/14}{Ensure that the ``subject to inspection'' line for calculators is only printed when calculators actually are allowed.}
% \changes{2.4}{2016-08-27}{Refactored ``subject to inspection'' line (now done in \@calculators).}
% Print out anything that candidates are allowed to bring:
%    \begin{macrocode}
  \underline{Candidates are permitted copies of:}%
  \\[\baselineskip]%
  \hspace*{\parindent}%
  \begin{minipage}{\dimexpr\textwidth-\parindent}%
    \@copiesof%
  \end{minipage}%
  \\[\baselineskip]%
%    \end{macrocode}
% \changes{2.1.3}{2009/04/28}{Fixed vertical spacing.}
% \changes{2.1.2}{2008/08/14}{Ensure that the ``subject to inspection''
% line for other material is only printed when there actually \emph{is}
% other material.}
% \changes{2.4}{2016-08-27}{Refactored ``subject to inspection'' line (now done in \@copiesof).}
% \changes{2.1.3}{2009/04/28}{Removed superfluous blank line.}
% \changes{2.4}{2016/08/26}{Added instruction for embargoed exams.}
% \changes{2.4.1}{2017/08/30}{Added detail to instruction for embargoed exams.}
% Print out other instructions, and finish. Automatically insert an instruction to hand in the entire exam if it's embargoed.
%    \begin{macrocode}
  \underline{Other Instructions:}%
  \\[\baselineskip]%
  \hspace*{\parindent}%
  \begin{minipage}{\dimexpr\textwidth-\parindent}%
    \if@embargo%
      You must hand in the entire examination paper attached to your %
      answer book(s) using the provided tie.%
      \ifx\@otherinst\@NA\else \\ \@otherinst\fi%
    \else\@otherinst%
    \fi%
  \end{minipage}%
 
  \newpage%
}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Obsolete macros and environments}
% 
% \changes{2.0}{2002/01/09}{Obsoleted all \textsf{multichoice} macros and environments}
%
% The following macros and environments are no longer supported as of version
% 2.0. Documents that use these macros can be processed using ouexam v1.2 or
% earlier. The obsolete multiple-choice examination support is dealt with
% during option processing, so we can ignore the obsolete multiple-choice
% macros.
% 
% \begin{environment}{questions}
% \changes{2.0}{2002/01/09}{Obsoleted}
% \begin{environment}{subquestions}
% \changes{1.1}{1999/04/20}{Now disabled when \textsf{multichoice} active}
% \changes{2.0}{2002/01/09}{Obsoleted}
% \begin{environment}{subsubquestions}
% \changes{1.1}{1999/04/20}{Now disabled when \textsf{multichoice} active}
% \changes{2.0}{2002/01/09}{Obsoleted}
% The \textsf{questions}, \textsf{subquestions} and \textsf{subsubquestions}
% environments have been replaced by the \textsf{question},
% \textsf{subquestion} and \textsf{subsubquestion} environments respectively.
%   \begin{macrocode}
\newenvironment{questions}{%
\def\item{\@ouexam@obsolete{questions environment}{1.2}}}{}
\newenvironment{subquestions}{%
\def\item{\@ouexam@obsolete{subquestions environment}{1.2}}}{}
\newenvironment{subsubquestions}{%
\def\item{\@ouexam@obsolete{subsubquestions environment}{1.2}}}{}
%    \end{macrocode}
% \end{environment}
% \end{environment}
% \end{environment}
% \begin{macro}{\markingschedule}
% \changes{1.2}{1999/10/26}{New macro}
% \changes{2.0}{2002/01/09}{Obsoleted}
% The \cs{markingschedule} macro has been replaced by the
% \textsf{markingschedule} class option. We can't map this to the
% \cs{@unsupported} macro because \cs{markingschedule} occurs in the document
% preamble. Mapping it to \cs{@unsupported} causes \TeX\ to blow up for some
% reason. It's safe enough to ignore it.
%   \begin{macrocode}
\let\markingschedule\@empty
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\marks}
% \changes{1.1}{1999/04/20}{Now increments \texttt{marks} counter}
% \changes{2.0}{2002/01/09}{Obsoleted}
% \changes{2.1}{2004/04/16}{Removed: e-TeX conflict}
% The \cs{marks} macro conflicted with a macro of the same name in e-TeX, so it was replaced by the argument to the various question-building environments.
% \end{macro}
% \begin{macro}{\totalmarks}
% \changes{1.1}{1999/04/20}{Removed number of marks argument}
% \changes{2.0}{2002/01/09}{Obsoleted}
% The \cs{totalmarks} macro has been replaced by automatic calculations within these environments.
%    \begin{macrocode}
\newcommand{\totalmarks}{\@ouexam@obsolete{totalmarks macro}{1.2}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\newsection}
% \changes{2.4}{2004/06/05}{Obsoleted the long-deprecated \cs{newsection} macro.}
% The \cs{newsection} macro has been deprecated since version 2.0. Ten years seems a long enough time for it to now be safe to remove completely!
%    \begin{macrocode}
\newcommand{\newsection}{\@ouexam@obsolete{newsection macro}{2.3}}
%    \end{macrocode}
% \end{macro}
% 
%
% 
% \Finale
% 
% \PrintChanges