\def\ouexamdate{4 September 2012}
\def\ouexamversion{2.3}
\def\ouexamshortdate{2012/09/04}
% \iffalse meta-comment
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% File: $Id$
%% Copyright 1999--2006 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
\usepackage{graphicx}
% change hyperref options as required
\usepackage[colorlinks,pdfpagemode=None,urlcolor=blue,
linkcolor=red,pdfauthor={Nigel Stanger}]{hyperref}
\title{The \textsf{ouexam} document class, v\ouexamversion}
\author{Nigel Stanger\\nstanger@infoscience.otago.ac.nz}
\date{\ouexamdate}
\begin{document}
\maketitle
\DocInput{ouexam.dtx}
\end{document}
%</driver>
%
% \fi
%
%% \CheckSum{889}
%%
%% \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}{NJS Added requirements and installation instructions.}
% \changes{2.3}{2012/09/04}{NJS 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}{NJS Added 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 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.
% \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.
%
%
% \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).
%
%
% \changes{2.1.1}{2006/08/21}{NJS Updated \textsf{lastpage} style to display
% ``\textbf{END}''.}
% \subsection{Page styles}
%
% There are three 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.
% This is the default page style.
%
% \item[\textsf{lastpage}] \DescribeMacro{lastpage} This is similar to
% \textsf{plain} but with ``\textbf{END}'' instead of ``\textbf{TURN
% OVER}''. It is used for the last page of the examination. You
% normally will not have to use this yourself---the class should take
% care of it automatically. The class does however occasionally seem
% to get confused, so there may times when you have to set the page
% style of the last page manually. It will be fairly obvious when you
% need to do this---the usual effect is that the last page
% has ``\textbf{TURN OVER}'' printed on it when it should not.
%
% \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. As with \textsf{lastpage}, 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}{NJS Moved the title page subsection to the start
% of this section.}
% \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{1999}|. 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}{NJS Added `FY' to the \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.
%
% \changes{2.1}{2004/04/05}{NJS Modified \cs{allowcalculators} to conform
% to the new University calculator regulations.}
% \changes{2.1}{2004/04/05}{NJS Added \cs{permitcalculators} as a synonym
% for \cs{allowcalculators}.}
% 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. \cs{allowcalculators} 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{approved}] A sentence is inserted noting that only approved
% 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.
%
% 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, \ldots. Rather than redefine the existing section macros, this class
% defines an \DescribeEnv{examsection} \textsf{examsection}
% environment\footnote{Note that the old \cs{newsection} macro has been
% retained for backwards compatibility with earlier development versions of
% \textsf{ouexam}. The \textsf{examsection} environment replaces this macro
% and should be used in all new documents.} 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. \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.
% 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]}'' as an additional verification.
%
% \item Instructions for answering questions in this section (such as
% ``Answer any TWO questions.''). If you leave this argument empty it
% defaults to ``ANSWER ALL QUESTIONS.''.
%
% \item A description of the topic of the section. This can be left
% empty.
% \end{enumerate}
% Every section begins on a new page, and the section title is formatted as
% ``\textbf{\underline{Section A}}'', in \cs{large} size. 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]
% ANSWER ALL QUESTIONS. \\
% These questions are remarkably boring. \\
% \hspace*{2cm}\vdots \\
% \mbox{}\hfill\textbf{[SECTION A 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 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);
%
% \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.2}{2010/04/26}{NJS 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}{NJS 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 examinationss 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{INCOMPATIBLE (\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. \\
%
%
% \subsection{Warnings}
%
% \noindent\texttt{actual number of marks for exam (\ldots) does not match
% expected} \\
% \texttt{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} \\
% \texttt{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} \\
% \texttt{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. \\
%
% \noindent\texttt{DEPRECATED: The \cs{newsection} macro is deprecated; use
% the} \\
% \texttt{examsection environment instead} \\
% The \cs{newsection} macro is a hangover from earlier versions of
% \textsf{ouexam}, and has been left in v2.0 for backwards compatibility with
% some documents that use it. The entire sectioning mechanism was rewritten
% from scratch for v2.0, so this macro is now deprecated and will eventually
% disappear. You should use the \textsf{examsection} environment
% instead. \\
%
% \changes{2.0.2}{2002/08/22}{NJS Added `FY' to \cs{semester} error
% description.}
% \noindent\texttt{invalid value `\ldots' for \cs{semester}; valid values are
% `1', `2', `SS',} \\*
% \texttt{`FY' and `SP'. No semester information will be printed} \\*
% You have given 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}{NJS Added \cs{allowcalculators} error
% description.}
% \noindent\texttt{invalid value `\ldots' for \cs{allowcalculators}; valid values are \\*
% `none', `any' and `approved'. No calculators will be permitted} \\*
% You have given 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{2.1}{2004/04/10}{NJS Updated example to conform to 2.1 changes.}
% \changes{2.0}{2002/01/25}{NJS Updated example to conform to 2.0 changes.}
% \changes{1.1}{1999/04/20}{NJS Updated example to conform to 1.1 changes.}
% 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{}
%
% \changes{2.0}{2002/01/10}{NJS 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}{\@unsupported}
% \changes{2.0}{2002/01/10}{NJS New \cs{@unsupported} macro.}
% 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\@unsupported#1{\ClassError{ouexam}{INCOMPATIBLE (#1): this %
document was written for an earlier version of ouexam and is %
not compatible with ouexam v\ouexamversion\space Please use ouexam %
v1.2 or earlier to process this document. Version 1.2 can be %
downloaded from the same location as version\space\ouexamversion}}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{multichoice}
% \changes{1.1}{1999/04/20}{NJS New \textsf{multichoice} class option.}
% \changes{2.0}{2000/09/04}{NJS Removed support for \textsf{multichoice} 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}{%
\OptionNotUsed\@unsupported{multichoice class option}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{twoside}
% \changes{1.1}{1999/04/20}{NJS Turned off \textsf{twoside} 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}{\OptionNotUsed}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{10pt}
% \begin{macro}{11pt}
% \changes{2.3}{1999/04/20}{NJS 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}{\OptionNotUsed}
\DeclareOption{11pt}{\OptionNotUsed}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{draft}
% \changes{2.0}{2001/05/15}{NJS New \textsf{draft} class option.}
% \begin{macro}{\if@draft}
% \changes{2.0}{2001/05/15}{NJS 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}
% does this need to be passed to the article class?
% \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}{NJS New \textsf{markingschedule} class option.}
% \begin{macro}{\if@markingschedule}
% \changes{2.0}{2000/09/05}{NJS 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}{NJS New \textsf{times} class option.}
% \begin{macro}{\if@times}
% \changes{2.3}{2012/09/03}{NJS New switch for \textsf{times}.}
% The \textsf{times} option formats the exam paper using 13pt Times. If this
% option is not specified, then the exam paper is formatted using 12pt Palatino.
%
% \begin{macrocode}
\newif\if@times \@timesfalse
\DeclareOption{times}{\@timestrue}
% \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}{NJS Changed default point size to 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}{NJS Removed requirement for \textsf{calc} and
% \textsf{ifthen} packages.}
% The \textsf{verbatim} package, is used to implement the \textsf{marking}
% environment:
%
% \begin{macrocode}
\RequirePackage{verbatim}
% \end{macrocode}
%
% \changes{2.3}{2012/09/04}{NJS 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.3}{2012/09/04}{NJS 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}
%
% \changes{2.0}{2001/05/17}{NJS Added support to page styles for \textsf{draft}
% and \textsf{markingschedule} class options.}
% \changes{2.0}{2002/01/15}{NJS Fixed headers so that the page number is always
% centered.}
% \changes{2.1.1}{2006/08/21}{NJS Updated \textsf{lastpage} style to display
% ``\textbf{END}''.}
% \changes{2.3}{2012/09/03}{NJS 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.}
%
% \begin{macro}{\ps@plain}
% 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{TURN OVER}}}}%
\let\@evenfoot\@oddfoot%
}
% \end{macrocode}
% \end{macro}
%
% \textsf{plain} is the default page style:
% \begin{macrocode}
\pagestyle{plain}
% \end{macrocode}
%
% \begin{macro}{\ps@lastpage}
% The \textsf{lastpage} page style is similar to \textsf{plain}, but with
% ``\textbf{END}'' instead of ``\textbf{TURN OVER}'':
% \begin{macrocode}
\def\ps@lastpage{%
\def\@oddhead{\@markingschedule\hfill\@pnumber%
\ifx\@semester\@empty\else\ (\@semester)\fi}%
\let\@evenhead\@oddhead%
\def\@oddfoot{%
\rlap{\parbox[b]{\columnwidth}{\raggedright\@draft\strut}}\hfill%
\parbox[b]{\columnwidth}{\centering\textrm{\thepage}\strut}\hfill%
\llap{\parbox[b]{\columnwidth}{\raggedleft\textbf{END}}}}%
\let\@evenfoot\@oddfoot%
}
% \end{macrocode}
% \end{macro}
%
% \textsf{lastpage} should be automatically applied to the last page of the
% document:
% \begin{macrocode}
\AtEndDocument{\thispagestyle{lastpage}}
% \end{macrocode}
%
% \begin{macro}{\ps@titlepage}
% The \textsf{titlepage} page style is similar to \textsf{plain}, but without
% the header.
% \begin{macrocode}
\def\ps@titlepage{%
\def\@oddhead{\@markingschedule}%
\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}{NJS New \texttt{subquestion} counter.}
% \changes{2.0.1}{2000/04/30}{NJS Removed prefixed question number from
% \cs{labelsubquestion} macro so that references now print as just ``(a)''
% instead of ``1(a)''.}
% \begin{macro}{subsubquestion}
% \changes{2.0}{2000/09/11}{NJS New \texttt{subsubquestion} counter.}
% \changes{2.0.1}{2000/04/30}{NJS The \texttt{subsubquestion} was incorrectly
% printing as ``(a)'' rather than ``(i)''. Fixed.}
% \changes{2.0.1}{2000/04/30}{NJS Removed prefixed question numbers from
% \cs{labelsubsubquestion} macro so that references now print as just ``(i)''
% instead of ``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}{NJS New \texttt{examexpected} 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}{NJS New \texttt{examoutof} 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}{NJS New \cs{sectexpected} counter.}
% \begin{macro}{qexpected}
% \changes{2.0}{2000/09/11}{NJS New \cs{qexpected} counter.}
% \begin{macro}{subqexpected}
% \changes{2.0}{2000/09/11}{NJS New \texttt{subqexpected} counter.}
% \begin{macro}{subsubqexpected}
% \changes{2.0}{2000/09/11}{NJS New \texttt{subsubqexpected} 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}{NJS New \texttt{lastexpected} 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}{examrunning}
% \changes{2.0}{2000/09/11}{NJS New \texttt{examrunning} counter.}
% \begin{macro}{sectrunning}
% \changes{2.0}{2002/01/09}{NJS New \texttt{sectrunning} counter.}
% \begin{macro}{qrunning}
% \changes{2.0}{2000/09/11}{NJS New \texttt{qrunning} counter.}
% \begin{macro}{subqrunning}
% \changes{2.0}{2000/09/11}{NJS New \texttt{subqrunning} 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
% |qrunning| and |subqrunning| counters are reset when the associated
% question counters are incremented.
%
% \begin{macrocode}
\newcounter{examrunning}
\setcounter{examrunning}{0}
\newcounter{sectrunning}
\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}{NJS New \texttt{hassubs} counter.}
% \begin{macro}{hassubsubs}
% \changes{2.0}{2000/09/11}{NJS New \texttt{hassubsubs} 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}
%
% 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 match expected number of marks %
(\theexamexpected)}%
\fi%
}
% \end{macrocode}
%
% \begin{macro}{xsection}
% \changes{2.0}{2002/01/29}{NJS New \texttt{xsection} counter.}
% Finally, we 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}
%
%
% \subsection{Question-building environments and associated items}
%
% \changes{2.0}{2000/09/11}{NJS \textsf{question} environment no longer a
% redefinition of \textsf{enumerate}.}
% \changes{2.0}{2001/05/15}{NJS Added penalty handling to ensure correct
% placement of marks in output.}
% \changes{2.0}{2001/05/15}{NJS Total marks for a question are now printed only
% if the question has no sub-questions.}
% \begin{environment}{question}
% 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}[1]{%
\def\@nummarks{#1}%
\ifx\@nummarks\@empty\setcounter{qexpected}{0}%
\else\setcounter{qexpected}{#1}\fi%
% \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|, and both |qrunning|
% and |lastexpected| are set to the value of |qexpected|.
%
% \begin{macrocode}
}{%
\ifnum\thehassubs=0%
\addtocounter{examrunning}{\value{qexpected}}%
\addtocounter{sectrunning}{\value{qexpected}}%
\setcounter{qrunning}{\value{qexpected}}%
% \end{macrocode}
%
% The total number of marks for the question is then printed right-justified
% on the line as ``(\emph{m} marks)'' where \emph{m} is the value of the
% |qrunning| counter. The environment 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}:
%
% \begin{macrocode}
\unskip\nobreak\hfil\penalty50\hskip2em\hbox{}\nobreak%
\hfil(\theqrunning~\ifnum\theqrunning=1 mark\else marks\fi)%
\parfillskip=0pt \finalhyphendemerits=0 \par%
% \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.
%
% \begin{macrocode}
\else%
\ifnum\theqrunning=\theqexpected%
\else\ClassWarning{ouexam}{actual mark (\theqrunning) for %
question \thequestion\space doesn't match 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}
%
% \end{enumerate}
% \end{environment}
%
% \begin{environment}{subquestion}
% \changes{2.0}{2000/09/11}{NJS \textsf{subquestion} environment no longer a
% redefinition of \textsf{enumerate}.}
% \changes{2.0}{2001/05/13}{NJS Added penalty handling to ensure correct placement
% of marks in output.}
% 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}[1]{%
\def\@nummarks{#1}%
\ifx\@nummarks\@empty\setcounter{subqexpected}{0}%
\else\setcounter{subqexpected}{#1}\fi%
\setcounter{subqexpected}{#1}%
\addtocounter{hassubs}{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%
\addtocounter{examrunning}{\value{subqexpected}}%
\addtocounter{sectrunning}{\value{subqexpected}}%
\addtocounter{qrunning}{\value{subqexpected}}%
\setcounter{subqrunning}{\value{subqexpected}}%
% \end{macrocode}
% Then the number of marks for the sub-question are typeset in a similar manner
% to the \textsf{question} environment:
% \begin{macrocode}
\unskip\nobreak\hfil\penalty50\hskip2em\hbox{}\nobreak%
\hfil(\thesubqrunning~\ifnum\thesubqrunning=1 mark\else marks\fi)%
\parfillskip=0pt \finalhyphendemerits=0 \par%
% \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%
\ifnum\thesubqrunning=\thesubqexpected%
\else\ClassWarning{ouexam}{actual mark (\thesubqrunning) for %
question \thesubquestion\space doesn't match 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}%
}
% \end{macrocode}
% \end{environment}
%
% \begin{environment}{subsubquestion}
% \changes{2.0}{2000/09/11}{NJS \textsf{subsubquestion} environment no longer a
% redefinition of \textsf{enumerate}.}
% \changes{2.0}{2001/05/13}{NJS Added penalty handling to ensure correct placement
% of marks in output.}
% 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}[1]{%
\def\@nummarks{#1}%
\ifx\@nummarks\@empty\setcounter{subsubqexpected}{0}%
\else\setcounter{subsubqexpected}{#1}\fi%
% \end{macrocode}
% Increment |hassubsubs| so that the enclosing \textsf{subquestion} environment
% can react appropriately:
% \begin{macrocode}
\addtocounter{hassubsubs}{1}%
\refstepcounter{subsubquestion}%
\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}
\addtocounter{examrunning}{\value{subsubqexpected}}%
\addtocounter{sectrunning}{\value{subsubqexpected}}%
\addtocounter{qrunning}{\value{subsubqexpected}}%
\addtocounter{subqrunning}{\value{subsubqexpected}}%
\setcounter{lastexpected}{\value{subsubqexpected}}%
\unskip\nobreak\hfil\penalty50\hskip2em\hbox{}\nobreak%
\hfil(\thesubsubqexpected~\ifnum\thesubsubqexpected=1 mark%
\else marks\fi)%
\parfillskip=0pt \finalhyphendemerits=0 \par%
\end{list}%
}
% \end{macrocode}
% \end{environment}
%
% Note that none of these three environments check whether they are correctly
% nested (i.e., \textsf{subsubquestion} within \textsf{subquestion} within
% \textsf{question}).
%
%
% \subsection{Draft examination printing}
%
% \begin{macro}{\@marking}
% \changes{2.0}{2001/05/17}{NJS New \cs{@draft} 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}{NJS 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}
% \begin{macro}{\@markingschedule}
% \changes{1.2}{1999/10/26}{NJS New \textsf{marking} environment for including
% answers and/or marking schedule information.}
% \changes{2.0}{2000/09/11}{NJS Now prints ``MARKING SCHEDULE'' at the bottom
% of every page if the \textsf{markingschedule} class option 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}
%
% \changes{2.0}{2002/01/09}{NJS new \textsf{examsection} environment.}
% \changes{2.0}{2002/01/09}{NJS New \cs{@defsecinst} macro.}
% \begin{environment}{examsection}
% \begin{macro}{\@defsecinst}
% The \textsf{examsection} environment specifies a major section of an
% examination paper. Sections are sequentially numbered ``A'', ``B'', etc. The
% environment has three arguments:
%
% \begin{enumerate}
% \item The expected number of marks for the section.
%
% \item The instructions for this section. This defaults to ``ANSWER ALL
% QUESTIONS.'' if left blank. To change the default text, redefine the
% \cs{@defsecinst} macro.
% \begin{macrocode}
\def\@defsecinst{ANSWER ALL QUESTIONS.}
% \end{macrocode}
%
% \item A description of the contents of the section which may be left blank.
% \end{enumerate}
%
% \begin{macrocode}
\newenvironment{examsection}[3]{%
% \end{macrocode}
% Every section begins on a new page.
% \begin{macrocode}
\newpage%
% \end{macrocode}
% If the argument for the number of marks is left empty, default to zero.
% \begin{macrocode}
\def\@nummarks{#1}%
\ifx\@nummarks\@empty\setcounter{sectexpected}{0}%
\else\setcounter{sectexpected}{#1}\fi%
\refstepcounter{xsection}%
\setcounter{sectrunning}{0}%
% \end{macrocode}
% The section title is formatted as ``\textbf{\underline{Section A}}'', in
% \cs{large} size.
% \begin{macrocode}
{\large\noindent\textbf{\underline{Section~\thexsection}}}%
\\[0.5\baselineskip]%
\def\@usersecinst{#2}%
\ifx\@usersecinst\@empty\@defsecinst\else\@usersecinst\fi\par%
\def\@usersectopic{#3}%
\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. 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|.
%
% \begin{macrocode}
\ifnum\thesectrunning=\thesectexpected%
\else\ClassWarning{ouexam}{actual mark (\thesectrunning) for section %
\thexsection\space doesn't match expected mark (\thesectexpected)}%
\fi%
\bigskip\hfill\textbf{[SECTION \thexsection\ TOTAL %
\thesectrunning\ MARKS]}%
}
% \end{macrocode}
% \end{macro}
% \end{environment}
%
% \begin{macro}{\newsection}
% \textbf{[DEPRECATED]} The \cs{newsection} macro generates a new examination
% section, appropriately numbered. The optional argument contains instructions
% for answering the questions in the new section, and defaults to ``ANSWER ALL
% QUESTIONS''. This macro is included only for backwards compatibility with
% previous versions. The \textsf{examsection} environment replaces this macro
% and should be used in new documents. This macro will eventually be deleted.
% \begin{macrocode}
\newcommand{\newsection}[1][ANSWER ALL QUESTIONS.]{%
\ClassWarning{ouexam}{DEPRECATED: The \protect\newsection\space %
macro is deprecated; use the examsection environment instead}%
% \end{macrocode}
% Every section begins on a new page.
% \begin{macrocode}
\newpage%
\refstepcounter{xsection}%
% \end{macrocode}
% The section title is formatted as ``\textbf{\underline{Section A}}'', in
% \cs{large} size. Note that sections are ``numbered'' A, B, \ldots.
% \begin{macrocode}
{\large\noindent\textbf{\underline{Section~\thexsection}}}%
\\[0.5\baselineskip]%
#1%
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Title page generation}
%
% \begin{macro}{\examyear}
% \begin{macro}{\@year}
% \changes{2.0.2}{2002/08/22}{NJS Put back \@eha at end of the \ClassError. Don't
% know what this does, but the macro crashes without it there.}
% 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}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\department}
% \begin{macro}{\@dept}
% \changes{2.0.2}{2002/08/22}{NJS Put back \@eha at end of the \ClassError. Don't
% know what this does, but the macro crashes without it there.}
% 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}{NJS Put back \@eha at end of the \ClassError. Don't
% know what this does, but the macro crashes without it there.}
% 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}{NJS Put back \@eha at end of the \ClassError. Don't
% know what this does, but the macro crashes without it there.}
% 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}
% \begin{macro}{\@semester}
% \changes{2.0.2}{2002/08/22}{NJS Added full-year support to \cs{semester}.}
% \changes{2.0}{2002/01/14}{NJS Rewrote \cs{semester} to support summer school
% and special exams.}
% 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; valid values are `1', `2', `SS', %
`FY' and `SP'. No semester 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}{NJS Renamed label from \cs{page.last}.}
% 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:
% \begin{macrocode}
\AtEndDocument{%
\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}{NJS New \cs{num.questions} label representing the
% number of questions.}
% 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{%
\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}{NJS Added \cs{@NA} macro.}
% The \cs{@NA} macro enables us to easily assign and test for the default value
% (``N/A'') 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{N/A}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\material}
% \begin{macro}{\@material}
% \changes{2.1.3}{2009/04/28}{NJS Changed default to ``N/A'' 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 ``N/A''.
% \end{macro}
% \end{macro}
%
% \begin{macro}{\allowcalculators}
% \begin{macro}{\@calculators}
% \changes{2.1}{2004/04/05}{NJS Modified calculator macros to conform to
% new University calculator regulations.}
% 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 are 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 ``No
% restriction on the model of calculator to be used, but no device with
% communication capability shall be accepted as a calculator.'' Issuing an
% \cs{allowcalculators[approved]} redefines \cs{@calculators} to ``Only
% calculators on the University of Otago list of approved calculators are
% permitted.'':
% \begin{macrocode}
\def\@CalcNONE{none}
\def\@CalcANY{any}
\def\@CalcAPPROVED{approved}
% \end{macrocode}
% \changes{2.1.2}{2008/08/14}{NJS Ensured that the correct default is set
% regardless of whether the calculators macro is called.}
% \begin{macrocode}
\let\@calc\@CalcNONE
\newcommand{\allowcalculators}[1][any]{%
\def\@calc{#1}%
\ifx\@calc\@CalcNONE%
\else\ifx\@calc\@CalcANY\def\@calculators{No restriction on the %
model of calculator to be used, but no device with communication %
capability shall be accepted as a calculator.}%
\else\ifx\@calc\@CalcAPPROVED\def\@calculators{Only calculators on %
the University of Otago list of approved calculators are permitted.}%
\else\ClassWarning{ouexam}{invalid argument `#1' for %
\protect\allowcalculators; valid values are `none', `any' and %
`approved'. %
No calculators will be permitted}%
\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}{NJS Added \cs{permitcalculators} as a 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}{NJS Changed default to ``N/A'' 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}
\let\@copiesof\@NA
\newcommand{\copiesof}[1]{\def\@copiesof{#1}}
% \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\otherinstructions}
% \begin{macro}{\@otherinst}
% \changes{2.1.3}{2009/04/28}{NJS Changed default to ``N/A'' 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}{NJS Renamed macro from \cs{maketitlepage}.}
% 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 Paper \@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 reference the |num.pages| label that we put into the |.aux|
% file:
% \begin{macrocode}
\underline{This examination paper comprises \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*{1cm}\begin{minipage}{13.5cm}\@instructions\end{minipage}%
\\[\baselineskip]%
% \end{macrocode}
% Print out any provided material:
% \begin{macrocode}
\underline{The following material is provided:}%
\\[\baselineskip]%
\hspace*{1cm}\begin{minipage}{13.5cm}\@material\end{minipage}%
\\[\baselineskip]%
% \end{macrocode}
% Print out use of calculators section:
% \begin{macrocode}
\underline{Use of calculators:} \\[\baselineskip]%
\hspace*{1cm}\begin{minipage}{13.5cm}\@calculators\end{minipage}%
\\[\baselineskip]%
% \end{macrocode}
% \changes{2.1.3}{2009/04/28}{NJS Fixed vertical spacing.}
% \changes{2.1.2}{2008/08/14}{NJS Ensure that the ``subject to inspection''
% line for calculators is only printed when calculators actually are allowed.}
% Only print out the ``subject to inspection'' line if calculators actually
% are allowed (irrelevant otherwise):
% \begin{macrocode}
\ifx\@calc\@CalcNONE%
\else\mbox{}\hfill(Subject to inspection by the examiners.)%
\\[\baselineskip]%
\fi%
% \end{macrocode}
% Print out anything that candidates are allowed to bring:
% \begin{macrocode}
\underline{Candidates are permitted copies of:}%
\\[\baselineskip]%
\hspace*{1cm}\begin{minipage}{13.5cm}\@copiesof\end{minipage}%
\\[\baselineskip]%
% \end{macrocode}
% \changes{2.1.3}{2009/04/28}{NJS Fixed vertical spacing.}
% \changes{2.1.2}{2008/08/14}{NJS Ensure that the ``subject to inspection''
% line for other material is only printed when there actually \emph{is}
% other material.}
% Only print out the ``subject to inspection'' line if there actually
% \emph{is} other material (irrelevant otherwise):
% \begin{macrocode}
\ifx\@copiesof\@NA%
\else\mbox{}\hfill(Subject to inspection by the examiners.)%
\\[\baselineskip]%
\fi%
% \end{macrocode}
% \changes{2.1.3}{2009/04/28}{NJS Removed superfluous blank line.}
% Print out other instructions, and finish.
% \begin{macrocode}
\underline{Other Instructions:}%
\\[\baselineskip]%
\hspace*{1cm}\begin{minipage}{13.5cm}\@otherinst\end{minipage}%
\newpage%
}
% \end{macrocode}
% \end{macro}
%
%
% \subsection{Obsolete macros and environments}
%
% \changes{2.0}{2002/01/09}{NJS All \textsf{multichoice} macros and environments
% made obsolete.}
% \changes{2.0}{2002/01/09}{NJS \cs{markingschedule}, \cs{marks}, \cs{totalmarks}
% macros made obsolete.}
% \changes{2.0}{2002/01/09}{NJS \textsf{questions}, \textsf{subquestions},
% \textsf{subsubquestions} environments made obsolete.}
% 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}
% \begin{environment}{subquestions}
% \changes{1.1}{1999/04/20}{NJS Now disabled when \textsf{multichoice} is
% active.}
% \begin{environment}{subsubquestions}
% \changes{1.1}{1999/04/20}{NJS Now disabled when \textsf{multichoice} is
% active.}
% \begin{macro}{markingschedule}
% \changes{1.2}{1999/10/26}{NJS New macro to turn marking information on and
% off.}
% 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{\@unsupported{questions environment}}}{}
\newenvironment{subquestions}{%
\def\item{\@unsupported{subquestions environment}}}{}
\newenvironment{subsubquestions}{%
\def\item{\@unsupported{subsubquestions environment}}}{}
% \end{macrocode}
% 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}
% \end{environment}
% \end{environment}
% \end{environment}
%
% \changes{2.1}{2004/04/16}{NJS Removed the \texttt{marks} macro entirely
% because it conflicts with a macro in e-TeX.}
% \changes{1.1}{1999/04/20}{NJS This macro now increments the \texttt{marks}
% counter.}
% \begin{macro}{\totalmarks}
% \changes{1.1}{1999/04/20}{NJS Removed the parameter for the number of marks;
% Both these macros have been replaced by automatic calculations within the
% question-building environments.}
% The \cs{marks} macro has been replaced by the argument to the various
% question-building environments. The \cs{totalmarks} macro has been replaced
% by automatic calculations within these environments.
% \begin{macrocode}
\newcommand{\totalmarks}{\@unsupported{totalmarks macro}}
% \end{macrocode}
% \end{macro}
%
%
%
% \Finale
%
% \PrintChanges
