\documentclass[12pt,a4paper]{amsart}

\begin{document}

\title{\texttt{exam}, a \LaTeXe\ class for examination papers}
\date{March 2002}
\author{Simon Eveson}
\maketitle

\section*{Introduction}

\verb|exam.cls| is a \LaTeXe\ class file for producing examination
papers. It provides an automatically-numbered \verb|question|
environment, which does not allow questions to be broken across pages
without specific instructions from the user, and an optional
\verb|solution| environment if you want to type solutions into the same
file. The front page, with the examination's title, module number,
duration and rubric is automatically set in the approved format
and page footers like \emph{turn over} and \emph{continued on next page}
are automatically generated. If you wish, you can add a marking scheme
to the solutions and the system will total the marks for each question.

\section*{Installation}

The current version of \verb|exam.cls| and some supporting files are
available from
\begin{verbatim}
http://www-users.york.ac.uk~spe1/examclass/
\end{verbatim}
You should put the class file \texttt{examclass.cls} either in the same
directory (folder) as the document you are working on, or in a global
inputs directory. If you use the networked version of \TeX, you can use
\verb|~/tex/inputs| under Unix or \verb|h:\texmf\tex\latex\| under
Windows (note that there is another file called \verb|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 file \texttt{examsamp.tex} is a complete examination paper, including
solutions, produced in \verb|exam| class. Take a look at it to see the 
way the system works, or use its skeleton as the basis for your own file.

\section*{Class Declaration}

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

\begin{verbatim}
\documentclass{exam}
\end{verbatim}

By default, this class uses 12pt type on A4 paper and produces output
suitable for double-sided duplication. There should be no need to change 
this, but you can if required: any option understood by the standard 
\texttt{article} class is also understood by \verb|exam|.

\section*{Packages}

The \verb|exam| class automatically loads the AMS packages
\verb|amsmath|, \verb|amsfonts| and the extended vaerbatim 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 \verb|exam| class.
After the \verb|\begin{document}| command, you must specify the
paper's title, number, duration and year and 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}
\codenumber{12345}
\year{1996}
\title{Functional Analysis Sample Paper}
\duration{$1\half$ hours}

\begin{rubric}
  Answer not more than \underline{three} questions. \\
  Calculators may be used but should be unnecessary.
\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 III or IV third year courses, fourth year courses
and masters courses), use some combination of the macros \verb|\babscfalse|,
\verb|\mmathfalse|, \verb|\msctrue| and \verb|\mrestrue|. 
The synonyms \verb|\MMathfalse|, \verb|\BABScfalse|, \verb|MSctrue| and 
\verb|MRestrue| are available for those who like Capital Letters. The 
opposite switches are also available, e.g. \verb|babsctrue|, but you're 
unlikely to want them.

If the paper is a resit paper, put \verb|\resittrue| in the topmatter.
This insert the word `Resit' before `Examinations' in the heading. You
should also prefix the module number with \texttt{R}, e.g.\ \texttt{R12345}.

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.

\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. Unlike earlier versions
of \verb|exam.cls|, footnotes and marginal notes will now work within
questions. Whether one would ever want to use such things in a question
is, of course, another matter.

As you would expect from \LaTeX, questions are automatically numbered.
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. (see `Tweaking Things' below if you want your first
order lists to be roman and your second-order lists to be alphabetic). I
haven't specified the numbering of any higher-level enumerations: if you
really need one, let me know and I can add it.

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 in 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 `$x$ \emph{Cont.}' on the next page, where $x$ is the page 
number (earlier versions also did a good deal of housekeeping to do with
the \emph{continued on next page} footers and \emph{continued from previous 
  page} headers, but this is now fully handled by the page style).

\section*{Parts}

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

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.} at the
top of the paper, begin with \verb|\skippart\nextpart|. 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 possibly \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, if you are typing solutions (see next section),
\begin{verbatim}
\skipsolution[6]
\end{verbatim}
between the last question and first solution.

\section*{Solutions}

You can (if you want to) 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 \verb|\questionbreak| or similar command.

One extra environment and one extra command are provided for convenience
in typing solutions. The \verb|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.}

The \verb|\marks{n}| command prints `n Marks.' in a framed,
right-aligned box. For example, \verb|\marks{5}| produces
\hspace*{\fill}\fbox{5 Marks.}\linebreak
If there is not enough room on the current line, a new line will be
created (blank except for the number of marks). The \verb|\marks{}| command can 
be used inside displayed mathematics, in which case it puts the number
of marks 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}
produces
$$\sum_{n=1}^\infty\frac{1}{n^2}=\frac{\pi^2}{6}\eqno\framebox{5 Marks}$$

If you use any \verb|\marks{}| commands in a question or solution, the 
total is printed at the end of the solution.

To supress the printing of marks and remarks, put the command \verb|\nomarks|
in your preamble. This might be useful if you want to distribute solutions 
to last year's paper, but not distribute the marking scheme or any
comments to the external examiner.

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. I might be able to allow them to be interspersed, if
anyone really desperately wants it, but it won't be easy.

If you don't want to type solutions, there is no need to: the
\verb|solution| environments are entirely optional.

\section*{Tweaking things}
\label{sec:tweak}

There are a few tweakable parameters in the system. 

By default, the \verb|enumerate| environment numbers its items (a), (b),
(c), \dots and second-level enumerations are numbered  (i), (ii), (iii),
\dots. To swap these, so first-level enumerations are numbered in roman
and second-level in alphabetic, put the command \verb|\romantrue| in the
document preamble.

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 3em). It must be at least wide
  enough to contain the question number and the word \emph{cont.}
\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}

Note that \verb|\footheight| is no longer available (did anyone ever use it?). 
Use the standard \LaTeXe\ length \verb|\footskip| instead (default length 6ex 
in this class).

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}{4em}
\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*{Security}

There are obvious security implications in keeping examination-related
material on networked file systems. The best solution is simply not to
do this: use your own local hard disk, or a floppy disk.

If you really must keep material like this on the network, the
\emph{minimum} level of security is to make the files and the directory
containing them accessible only to you. To do this, at the Unix shell
prompt or DOS prompt type 
\begin{verbatim}
chmod go-rx <name>
\end{verbatim}
where \verb|<name>| is the name of the file or directory
to protect. You can use wildcards: e.g.\ \verb|*| under Unix or
\verb|*.*| under DOS to mean `all files in the current directory.' It is
especially important to protect the directory containing the files,
since the protection on the \verb|.dvi| and \verb|.ps| files produced by
\TeX\ and \verb|dvips| is somewhat hard to predict.

It is also possible to encrypt files, which is probably the best
security of all. Unfortunately this is not really practical when it
comes to \TeX\ since one would need to encrypt the \TeX\ source, the
\verb|.dvi| file and the PostScript file. See the manual entry for
\verb|crypt| on the Unix systems, or the MicroEMACS documentation for
its \verb|CRYPT| mode.

\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 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}
