\documentclass[12pt,a4paper]{amsart}

\usepackage{times, fancybox, a4wide}

\chardef\bs=`\\

\begin{document}

\title{\texttt{ymexam}, a \LaTeXe\ class for examination papers}
\date{October 2009}
\author{Simon Eveson}
\maketitle

\section{Introduction}

\texttt{ymexam.cls} is a \LaTeXe\ class file for producing examination
papers in the style required for the York Mathematics department. It
replaces \texttt{exam.cls} which was in use up to academic year 2005/06;
the name has changed partly because this version is very slightly
incompatible with the older version, and partly because most \LaTeX\
intallations now come with an unrelated file called \texttt{exam.cls}.

The class provides:
\begin{itemize}
\item a front page, with the examination's title, module number,
  duration and rubric, set in the approved format;
\item a numbered \verb|question| environment, which does not allow questions 
  to be broken across pages without specific instructions from the user;
\item automatic handling of page footers like \emph{turn over} and 
  \emph{continued on next page};
\item facilities for displaying and totalling marking schemes;
\item a numbered \verb|solution| environment.
\end{itemize}

\section{Installation}

The current version of \texttt{ymexam.cls}, some supporting files and the
old \texttt{exam.cls} are all available on the Department's web-server:
from Staff Home, go to Examinations, then LaTeX Class File for Examinations.
The URL at time of writing is
\begin{verbatim}
http://maths.york.ac.uk/moodle/mod/book/view.php?id=25405&chapterid=470
\end{verbatim}
You should put the class file \texttt{ymexam.cls} either in the same
directory (folder) as the document you are working on, or in a global
inputs directory. 
\footnote{If you're using the old \texttt{exam.cls}, note that there is another 
file called \texttt{exam.cls} which ships with current versions of \LaTeX, 
and it is important to put the local class ahead of this in the search order.}
The following places should work:
\begin{description}
\item[central Unix] \verb|~/texmf/tex/latex|
\item[supported Windows] \verb|h:\texmf\tex\latex\|
\item[other miktex installation] \verb|c:\localtexmf\tex\latex\|
\end{description}
If you use Miktex, you'll need to register the file's existence.
Click on Start, Run, type \texttt{mo}, press Return, select the Roots
tab, click on the root corresponding to where you put \texttt{ymexam.cls}
(e.g. \verb|h:\texmf| or \verb|c:\localtexmf|), click on Refresh FNDB,
click on OK. If you want to use both central Unix and a Miktex
installation in parallel, sharing a local tree, you can create a new
root at \verb|m:\texmf|.

There are various sample files available; take a look at them to see the way 
the system works, or use one as the basis for your own file.

\section{Class Declaration}

\verb|ymexam| is a \LaTeXe\ class file, so your document should begin

\begin{verbatim}
\documentclass{ymexam}
\end{verbatim}

By default, this class uses 12pt type on A4 paper and produces output
suitable for double-sided duplication. There is rarely any need to
change this, but any option understood by the \texttt{extarticle} class, and 
therefore any option understood by the standard \texttt{article} class, is 
also understood by \texttt{ymexam}. In particular, the font sizes
14pt, 17pt and 20pt can be used to make large-font copies for students
with visual impairments (sizes other than 12pt should only be used in
consultation with the University Examinations Office and Disability Support).
\footnote{Prior to Summer~2009, \texttt{ymexam}'s base class was
  \texttt{article}, not \texttt{extarticle}, so the large font sizes were
  not available.}

\section{Packages}

The \verb|ymexam| class automatically loads the AMS packages
\verb|amsmath|, \verb|amsfonts| and the extended verbatim environments
from \verb|verbatim|.

Any other packages required can be loaded with a \verb|\usepackage{}|
declaration, as usual.

\section{Topmatter}

Unlike most classes, topmatter is mandatory in the \texttt{ymexam} class.
After \verb|\begin{document}|, you must specify the paper's title, the
module number, the duration of the examination, the year and you must
provide a rubric. When specifying the duration, the macro \verb|\half| 
is provided as a convenient way to produce $\frac{1}{2}$. For example,

\begin{verbatim}
%\resit
\codenumber{0500010}
\year{2006}
\title{Analysis I}
\duration{$1\half$ hours}

\begin{rubric}
  Answer \underline{all} parts of Question~1 and \underline{two} 
  of the remaining three questions. \\
  Question~1 carries 40~marks; questions~2, 3~and~4 carry 
  25~marks each. \\
  Standard calculators will be provided. \\
  The marking scheme shown on each question is indicative only.
\end{rubric}

\maketitle
\end{verbatim}

Note the \verb|\maketitle| command, which actually prints the topmatter.
In the \verb|rubric| environment, indicate line breaks with \verb|\\| where
required. The rubric is printed in flush left italic type.

By default, the paper is headed `BA, BSc and MMath Examinations.' To
change this (for type IV third year courses, fourth year courses
and masters courses), use some combination of the macros \verb|\BABSc|,
\verb|\noBABSc|, \verb|\MMath|, \verb|\noMMath|, \verb|\MSc|,
\verb|noMSc|, \verb|\MRes| and \verb|\noMRes|.\footnote{There is an
  extensive array of synonyms for these for compatibility with existing 
  documents; if it worked in an earier version, it still works now.}

