diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex b/Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex new file mode 100644 index 00000000000..de9e3a8ba70 --- /dev/null +++ b/Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex @@ -0,0 +1,304 @@ +\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} |