path: root/macros/latex/contrib/exam-n/notes-for-authors.tex

\documentclass[10pt]{scrartcl}
%\documentclass[11pt]{scrartcl}

\usepackage{url,pdfpages,moreverb,color}
\definecolor{cscolour}{rgb}{0.5,0.1,0.1}

\title{Notes for exam question authors}
\author{Norman Gray}
\date{exam-n 1.1.4, 2016 December 19}

\parindent=0pt
\parskip=\medskipamount

\makeatletter
\def\csarg#1{\texttt\{\textit{#1}\texttt\}%
  \advance\@tempcnta-1
  \ifnum\@tempcnta>0
    \let\next\csarg
  \else
    \let\next\endgroup          % begun in \cs
  \fi
  \next}
\newcommand\cs[2][0]{\begingroup
  \color{cscolour}%
  $\backslash$\texttt{#2}%
  \@tempcnta=#1
  \ifnum\@tempcnta>0
    \let\next\csarg
  \else
    \let\next\endgroup
  \fi
  \next}

\def\env#1{\texttt{\textcolor{cscolour}{#1}}}
\def\opt#1{\texttt{[#1]}}

\setcounter{secnumdepth}0

\begin{document}
\maketitle

The full documentation for the \texttt{exam-n} document class is in
the file \texttt{exam-n.pdf}, but some of this is quite detailed, and
addressed to the exams convener, who has to assemble the overall
exam.  This document is a compact account of how to use the exams
class as a question author.

You can find updated versions of the \texttt{exam-n} document class, and the
complete documentation, at \url{http://purl.org/nxg/dist/exam-n}.

\subsection{Template}
\label{s:template}
\listinginput1{template-question.tex}

Notice first that this is a standalone document -- you can \LaTeX\ it
to produce a formatted exam paper, as long as you include the
\opt{compose} option in the document class line.  This complete
document can later be given to the exams convener, who can
input it unchanged into the master file which pulls the various questions
together.  It follows from that that you should be hesitant about putting anything into
the preamble other than \cs{usepackage} commands, and you should
consult with the exams convener to ensure that such packages go into
the master file, too.  It's probably a safe bet that the `graphicx'
package will be included in the master file.  If you want to include 
a \cs{newcommand}, or anything like that,
it can be placed inside the \env{question} environment.  For
other customisations, negotiate with the exams convener.

The \env{question} environment contains (surprise) a question, broken into
parts (a, b, c, \dots) by \cs{part} commands, and with the distribution of marks within
the question being indicated by \cs[1]{partmarks}n; the class will check that the
marks in \cs{partmarks} do add up to the question goal given as an
argument in \cs[1]{begin\{question\}}{markgoal}.  Within the
question there can be one or more \env{solution} environments, which are
not displayed in the final version (obviously), but which do appear in
draft modes.  You'll most typically have a \cs{partmarks} macro and a
\env{solution} environment for each \cs{part}, but they don't have to
match up, and you can have the entire solution at the end if you prefer.
The \cs[1]{partmarks*}n command is almost the same, but places the
mark indicator in a slightly different position which looks better
when there would otherwise be a gap at the right of the page.  It can
be placed after a list, or inside but at the end of an equation.
Note that \cs{partmarks} ends a paragraph (\cs{partmarks*} doesn't): this is
probably good style, but if you insist on mid-paragraph marks, then a following
\verb|\noindent| will be useful.  It's helpful to use \cs{partmarks} inside a
\env{solution} to indicate the distribution of marks -- this doesn't mess up
the mark-totalling calculation.

One common exam or test question type is a multiple-choice question.
This is indicated by a \cs{begin\{mcq\}} environment, which contains a
textual question followed by a sequence of possible answers indicated by
\cs{item}, including precisely one correct answer, indicated by
\cs{answer} (this is of course formatted identically to the others,
unless the \opt{showsolutions} option is present).  Before you can use
the \env{mcq} environment, you must call
\cs[1]{multiplechoiceanswers}{n} to indicate how many options are
required in each question.
It's OK to have a \env{solution} within an \env{mcq} environment,
perhaps to provide commentary on or explanation of the correct answer.

You can include a \env{questiondata} environment at (typically) the end of
the question: this is intended for extra equations or constants which
are useful for the examinee.

The \env{figure} and \env{table} environments act differently from the
way they usually act in \LaTeX: \emph{`floats' don't float}.  In each
case, the content is forced to be always `here', and in addition is
also tied to the text which follows it, so that a page break will not
occur immediately after a figure or table.  There are \emph{no} figure
or float options permitted in this class's `floating' environments
(that is, option \texttt{[h]} is neither necessary nor permissible).
If you need to tune the page breaking, then you should use
\verb|\goodbreak|, \verb|\vspace| or, in extremis, \verb|\newpage|.
The \cs[1]{caption}{text} command works as usual; the figure and table
numbering sequences continue through the solutions, if they're shown,
but this isn't expected to be a problem.

If you use \cs{label} within a \env{question} environment, that label
will, as you might expect, refer to the question number.

Hints:
Figures can be included with \cs{includegraphics} as usual, as long as
the `graphicx' package has been included at the top of the master
file.  If you want to include complete pages from a PDF (most
typically containing a scanned handwritten model answer), then you can
do so by including the `pdfpages' package at the top of the file, and
then \cs[1]{includepdf[pages=\{-\}]}{filename} inside a \env{solution}
environment.
The \texttt{pages=\{-\}} option means that all pages from the file are
inserted; you may wish to use \texttt{scale=0.8} to shrink the PDF;
the option \verb|pagecommand={\thispagestyle{fancy}}| will cause the other
class apparatus, such as page numbers and headers, to be
superimposed on the included pages.
See the documentation of the `pdfpages' package for more information.

Include marginal notes with \cs[1]{comment}{remark} -- these show up in drafting
modes (\opt{draft} and \opt{compose}), but not in the final version.
The \cs[1]{author}{name} command is just
a type of comment.  If you need to make more noise, then
\cs[1]{shout}{remark} inserts a highlighted \emph{remark} in the flow of text
(so it can be used anywhere) and includes the remark in a prominent
list of exclamations at the end of the document.

At the bottom of each page, you see a faint identification code, such
as `QM/123-456'.  This consists of an exam identifier, extracted from
the exam preamble, plus a code which changes each time \LaTeX\ is
run. This helps you avoid collation accidents, and to distinguish
between slightly different versions of the printed document.

\subsection{Various convenience commands}
\label{s:othercommands}

\makeatletter
% Definitions edited in at build time...
% Abbreviations for degrees.
%    \begin{macrocode}
\newcommand\BSc{B.Sc.{}}
\newcommand\MSci{M.Sci.{}}
\newcommand\MSc{M.Sc.{}}
\newcommand\MA{M.A.{}}
\newcommand\MEng{M.Eng.{}}
\newcommand\BEng{B.Eng.{}}
%    \end{macrocode}
%
% Tweaks to differentials.
%    \begin{macrocode}
\newcommand{\dd}{\mathrm{d}}
\newcommand{\ddd}{\,\mathrm{d}}  % inside an integral, including thinspace

\def\Diffl{\@ifstar\@Difflflat\@Diffl}
\def\Partial{\@ifstar\@Partialflat\@Partial}
\def\@Partial{\@ifnextchar[{\@@Diffl\partial}{\@@Diffl\partial[]}}
\def\@Partialflat{\@ifnextchar[{\@@Difflflat\partial}{\@@Difflflat\partial[]}}
\def\@Diffl{\@ifnextchar[{\@@Diffl\dd}{\@@Diffl\dd[]}}
\def\@Difflflat{\@ifnextchar[{\@@Difflflat\dd}{\@@Difflflat\dd[]}}
\def\@@Diffl#1[#2]#3#4{%
  \def\@tempa{#2}%
  \ifx\@tempa\empty
    \frac{#1#3}{#1#4}%
  \else
    \frac{{#1}^{#2}#3}{#1{#4}^{#2}}%
  \fi}
\def\@@Difflflat#1[#2]#3#4{%
  \def\@tempa{#2}%
  \ifx\@tempa\empty
    #1#3\mskip-0.8mu/\mskip-1.2mu #1#4%
  \else
    {#1}^{#2}#3\mskip-0.8mu /\mskip-1.2mu #1{#4}^{#2}%
  \fi}
%    \end{macrocode}
%
% The exponential sign
%    \begin{macrocode}
\def\e{{\mathrm e}}
%    \end{macrocode}
%
% Physical units in |\rm|.  Unstarred version includes leading
% |\thinspace|.  Starred version doesn't, and is used when referring to
% the unit by itself (eg axis is |$B/\units*T$|), and is not qualifying
% a number.
% FIXME: |\mu| in |\units| can come out wrong in some fonts (mtpro2?)
% -- needs investigation.
%    \begin{macrocode}
\def\units{\begingroup
  \catcode`\.=\active
  \@ifstar{\let\un@tsspace\relax    \un@ts}%
          {\let\un@tsspace\thinspace\un@ts}}
\begingroup
  \catcode`\.=\active
  \gdef\un@ts#1{\let~\thinspace\let.\thinspace
    \ifmmode
      \un@tsspace\mathrm{#1}%
    \else
      \nobreak$\un@tsspace\mathrm{#1}$%
    \fi
    \endgroup}
\endgroup
%    \end{macrocode}
%
% Other miscellaneous symbols:
% The AU is nothing exciting, but may be adjusted in future
%    \begin{macrocode}
\def\au{au}
%    \end{macrocode}
% The symbol for Compton wavelength is a crossed lambda -- the following isn't perfect, but is OK for now.
%    \begin{macrocode}
\def\lambdabar{\setbox\@tempboxa\hbox{$\lambda$}%
  \hbox to 0pt{\hbox to \wd\@tempboxa{\hss$\bar{}$\hss}\hss}\box\@tempboxa}
%    \end{macrocode}
\makeatother

Macro \cs[1]{vec}{v} is redefined to give bold-font vectors, rather than
vectors with arrows, which is the (weird) \LaTeX\ default.  This
should work for bold greek as well as roman.

Macros \cs{dd} and \cs{ddd}: \cs{dd} is a roman d, as used for
differentials; \cs{ddd} is the same with a preceding thinspace,
as used within integrals; for example
\[
 \verb|\int f(x)\ddd x = \int f(x)\,\dd x| = \int f(x)\ddd x
\]

You can typeset derivatives neatly:
\begin{center}
\def\dd{\mathrm{d}}
\begin{tabular}{rl}
\verb|\Diffl{a}{b}|     & $\displaystyle \Diffl ab$ \\[3ex]
\verb|\Diffl[2]{a}{b}|  & $\displaystyle \Diffl[2]ab$\\[3ex]
\verb|\Diffl*{a}{b}|    & $\Diffl* ab$ \\[2ex]
\verb|\Diffl*[2]{a}{b}| & $\Diffl*[2]ab$\\
\end{tabular}
\end{center}
The unstarred versions are for displayed equations, the starred
ones for inline maths.
There is analogous support for partial derivatives with \cs[2]{Partial}ab.

Macros \cs[1]{units}{expr}, \cs[1]{units*}{expr}: These typeset
physical units in an upright shape, with tilde or dot acting as a
separator between units.  Since this is typeset in maths mode, all
other spacing is ignored.  For example, \verb|$v=10\units{m.\mu s^{-1}}$|
gives $v=10\units{m.\mu s^{-1}}$.  The unstarred version includes some
leading space; the starred version can be used when referring to the
unit by itself, where it is not qualifying a number (eg labelling an
axis with units \verb|$B/\units*T$|, or $B/\units*T$).  These macros
might be replaced, in the future, by a recommendation to use the
\texttt{siunitx} package.

For some other useful symbols, see the table below:

\def\arraystretch{1.5}
\begin{tabular}{rcp{8cm}}
\cs{e}&$\e^{i\pi}+1=0$& the exponential is typeset in an upright rather than
an italic shape, as in \verb|$\e^{i\pi} + 1 = 0$|.\\
\cs{au}&10\units\au& astronomical units:
\verb|10\units{\au}|.\\
\cs{lambdabar}&$\lambdabar$& the Compton wavelength, as a lambda with a
bar through it.\\
\end{tabular}


\subsection{Extra: Creating complete exams}
\label{s:complete}
As a question author, you are typically only concerned with one or two
single questions, and that is why this brief guide concentrates
exclusively on the \opt{compose} mode.  But you might be interested to see
how your text appears in the final exam.  A template master file is
below.  For more detail, see the complete documentation in \texttt{exam-n.pdf}.
\goodbreak
\listinginput1{template-master.tex}

The \texttt{exam-n} class currently supports a sample class option \opt{A1}.
This automatically includes a suitable constants sheet in the
formatted paper.

On the following pages, you can see the result of \LaTeX ing the sample file on
p.\pageref{s:template}, and of processing the master file above.
As you can see, the \opt{compose} mode by default shows solutions,
and collects the \cs[1]{shout}{text} remarks to the end.
In the \opt{final} mode (which is the default mode), solutions
disappear, but the shouted-out alerts remain, just to make sure no-one
can miss them.
\includepdf{template-question.pdf}
\includepdf[pages={2,1},angle=90,nup=1x2,column]{template-master.pdf}
\end{document}