If the paper is a resit paper, put \verb|\resit| at the \emph{beginning}
of the topmatter. This automatically inserts the word `Resit' before 
`Examinations' in the heading, and prefixes the module number with the letter
R. \footnote{For compatibility with existing documents, you can supply the
  R yourself, e.g. \texttt{\bs{}codenumber\{R0500010\}} will work correctly.}

The \verb|rubric| environment can contain most \LaTeX\ constructs. The
only exceptions are those relating to page layout: you cannot use
footnotes or marginal notes and you cannot split the rubric across a page.

The other topmatter commands can contain any \LaTeX\ macros you need, but
for \LaTeX{}nical reasons cannot contain environments. I can't imagine
this being a problem, but let me know if it is.

As of October 2007, in accord with guidance from the Examinations Office, 
the class default is that nothing is printed on the first page except the 
topmatter. This can be changed (against University policy!) by using
\verb|\questionfrontpage| before the \verb|\maketitle| command, in which
case the first question goes on the front page (if it will fit without
breaking; see the next section for information about page-breaks within 
questions).

\section{Questions}

Questions are entered in the \verb|question| environment. For example,
\begin{verbatim}
\begin{question}
  Show that $1/n\to 0$ as $n\to\infty$.
\end{question}
\end{verbatim}

You can put any \LaTeX\ instructions you like inside the \verb|question|
environment, except those relating to page breaking. In practice, this 
means that you should not attempt to use \verb|\newpage|, 
\verb|\pagebreak| or \verb|\clearpage| inside a \verb|question|, but use
the \verb|\questionbreak| macro described below. In the default layout,
paragraphs are separated by some vertical space but not indented. If you
want to change this, you need to change \verb|\qparskip| and
\verb|\qparindent|; see Section~\ref{sec:lengths}. Do not change
\verb|\parindent| or \verb|\parskip|.

As you would expect from \LaTeX, questions are automatically numbered.
By default, the total number of questions is also presented: numbers
look like ``1 (of 4)''. The \verb|\noquestioncount| command gives plain
numbering. As with all \LaTeX{} cross-referencing, if the number of questions
changes then \LaTeX{} will have to be run twice before the (of n) part
of the question numbers is correct.

If you want separate parts within a question, use the \verb|enumerate|
environment as usual. Parts will be numbered (a), (b), (c), \dots.
Second-level enumerated lists (i.e.\ an \verb|enumerate| environment
inside another \verb|enumerate| environment) have items numbered (i),
(ii), (iii), \dots. If you want your first order lists to be roman and your 
second-order lists to be alphabetic, enter \verb|\romanfirst|; to revert
to alphabetical first, enter \verb|\alphafirst|.
\footnote{Compatibility with existing documents: \texttt{\bs{}romantrue}
  and \texttt{\bs{}romanfalse} are synonyms for \texttt{\bs{}romanfirst}
  and \texttt{\bs{}alphafirst}.}

