diff options
author | Norbert Preining <norbert@preining.info> | 2022-10-11 03:01:16 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-10-11 03:01:16 +0000 |
commit | 2713ec666b0e53418a839b97c48e0a9234fe5c98 (patch) | |
tree | 44f44c40d7cf3d6c2c0be9da7bfcf4dad97eb483 /macros/latex/contrib/exam-n/notes-for-authors.tex | |
parent | 9c7942efff8183c8695ec824008847dd068dbfe7 (diff) |
CTAN sync 202210110301
Diffstat (limited to 'macros/latex/contrib/exam-n/notes-for-authors.tex')
-rw-r--r-- | macros/latex/contrib/exam-n/notes-for-authors.tex | 225 |
1 files changed, 107 insertions, 118 deletions
diff --git a/macros/latex/contrib/exam-n/notes-for-authors.tex b/macros/latex/contrib/exam-n/notes-for-authors.tex index de9e3a8ba7..d2798c9ed0 100644 --- a/macros/latex/contrib/exam-n/notes-for-authors.tex +++ b/macros/latex/contrib/exam-n/notes-for-authors.tex @@ -6,33 +6,46 @@ \title{Notes for exam question authors} \author{Norman Gray} -\date{exam-n 1.1.4, 2016 December 19} +\date{Version exam-n-1.4.0, 2022 October 10} \parindent=0pt \parskip=\medskipamount \makeatletter -\def\csarg#1{\texttt\{\textit{#1}\texttt\}% +\def\cs@arg#1{\texttt\{\textit{#1}\texttt\}% \advance\@tempcnta-1 \ifnum\@tempcnta>0 - \let\next\csarg + \let\next\cs@arg \else \let\next\endgroup % begun in \cs \fi \next} +{\catcode`\|=0 \catcode`\\=12 +|gdef|cs@textbackslash#1{|texttt{\#1}}} +% \cs{foo} typeset \foo +% \cs[2]{foo}{bar}{baz} typeset \foo{bar}{baz} \newcommand\cs[2][0]{\begingroup \color{cscolour}% - $\backslash$\texttt{#2}% + \cs@textbackslash{#2}% \@tempcnta=#1 \ifnum\@tempcnta>0 - \let\next\csarg + \let\next\cs@arg \else \let\next\endgroup \fi \next} -\def\env#1{\texttt{\textcolor{cscolour}{#1}}} +\let\origvec\vec +% We'd like to say here +% \newif\ifexamn@uprightpi \examn@uprightpitrue +% but that's not supported for CM fonts +\usepackage{examndefs} + +\makeatother + +\def\env#1{\texttt{\textcolor{cscolour}{\{#1\}}}} \def\opt#1{\texttt{[#1]}} +\def\package#1{\textsf{#1}} \setcounter{secnumdepth}0 @@ -61,7 +74,7 @@ together. It follows from that that you should be hesitant about putting anythi 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 +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. @@ -76,16 +89,54 @@ 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. + +The \cs{partmarks} command will most typically go at the end of a +paragraph, but it may also appear inside an equation (that is, in +\verb|\[...\]|; don't use \verb|$$...$$|), inside one or other +\package{amsmath} display environments, or in a list or other +environment. If it appears inside an environment, the indicator will +appear at the \emph{end} of the environment, independent of where in +the environment the command was typed (which implies that you can't +have more than one inside an environment). + +The starred version is similar, but budges its indicator upwards +a little, and is a heuristic alternative which is useful in some +cases \emph{after} a list or display, or after a numbered equation, if the placement of the +indicator is otherwise inaesthetic +(if the style of the part-marks indicators happens to be such +that the indicator may be mistaken for an equation number, then +it would be wise to use either \cs{partmarks} or \cs{partmarks*} +after the equation, instead). If you use \cs{partmarks*} within a +display, you might be confronted by an error message, talking +about \cs{eqno} in maths mode, which is even more incomprehensible +than most \LaTeX\ messages. + 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. +You may optionally give a question number as an argument to the +\env{question} environment: \cs[1]{begin\{question\}[n]}{markgoal}. +In \opt{compose} mode, this simply sets the question number, but in the other +modes, when the question file is included in a master file, this +checks that the given number~$n$ is what would be assigned +automatically, to help detect missing or out-of-order questions. If +the question identifier is not a number, such as `D1', then you can +provide that identifier here also, but in this case you must also set +\cs{QuestionNumberChecksOff} in the question preamble. + +The \cs{partmarks} command has an optional argument which +indicates the category of the question, thus `bookwork', `unseen', +and so on. If this is present -- for example +\cs[1]{partmarks[bookwork]}{5} -- then the category is included in the +marks indicator. +As you might hope, the \cs{partmarks*} command can take this +optional argument also: \cs[1]{partmarks*[bookwork]}{5}. +This extra text will typically be only one or two words long, but if +the text is much longer than that, it will be turned into a footnote. + 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 @@ -115,15 +166,17 @@ 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. +There is neither a \env{figure*} nor a \env{table*} environment, +because this is a single-column class. +Use the no-option unstarred versions instead. + +\subsection{Hints} -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 +the \package{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 +do so by including the \package{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 @@ -131,7 +184,10 @@ 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. +See the documentation of the \package{pdfpages} package for more information. + +If you use \cs{label} within a \env{question} environment, that label +will, as you might expect, refer to the question number. 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. @@ -139,99 +195,27 @@ 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. +list of exclamations at the end of the document. Note that \cs{shout} +text \emph{appears in the \opt{final} version}: it is to draw +attention to problems (for example \cs[1]{shout}{solution wrong!}) +which must be resolved before the exam is presented to students. 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 +run, but which is otherwise meaningless. +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. +Macro \cs[1]{vec}{v} is redefined to give bold-font vectors +rather than vectors with arrows, which is the (weird) \LaTeX\ default +-- thus $\vec v$ rather than $\origvec v$. +This is intended to work for bold greek as well as roman, +but it does so reliably only for the \opt{mtpro2} and \opt{stix2} +options. 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, @@ -254,6 +238,12 @@ 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. +You should generally type units, and numbers with units, using the +\package{siunitx} package (use the \opt{siunitx} \cs{documentclass} option). + +However this package currently also +supports a basic \verb|\units| command, described here. This macro +is very likely to be removed in a future version of this package. 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 @@ -261,22 +251,21 @@ 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} - +axis with units \verb|$B/\units*T$|, or $B/\units*T$). + +The command \cs{e} sets an upright~`e': +\verb|$\e^{i\pi} + 1 = 0$| produces $\e^{i\pi} + 1 = 0$. +Other shortcuts may be available in customisations of this class.\footnote{% +The package used to support an \cs{au} macro, for astronomical +unit, and \cs{lambdabar} for Compton wavelength, but these have +since been removed. The former is available via \package{siunitx}.} + +Note: $\pi$ is set as an italic pi character, matching the +\LaTeX\ default. Since it's (usually) used as the circular constant, +it should more properly be set upright, and you can get that using the +\opt{uprightpi} option. This option also defines a \verb|\italicpi| +command, for completeness. This option is at present +implemented only for the \opt{mtpro2} and \opt{stix2} options. \subsection{Extra: Creating complete exams} \label{s:complete} @@ -288,7 +277,7 @@ 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}. +The \texttt{exam-n} class currently supports a sample class option \opt{myclass}. This automatically includes a suitable constants sheet in the formatted paper. |