3 % $Id: exercise.dtx,v 1.2 2003/09/05 16:10:41 mdw Exp $
7 % (c) 2003 Mark Wooding
9 %----- Revision history -----------------------------------------------------
11 % $Log: exercise.dtx,v $
12 % Revision 1.2 2003/09/05 16:10:41 mdw
13 % Non-typesetting of answers. Reading in answers from another document.
15 % Revision 1.1 2002/02/03 20:49:03 mdw
16 % Checkin for new build system.
21 % \begin{meta-comment} <general public licence>
23 %% exercise package -- useful macros for setting exercises with answers
24 %% Copyright (c) 2003 Mark Wooding
26 %% This program is free software; you can redistribute it and/or modify
27 %% it under the terms of the GNU General Public License as published by
28 %% the Free Software Foundation; either version 2 of the License, or
29 %% (at your option) any later version.
31 %% This program is distributed in the hope that it will be useful,
32 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
33 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
34 %% GNU General Public License for more details.
36 %% You should have received a copy of the GNU General Public License
37 %% along with this program; if not, write to the Free Software Foundation,
38 %% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
41 % \begin{meta-comment} <Package preambles>
42 %<+package>\NeedsTeXFormat{LaTeX2e}
43 %<+package>\ProvidesPackage{exercise}
44 %<+package> [2003/08/25 1.1 Exercies with answers]
49 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
50 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
51 %% Digits \0\1\2\3\4\5\6\7\8\9
52 %% Exclamation \! Double quote \" Hash (number) \#
53 %% Dollar \$ Percent \% Ampersand \&
54 %% Acute accent \' Left paren \( Right paren \)
55 %% Asterisk \* Plus \+ Comma \,
56 %% Minus \- Point \. Solidus \/
57 %% Colon \: Semicolon \; Less than \<
58 %% Equals \= Greater than \> Question mark \?
59 %% Commercial at \@ Left bracket \[ Backslash \\
60 %% Right bracket \] Circumflex \^ Underscore \_
61 %% Grave accent \` Left brace \{ Vertical bar \|
62 %% Right brace \} Tilde \~}
65 % \begin{meta-comment}
69 \describespackage{exercise}
70 \let\epsilon\varepsilon
71 \errorcontextlines\maxdimen
77 %^^A-------------------------------------------------------------------------
78 % \section{User guide}
80 % The \package{exercise} package allows you to typeset exercises and keep the
81 % answers together with the questions in your source (so they don't get
82 % lost) but typeset them all together at the end of your document.
84 % \subsection{Exercises and answers}
86 % \DescribeEnv{exercise}
87 % Exercises are typset in an \env{exercise} environment. This takes no
88 % arguments. There's a counter for exercises, named |exercise|, and you can
89 % cross-reference exercises in the usual way.
91 % \DescribeMacro\answer
92 % If you want to include an answer for your exercise, just say |\answer|
93 % followed by your answer. The rest of the text up to the end of the
94 % \env{exercise} environment is considered to be the answer, and is stored
95 % away until asked for. This material can contain anything you like. It
96 % \emph{isn't} a moving argument.
99 %\begin{demo}[w]{The \env{exercise} environment}
101 %Show that if $F\colon \{0, 1\}^k \times \{0, 1\}^* \to \{0, 1\}^L$
102 %is a $(t, q + 1, \epsilon)$-secure PRF, then $F$~is also a
103 %$(t, q, \epsilon + 2^{-L})$-secure MAC.
105 %Let~$A$ be an adversary attacking~$F$ as a MAC. Consider the
106 %adversary~$B$ \ldots
111 % \DescribeMacro\skipanswer
112 % The |\skipanswer| command is similar, but just skips over the answer rather
113 % than writing it to the output file. It does nothing at all with counters
114 % -- it's as if there was no answer given at all.
116 % It's OK to use commands like |\answer| and |\skipanswer| in your own
117 % macros as long as they're the \emph{last} token. You can therefore say
120 %\newcommand{\evenanswer}{%
122 % {\isodd{\value{exercise}}}%
127 % to get just the answers to the odd-numbered problems. (If you don't like
128 % \package{ifthen} then you'll need to play with |\expandafter| for a bit.)
130 % \subsection{The answers file}
132 % \DescribeMacro\answrite
133 % Answers are accumulated into a file, to be read later. Additional material
134 % can be added to the file using the |\answrite| macro, which just writes its
135 % argument. Note that this is a \emph{moving} argument, so fragile commands
136 % need |\protect|ing.
138 % \DescribeMacro\exctrcheck
139 % It's common to divide up the answers by section. You can tell the package
140 % to check a collection of counters and perform actions if they've changed
141 % since last time, giving you a chance to write the correct decorations to
142 % the answers file. This is done by saying
143 % \syntax{"\\exctrcheck{"<counter>"}{"<action>"}"}. Then, each |\answer|
144 % command checks to see if \<counter> has changed since last time, and if it
145 % has, it does \<action>, For example,
147 %\exctrcheck{section}
148 % {\answrite{\protect\subsection*{Section \thesection}}}
150 % starts a new (unnumbered) subsection in the answers for each section in the
153 % \subsection{Style tweaks}
155 % The \env{exercise} environment is very simple, and can be easily rewritten
156 % to fit in with your style preferences. If you like exercises to look like
157 % theorems, the easiest thing to do is say something like
159 %\newtheorem{doexercise}[exercise]{\exercisename}
160 %\renewenvironment{exercise}{\exfix\doexercise}{\enddoexercise}
162 % This makes the environment use the existing exercise counter. If you don't
165 %\newtheorem{doexercise}[othercounter]{\exercisename}
166 %\renewenvironment{exercise}{\exfix\doexercise}{\enddoexercise}
167 %\let\theexercise\theothercounter
169 % and all will be well.
171 % \DescribeEnv{doanswer}
172 % Answers are typeset in a \env{doanswer} environment, which is given one
173 % argument: the exercise number (as set by |\theexercise|). This can be
174 % modified to do whatever you like.
176 % \DescribeMacro\exfix
177 % The |\exfix| is a convenient hook which is run both in the \env{exercise}
178 % and \env{doanswer} environments by default. The current implementation
179 % just skips a level of \env{enumerate} depth, which usually means that
180 % \env{enumerate} lists will go (a), (b), (c), \ldots\ rather than 1, 2, 3,
183 % \subsection{Lists in paragraphs}
185 % \DescribeEnv{parenum}
186 % Answers to subparts tend to be compressed together into a single
187 % paragraph. It's nice, when you do this, not to have to worry about losing
188 % your numbering of subparts. The \env{parenum} environment provides an
189 % enumerated list in a paragraph. So, for example, you can say something
191 %\begin{demo}[w]{Example of \env{parenum}}
193 %A PRG $g\colon \{0, 1\}^k \to \{0, 1\}^L$ is \emph{trivial} if
196 %\item Show that trivial PRGs exist.
197 %\item Show that a non-trivial $(t, \epsilon)$-secure PRG is a
198 % $(t, \epsilon + 2^{k-L})$-secure one-way function.
202 %\item The identity function is a trivial PRG: the real and random
203 % games are identically distributed.
204 %\item Let~$A$ be an adversary attempting to invert~$g$: then we
205 % can construct a distinguisher~$B$ as follows \ldots
210 % \subsection{And finally}
212 % \DescribeMacro\answers
213 % In order to extract your answers, say |\answers|.
214 %\begin{demo}[w]{The \texttt{\string\answers} command}
219 % The |\answers| command has an optional argument, which is the file to read
220 % in. This allows you to make `answer booklet' documents, by saying
225 % If you don't give a file extension, then |.ans| is appended automatically.
230 %^^A-------------------------------------------------------------------------
231 % \section{Implementation}
237 % \subsection{Initialization}
239 % The \textsf{within} option is handled by the \package{mdwkey} package.
242 \RequirePackage{mdwkey}
245 % \begin{macro}{\ex@within}
247 % When the \textsf{within} option is seen, we set a command |\ex@within| to
248 % the correct code, to be executed later when we've made our minds up.
252 \mkdef{exercise:opts}{within}{%
254 \@addtoreset{exercise}{#1}%
255 \toks@\expandafter{\csname the#1\expandafter\endcsname%
256 \expandafter.\theexercise}%
257 \edef\theexercise{\the\toks@}%
263 % \begin{macro}{\ex@opts}
265 % The |\ex@opts| macro just runs the \package{mdwkey} kit to parse an option
269 \def\ex@opts{\mkparse{exercise:opts}}
273 % Now do the options thing.
276 \DeclareOption*{\expandafter\ex@opts\expandafter{\CurrentOption}}
280 % Set up the |exercise| counter, and number it within some other sort of
281 % counter as appropriate.
284 \newcounter{exercise}\ex@within
287 % We also need the \package{sverb} package in order to do the delaying of the
291 \RequirePackage{sverb}
294 % \subsection{Checking for counter changes}
296 % \begin{macro}{\ex@ctrcheck}
298 % The counter checking state is stored here. It's initially empty.
305 % \begin{macro}{\exctrcheck}
307 % Adding a counter to the check list is relatively easy. We expand the
308 % current list into a token register, add the new material to the end, and
309 % put the list back in our macro using |\edef|. The `last' value of the
310 % counter is set to |\relax|, to force out the change on the next |\answer|.
313 \def\exctrcheck#1#2{%
314 \toks@\expandafter{\ex@ctrcheck\ex@ctrdo{#1}{#2}}%
315 \edef\ex@ctrcheck{\the\toks@}%
316 \global\expandafter\let\csname ex@ctrlast@#1\endcsname\relax%
321 % \begin{macro}{\ex@ctrdo}
323 % Here we actually check to see whether a counter has changed and execute the
328 \edef\@tempa{\csname the#1\endcsname}%
329 \expandafter\ifx\csname ex@ctrlast@#1\endcsname\@tempa\else%
331 \global\expandafter\let\csname ex@ctrlast@#1\endcsname\@tempa%
337 % \subsection{The \env{exercise} environment}
339 % \begin{macro}{\exercisename}
341 % We store the string to print for each exercise in |\exercisename| as a
342 % half-hearted attempt at internationalization.
345 \providecommand\exercisename{Exercise}
349 % \begin{macro}{\exfix}
351 % This is a dumping ground for style fixing common to both exercises and
352 % answers. Here, we bump on the \env{enum} depth counter, so that it skips
353 % labelling with digits.
356 \def\exfix{\advance\@enumdepth\@ne}
360 % \begin{environment}{exercise}
362 % This is pretty simple. The environment is list-based, with the number set
363 % in bold in a label.
367 \refstepcounter{exercise}%
369 \trivlist\advance\itemindent\labelsep%
370 \item[\textbf{\exercisename\ \theexercise}]%
372 \let\endexercise\endtrivlist
376 % \subsection{Answers}
378 % We need a file in which to store our answers.
384 % \begin{macro}{\ex@ansfilename}
386 % In case anyone has a better idea for a filename than our default, we
390 \def\ex@ansfilename{\jobname.ans}
394 % We open the file at the end of the preamble, to give the user a chance to
395 % say |\nofiles|, or change |\ex@ansfilename|.
400 \immediate\openout\ex@ansfile=\ex@ansfilename\relax%
406 % \begin{macro}{\answrite}
408 % This writes stuff to the answers file. We make sure that it's
409 % appropriately protected, so that you can insert section headings and so on.
415 \let\protect\@unexpandable@protect%
416 \immediate\write\ex@ansfile{#1}%
423 % \begin{macro}{\answer}
425 % The |\answer| macro needs to read until the end of the enclosing
426 % \env{exercise} environment (or whatever).
429 \def\answer{\sv@readenv\ex@answer}
432 % Now for the main guts.
440 % First of all, check to see whether any counters have changed.
446 % Start a \env{doanswer} environment in the file.
449 \answrite{\noexpand\begin{doanswer}{\theexercise}}%
452 % Set catcodes to be strange, and read lines one-at-a-time, writing them to
453 % the file. When finished, continue at |\ex@endanswer|.
456 \let\do\@makeother\dospecials%
458 \sv@read{#1}\answrite{\ex@endanswer#2}%
462 % When that's done, we wind up here.
467 \answrite{\noexpand\end{doanswer}}%
473 % \begin{macro}{\skipanswer}
475 % This is much simpler.
478 \let\skipanswer\ignore
482 % \begin{macro}{\answers}
484 % The |\answers| macro closes the file, makes sure that future
485 % \env{exercise}s with answers cause an error, and reads in the file.
489 \@ifnextchar[{\answers@i\input}{\answers@i\@input[\ex@ansfilename]}%
491 \def\answers@i#1[#2]{%
492 \immediate\closeout\ex@ansfile%
493 \global\let\answrite\exerr@toolate%
494 \ex@withext{#1}{#2}{ans}%
496 \def\q@delim{\q@delim}
497 \def\ex@withext#1#2#3{%
498 \edef\next@##1{\noexpand\ex@ext@i{##1}{#2}{#3}#2.\noexpand\q@delim}%
501 \def\ex@ext@i#1#2#3#4.#5\q@delim{%
502 \ifx\q@delim#5\q@delim\def\next@{#1{#2.#3}}%
503 \else\def\next@{#1{#2}}\fi%
509 % \begin{environment}{doanswer}
511 % A very simple environment. We set the exercise number in bold and then
512 % just write the text.
517 \trivlist\advance\itemindent\labelsep%
520 \let\enddoanswer\endtrivlist
524 % \subsection{Lists inside paragraphs}
526 % \begin{environment}{parlist}
528 % The \env{parlist} environment is a trimmed-down version of a normal list.
529 % We todge the |\item| command, make |\list| and |\trivlist| make errors, and
530 % do various normal list things.
534 \let\@trivlist\exerr@parlist%
536 \let\makelabel\relax%
545 % \begin{macro}{\pl@item}
547 % This is the implementation of |\item| within a \env{parlist}. The main
548 % interesting point is the game with boxes, which has the objective of
549 % extracting the text of the item, together with any style changes set by
550 % |\makelabel|, but without any stupid bits of glue, or |\llap| or anything
554 \def\pl@item{\@ifnextchar[\pl@item@i{\pl@item@i[\@itemlabel]}}
556 \if@nmbrlist\refstepcounter{\@listctr}\fi%
557 \setbox\z@\hbox{\makelabel{\global\setbox\@ne\hbox{#1}}}%
558 \ifvmode\leavevmode\else\unskip\hskip1em\fi\box\@ne~\ignorespaces%
563 % \begin{macro}{\useparlist}
565 % We just set the \env{list} environment to use \env{parlist}.
568 \def\useparlist{\let\list\parlist\let\endlist\relax}
572 % \begin{environment}{parenum}
574 % Very simple, this. Note that we don't run |\endenumerate|, because that's
575 % |\let| to |\endlist|.
578 \def\parenum{\useparlist\enumerate}
579 \let\endparenum\endparlist
583 % \subsection{Errors}
587 \PackageError{exercise}{Too late now for \string\answrite}{%
588 You can't write answers after you've read the file in. I've^^J%
589 ignored the text you attempted to write. This is why answers^^J%
590 go at the end of a book!%
594 \PackageError{exercise}{You can't nest a `list' inside a `parlist'.}{%
595 I've found a `list' or `trivlist' environment nested inside^^J%
596 a `parlist'. This isn't allowed. You're probably doomed now.%
604 % \hfill Mark Wooding, \today