Questions are never broken across pages without specific instructions. 
If you need to break a question (typically because it is too long to fit 
on a single page even on its own), you can put a \verb|\questionbreak| 
command where you want the break to occur. The break occurs exactly at 
this point, so you should normally put it between paragraphs or between 
a paragraph and a displayed equation: if you put a \verb|\questionbreak| 
command inside a paragraph, the last line on the page will not be justified.

If you want to force a page break between questions, as opposed to
inside a question, use \verb|\pagebreak| or \verb|\newpage| in the usual
way; for example
\begin{verbatim}
\end{question}

\pagebreak

\begin{question}
\end{verbatim}

The reason for the separate commands is that a pagebreak inside a
question prints `\emph{Continued on next page}' and repeat the question
number as `$x$ \emph{Cont.}' on the next page.

\section{Parts}

If the paper contains multiple parts, begin each one with the \verb|\part|
command,\footnote{For compatibility with existing documents,
  \texttt{\bs{}nextpart} is a synonym for \texttt{\bs{}part\{\}}}. e.g. 
\begin{verbatim}
\part{Hilbert Spaces.}
\end{verbatim}
This prints a bold heading on 
the lines of \textbf{Part A. Hilbert Spaces.} Note that \verb|\part| does not 
cause a pagebreak. Use one of the standard pagebreaking commands (e.g. 
\verb|\clearpage|) before the \verb|\part{}| command (but after the 
preceding \verb|\end{question}|) if you want your section to start on a new 
page. 

If you are writing just one part of the paper and want to generate the
correct heading without earlier parts being present, you can use
\verb|\skippart|. For example, to put a heading \textbf{Part B. The
  Lebesgue Integral} at the top of the paper, begin with 
\begin{verbatim}
\skippart
\part{The Lebesgue Integral}
\end{verbatim}
The \verb|\skippart| macro can take an optional argument: to skip two parts, 
use \verb|\skippart[2]| (note square brackets; \verb|\skippart{2}| 
\emph{does not} work).

If you use \verb|\skippart|, you probably also need to use
\verb|\skipquestion| and \verb|\skipsolution|, which step the
question and solution counters. Like \verb|\skippart|, they default to
skipping one question, but take an optional argument to skip more. 

For example, if parts A and B have three questions each and you are just
writing part C, you might begin (imediately after
\verb|\begin{document}|) with
\begin{verbatim}
\skippart[2]
\skipquestion[6]
\end{verbatim}
and between the last question and first solution
\begin{verbatim}
\skipsolution[6]
\end{verbatim}

The \verb|\partinquestion| command makes the part number appear within each
question number, so questions might be numbered A1, A2, A3, B4, B5, etc.
\footnote{The \texttt{\bs{}numberwithinpart} command causes the question 
  number to reset to 1 at the beginning of each part, so the numbering 
  sequence might be A1, A2, A3, B1, B2, B3, etc. This is best avoided: it 
  only makes sense if \texttt{\bs{}partinquestion} is switched on, it's 
  incompatible with \texttt{\bs{}questioncount} and I think it's against the 
  University layout rules.} If you use this, you probably want 
\verb|\noquestioncount| as well, otherwise you'll end up with numbers like 
``A1 (of 5).''

\section{Solutions}

You can put solutions into the same document as the questions, using the 
\verb|solution| environment. You can put anything you like inside a 
\verb|solution| environment, including footnotes and marginal notes. 
Solutions are subject to \LaTeX's normal page-breaking algorithm: there is no 
analogue of \verb|\questionbreak|.

One extra environment is provided for convenience in typing solutions. The 
\texttt{remarks} environment, intended for remarks to the checker or external 
examiner, typesets its contents as a separate paragraph, in italics, with a 
bold heading \textbf{Remarks}. For example,
\begin{verbatim}
\begin{remarks}
  This question lifted verbatim from last year's paper.
