From f84e6a7cb7a889c2a8c7297f9d5ca4894eab7687 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 20 Dec 2016 22:54:48 +0000
Subject: exam-n (20dec16)

git-svn-id: svn://tug.org/texlive/trunk@42755 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/latex/exam-n/notes-for-authors.tex         | 304 +++++++++++++++++++++
 1 file changed, 304 insertions(+)
 create mode 100644 Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex

(limited to 'Master/texmf-dist/doc/latex/exam-n/notes-for-authors.tex')

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}
-- 
cgit v1.2.3