\end{remarks}
\end{verbatim}
produces
\noindent\par\textbf{Remarks.} \textit{This question lifted verbatim
  from last year's paper.}

You can suppress the printing of remarks by entering \verb|\noremarks|
and reinstate it with \verb|\showremarks|.

To entirely suppress the printing of solutions (when you print the
final copy for duplication, for example) put the command \verb|\nosolutions| 
in your preamble.

Note that you \emph{cannot} intersperse questions and solutions: you
must have all of the questions in order, followed by all of the
solutions in order.

\section{Marks and Totals}

In both the question and solution environments, you can use
\verb|\marks{n}| to indicate how many marks are assigned to
part of the question. The number is printed flush right, and can be used
either in text or inside displayed mathematics. In displayed mathematics
(including the \AmS\LaTeX{} primary environments such as \texttt{align}, 
\texttt{gather} and \texttt{multline}) the number of marks appears where the 
equation number would normally go, so don't use it in combination with 
equation numbers! For example,
\begin{verbatim}
$$\sum_{n=1}^\infty\frac{1}{n^2}=\frac{\pi^2}{6}\marks{5}$$
\end{verbatim}
might produce (depending on the current style, see below)
$$\sum_{n=1}^\infty\frac{1}{n^2}=\frac{\pi^2}{6}\eqno\ovalbox{5 Marks}$$
If you don't want the number of marks to be right-aligned, use
\verb|\marks*{}| instead; the format is the same, but the
resulting box is set inline. There are some circumstances in which
\verb|\marks{}| returns an error, and \verb|\marks*{}| has to be used%
\footnote{In versions of \texttt{exam.cls} prior to 4/4/2004, 
  \texttt{\bs{}marks\{\}} ``worked'' in these contexts, in the sense that it 
  did not produce an error but failed to align properly. Documents written 
  for these classes might therefore need to be updated to work with the new 
  class.}; in particular, \verb|\marks{}| does not work in \AmS{} subsidiary 
mathematics environments such as \texttt{aligned}, \texttt{gathered} and 
\texttt{split}.\footnote{This is because, within these environments, \TeX{} 
  is in text-style mathematics mode, not display-style.}

The command \verb|\noquestionwordmarks| suppresses the word ``Marks'' in the 
output with question environments (this is the default), and the command 
\verb|\questionwordmarks| restores it; \verb|\solutionwordmarks| (the
default) and \verb|\nosolutionwordmarks| work in the same way for solutions.

The format can be changed with a command of the form 
\verb|\questionmarkstyle{style}| or \verb|\solutionmarkstyle{style}|
in the preamble\footnote{For even finer control, you can use 
  \texttt{\bs{}markstyle}, \texttt{\bs{}wordmarks} and 
  \texttt{\bs{nowordmarks}} which override the current settings; this can be 
  used to give different layouts in different questions, or even different
  parts of the same question, which is almost certainly not a good idea!}: 
Predefied styles are \texttt{box}, \texttt{oval}, \texttt{bracket} and 
\texttt{boldbracket}, which produce results like \fbox{5 marks}, 
\ovalbox{5 Marks} (default for solutions), \mbox{[5 Marks}] and 
\textbf{\mbox{[5 Marks]}} (default for questions) respectively. If you want 
to define a new style \texttt{x}, define a macro \verb|\markx| which takes one
argument and supplies the framing or whatever; e.g. the definition of 
\verb|\markbracket| is simply
\begin{verbatim}
\newcommand{\markbracket}[1]{\mbox{[#1]}}
\end{verbatim}

To typeset marks which do not contribute to the question total (e.g. in
presenting marks for an either/or question, or marking schemes for
alternative solution strategies), use \verb|\suspendtotal| and
\verb|\resumetotal|: any \verb|\marks| command between these display in
the usual way, but do not change the question total. Note that 
\verb|\begin{question}| and \verb|\begin{solution}| implicitly execute
\verb|\resumetotal|.

At the end of each question or solution, the total number of marks can be
printed. For questions, the default is not to print totals; you can 
change this with \verb|\questiontotals| in the preamble. For solutions,
the defaults is to print the total; you can suppress it with
\verb|\nosolutiontotals|. \texttt{\bs{}noquestiontotals} and 
\texttt{\bs{}solutiontotals} work as expected, but are unnecessary
unless you want totals on some, but not all, questions or solutions.

For example, to reproduce the default state where marks appear in the form 
\textbf{[5]} in the questions, without totals, and in the form 
\ovalbox{5 Marks} in the solutions, with totals, you would enter in the 
preamble:
\begin{verbatim}
\questionmarkstyle{boldbracket}
\noquestionwordmarks
\noquestiontotals
\solutionmarkstyle{oval}
\solutionwordmarks
\solutiontotals
\end{verbatim}

\section{Headers and Footers}

The page headers all contain the module number, right-aligned. Headers
of solution pages also contain the word ``SOLUTIONS'', centred.

The page footers all contain the page number, centred. On solution
pages, this is a simple arabic number; but the page number on question pages 
is printed in the form ``Page~x~(of y)''. The final page 
number, of course, is the last question page, not the last page in the 
document. This formatting feature can be switched off with \verb|\nopagecount|
(but don't do this for new papers). The last page is recorded with a \LaTeX{}
\verb|\label| called \verb|lastqpage| so, the first time \LaTeX{} is run,
there will be an ``undefined label'' error associated with this name. As with
all \LaTeX{} cross-referencing, if the number of pages changes then
\LaTeX{} will have to be run twice before the footers are correct.
\footnote{In versions earlier than Summer~2009, all page numbers were
  simple arabic numbers.}

When a question is broken across pages by the \verb|\questionbreak|
command, the footer of the page before the break contains
``continued on next page'' and the header of the page after the break
contains ``continued from previous page''.

The last footer of the last question page contains ``End of examination.''

\section{Adjustable Lengths}
\label{sec:lengths}

There are five lengths you can change. Recall that (approximately) 1ex is 
the height of a lowercase `x' in the current font and 1em is the width of 
a capital `M.'

\begin{enumerate}
\item \verb|\qksip| is the vertical space left between questions (default 4ex).
\item \verb|\qindent| is the distance from the left margin of the paper
  and the left margin of the question (default 5em).
\item \verb|\qlabelsep| is the space between the label and the item in
  secondary list environments (e.g.\ \verb|enumerate|, \verb|itemize|
  and \verb|description|). Default is currently 1em, which is quite
  wide; I might reduce this at some point.
\item \verb|\qparindent| is the extra paragraph indentation used inside
  a question (default 0pt).
\item \verb|\qparskip| is the space between paragraphs inside a question
  (default 1ex).
\end{enumerate}

You can change these using \verb|\setlength| in the preamble of your
document (that is, between the \verb|\documentclass| declaration and the 
\verb|\begin{document}|). For example, the default values are generated by
\begin{verbatim}
\setlength{\qindent}{5em}
\setlength{\qlabelsep}{1em}
\setlength{\qskip}{4ex}
\setlength{\qparindent}{0pt}
\setlength{\qparskip}{1ex}
\end{verbatim}

Note that the usual approach of changing \verb|\parindent| and
\verb|\parskip| will not affect the layout of paragraphs within a
question, but will wreak havoc on the layout of questions within the
paper. Use \verb|\qparindent| and \verb|\qparskip| instead.

\section{Bugs, Problems, Limitations}

This class does some fairly complicated stuff with page headers and footers and
with \TeX\ penalties. Although I think it all works OK, there
might well be bugs lurking which I haven't spotted. Some limitations
have been pointed out above; let me know if they cause any major
problems and I'll try to fix them.

I haven't really attempted to make the class entirely bomb-proof: there
are some things which you can do which will upset it in a big way, such
as making a \verb|\pagestyle| or \verb|\thispagestyle| declaration,
using any sectioning commands other than \verb|\part|, using a third level 
of enumeration, using \verb|\pagebreak|, etc. Be gentle!

\section*{Changes made October 2009}

Added \verb|\suspendtotal| and \verb|\resumtotal|.

\section*{Changes made May 2009}

\begin{enumerate}
\item Changed base class to \texttt{extarticle} to gain easy access to large
  font sizes.
\item Changed page number format to ``Page x (of y)''. Can be switched off
  (against University policy) with \verb|\nopagetotal|.
\item Now imports \texttt{fullpage} package to reduce margin widths.
\end{enumerate}

\section*{Changes made October 2007}

Added default pagebreak after \verb|\maketitle|. Can be switched off
(against University policy) with \verb|\questionfrontpage|.

\section*{Changes made October/November 2006}

\begin{enumerate}
\item Minor bugfix: literal \verb|\markstyle| echoed into text under some 
  circumstances.
\item Minor bugfix to \verb|\marks|: literal \verb|#1| echoed into text under 
  some circumstances.
\end{enumerate}

\section*{Changes made 23/8/2006}

\begin{enumerate}
\item Added missing \verb|\global| on several definitions and conditional
  switches.
\item Added and documented \verb|\marks*|
\end{enumerate}

\section*{Changes made 14/8/2006}

\begin{enumerate}
\item Renamed to \texttt{ymexam.cls} to stop confusion with
  \texttt{exam.cls} in standard distributions.
\item Added automatic addition of R to code number if not present on
  resit papers.
\item Added \verb|\questionmarkstyle|, \verb|\solutionmarkstyle|, the lower
  level \verb|\markstyle|, several conditionals to control mark 
  display and generally reworked mark display code.
\item Added \LaTeX-style aliases for all the plain \TeX\ conditionals.
\item Separated \verb|\nomarks| and \verb|\noremarks|.
\item Added \\\emph{End of examination.}'' as final-page footer.
\item Wrote up various undocumented features.
\end{enumerate}

\section*{Changes made at some point in 2005}

\begin{enumerate}
\item Changed question numbering to ``1 (of 4)'' format, added option to
  number questions within sections.
\item Fixed eTeX incompatibility (\verb|\marks| is an eTeX primitive).
\end{enumerate}

\section*{Changes made 27/4/2004}

Rewrote the page header and footer mechanism using \verb|\mark| to make
the header and footer changes associated with \verb|\questionbreak| more
robust.

\section*{Changes made 4/4/2004}

Rewrote \verb|\marks{}| so it works inside display math.

\section*{Changes made 1/3/2002}

\begin{enumerate}
\item Added \verb|\msctrue|, \verb|\mrestrue| and friends, completely
  rewriting the title generator in the process.
\item Added \verb|\part| macro for giving titles to parts.
\end{enumerate}

\section*{Changes Made 25/1/2000}

\begin{enumerate}
\item Added \verb|\resittrue| and \verb|\resitfalse| to control use of
  `Examinations' v.\ `Resit Examinations' in header.
\item Added \verb|\MMathfalse|, \verb|\BABScfalse|, \verb|\MMathtrue| and
   \verb|\BABSctrue| as synonyms of their uncapitalised forms.
\end{enumerate}

\section*{Changes Made 10/12/98}

Commands \verb|\babscfalse|and \verb|\babsctrue| added to go with
\verb|\mmathfalse| and \verb|\mmathtrue|.

\section*{Changes Made 1/7/97}

Minor enhancements (I hope):
\begin{enumerate}
\item \verb|\nomarks| command suppresses the printing of marks and
  totals, and also of the contents of \verb|remarks| environments. This
  is intended for printing papers with solutions for the library,
  without revealing the marking scheme or any remarks to the external examiner.
\item \verb|\nosolutions| suppresses the contents of the \verb|solution|
  environments. This is intended for printing the final copy for duplication.
\end{enumerate}
Note that these commands are irreversible: you can't switch the marking
scheme back on again having switched it off with \verb|\nomarks|. Note
also that \verb|\marksfalse| still works the way it used to, suppressing
marks and totals but not \verb|remarks| environments, but that
\verb|\nomarks| is now the preferred way to do this. I might withdraw
\verb|\marksfalse| at some point, as this would simplify the code.

\section*{Changes Made 3/3/97}

\begin{enumerate}
\item Page-breaking algorithm completely recoded so \verb|\questionbreak| 
  can be used anywhere you like, even within an item of a secondary or tertiary
  list.
\item \verb|\marks| now works, and also keeps track of totals for each
  question.
\item There is now some space (\verb|\qlabelsep|) between labels and items 
  in labelled lists inside the \verb|solution| environment. This also
  controls such spacing in the \verb|question| environment, which was
  previously left at the \verb|article.cls| default, so you might
  notice a slight difference in questions.
\item The \verb|rubric| environment is now much more flexible. You can
  put almost anything you like inside it, including labelled lists and
  aligned mathematics.
\end{enumerate}

\end{document}
