summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/exercise/exercise.doc
blob: 0c2d057893faa2429b0ee123d2d19c741ea9ebc4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
\def\fileversion{v1.0d}
\def\filedate{92/07/02}
\def\docdate{92/07/02}

%% \CheckSum{139}
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
%\iffalse   % this is a METACOMMENT !
%% Style-option `exercise' to use with LaTeX v2.09
%% Copyright (C) 1991 by Anselm Lingnau, all rights reserved.
%
% Copying of this file is authorized only if either
% (1) you make absolutely no changes to your copy, including name, or
% (2) if you do make changes, you name it something other than
%     exercise.doc.
% This restriction helps ensure that all styles developed here
% remain identical.
%
% Error reports please to: Anselm Lingnau
%                          Buchenweg 1
%                          D-6239 Eppstein
%                          Federal Republic of Germany
%                  Email:  <lingnau@math.uni-frankfurt.de>
%
%
%\fi
%
% \changes{v1.0d}{92/07/02}{New Internet address.}
% \changes{v1.0c}{91/10/08}{Write version number to transcript file only.}
% \changes{v1.0b}{91/10/08}{Polished the documentation.}
%
% \DoNotIndex{\@addtoreset,\@ifundefined,\@makeother,\@spaces,\@tempa}
% \DoNotIndex{\@warning,\^,\active,\arabic,\begin,\bf,\catcode}
% \DoNotIndex{\closeout,\csname,\def,\do,\docdate,\dospecials}
% \DoNotIndex{\edef,\else,\end,\endcsname,\endinput,\endtrivlist}
% \DoNotIndex{\errhelp,\errmessage,\expandafter,\fi,\filedate}
% \DoNotIndex{\fileversion,\ifx,\immediate,\input,\item,\jobname,\let}
% \DoNotIndex{\medbreak,\newcounter,\newif,\newenvironment,\newwrite}
% \DoNotIndex{\openout,\par,\refstepcounter,\relax,\renewcommand,\section}
% \DoNotIndex{\space,\string,\subsection,\the,\trivlist,\typeout,\wlog}
% \DoNotIndex{\write}
%
% \title{A \LaTeX\ Environment for Typesetting Exercises\thanks{%
%        This file has version number \fileversion{} dated \filedate.
%        The documentation was last revised on \docdate.
%       }}
% \def\rtitlex{A \LaTeX\ Environment for Typesetting Exercises}
% \thispagestyle{plain}
%
% \author{Anselm Lingnau}
% \address{Buchenweg 1\\
%         D-6239 Eppstein\\
%         Federal Republic of Germany}
% \netaddress[\network{Internet}]{lingnau@informatik.uni-frankfurt.de}
%
% \date{October 8, 1991}
%
% \maketitle
%
% \begin{abstract}
%   This style option implements a \LaTeX{} environment for
%   typesetting exercises.
%   The {\tt exercise} environment is modelled along the lines of
%   the exercise macros in {\sl The \TeX book},
%   i.\ e.\ the answer can be given right after the exercise.
%   Answers are collected in a file that can be included afterwards.
%   The macros presented here are based on Rainer Sch\"opf's
%   reimplementation of the {\tt verbatim} environment.
% \end{abstract}
%
% \section{Introduction}
%
% \TeX\ users everywhere are looking up to Donald Knuth's {\sl \TeX book\/}
% as a source of inspiration and good ideas.
% When I began writing a major software manual,
% I thought that it would be nice to have little exercises
% that would let the readers practise using the input language and so on.
% On pages 422--423,
% {\sl The \TeX book\/} lists some macros for exercises.
% Their most interesting feature is that the answer can be given
% immediately after the exercise itself.
% Thus exercises and answers always conveniently stay together,
% making it easy to insert, delete or move exercises without having to
% worry about numbering.
% The following example was lifted from {\sl The \TeX book\/}:
%\begin{verbatim}
%   \exercise After you have mastered the material in this book,
%   what will you be: A \TeX pert, or a \TeX nician?
%   \answer A \TeX nician (underpaid); sometimes also called
%   a \TeX acker.
%\end{verbatim}
% Obviously, these macros are geared towards \PlainTeX,
% and while they can be hacked to seemingly work with \LaTeX\ as well,
% I have experienced some nasty incompatibilities
% that didn't look straightforward to fix.
%
% Luckily, I came across Rainer Sch\"opf's reimplementation
% of the {\tt verbatim} environment \& Co.,
% and using this it was very easy to reimplement the exercise macros
% and make them fit within \LaTeX.
% The remainder of this document discusses the use and implementation
% of these macros.
%
% {\bf Warning:} This style option assumes
% that you have Rainer Sch\"opf's {\tt verbatim} macros.
% It won't work otherwise.
% You can get these macros from major software servers everywhere
% or from your local \TeX\ Users Group, e.\ g., DANTE e.\ V. in Germany. 
%
% \section{The User Interface}
%
% To use {\tt exercise.sty}, the style option {\tt exercise}
% must be included among the document style options.
% Be sure that you say {\tt verbatim} somewhere in the
% \verb|\documentstyle| command
% in order to load Rainer Sch\"opf's {\tt verbatim} stuff.
% Thus,
%\begin{verbatim}
%   \documentstyle[foo,verbatim,bar,exercise,baz]{article}
%\end{verbatim}
%
% \DescribeEnv{exercise}
% The {\tt exercise} environment is the most important part
% of our new style option.
% It will format its contents as an exercise,
% namely preceding it with an exercise number and, optionally,
% a ``title''. (Refer to the Implementation to find out how to change
% the formatting of exercise ``heads''.)
% The answer to the exercise is given right after the exercise itself,
% following the |\answer| command.
% Generally, an exercise looks like this:\\[2pt]
%   \hspace*{\MacroIndent}|\begin{exercise}|\\
%   \hspace*{\MacroIndent}\meta{The exercise itself}\\
%   \hspace*{\MacroIndent}|\answer|\\
%   \hspace*{\MacroIndent}\meta{The answer to this exercise}\\
%   \hspace*{\MacroIndent}|\end{exercise}|\\[2pt]
% The \meta{answer} is copied out to the file {\tt answers.tex}.
% This file can be read back in later with the |\listanswers| command.
%
% In {\sl The \TeX book}, the answer is finished by a blank line.
% With the {\tt exercise} environment, however, the answer includes
% everything up to the |\end{exercise}| command.
% Note that the |\answer| command may not occur inside another
% environment opened within the {\tt exercise}, that is, not at the same
% level of nesting as the |\begin{exercise}| \dots |\end{exercise}|
% commands. The implementation tries to detect this error and issues
% an appropriate diagnostic.
%
% Sometimes you may want to state an exercise without any answer
% (for example, a research problem).
% You can use the {\tt exercise} environment to typeset an
% answer-less exercise as well,
% thereby keeping the style and numbering of exercises uniform.
%
% \DescribeMacro{\listanswers}
% At some stage you will want to list the collected answers, presumably
% in an appendix of some sort. The |\listanswers| command will take
% care of that.
% You should say something along the lines of
%\begin{verbatim}
%   \appendix
%   \chapter{Answers to the Exercises}
%   Don't peek.
%   \listanswers
%\end{verbatim}
%
% \StopEventually{\makesignature}
%
% \section{The Implementation}
%
% As usual, the file identifies itself. Following Nico Poppelier's
% suggestion to Frank Mittelbach, the rather verbose headers are only written
% to the transcript file.
% \changes{v1.0c}{91/10/08}{Write version number to transcript file only.}
% We read this file only once.
%    \begin{macrocode}
\@ifundefined{exercise}{}{\endinput}
\wlog{Style-Option: `exercise'
   \fileversion \space <\filedate>  (AL)}
\wlog{English Documentation
   \@spaces \@spaces \space <\docdate>  (AL)}
%    \end{macrocode}
% We need a new counter for counting the exercises.
% Tricky manipulations are necessary because exercises are normally
% numbered within some sectional unit, e.\ g., the chapter.
% This, of course, is for the user to decide---we can't simply
% stick in a |\newcounter{exercise}[chapter]| because there's
% no way we'd be able to undo this, should our guess prove
% wrong\footnote{Oh well, I suppose we could always keep track
% of which sectional unit the exercises are numbered within.
% Then we could remove the entry from the corresponding list.
% What a mess.}.
% So, by default, the exercises are numbered consecutively throughout
% the whole document.
% (This is what you want when you're typing up homework assignments.)
%    \begin{macrocode}
\newcounter{exercise}
%    \end{macrocode}
%
% \begin{macro}{\numberexercises}
% The |\numberexercises| command lets the user specify
% where the exercises are actually supposed to be numbered.
% I. e., |\numberexercises{chapter}| will reset the {\tt exercise}
% counter to zero whenever a new chapter begins.
% The actual exercise number is appended to the number of
% whatever we are numbering the exercises within.
% |\numberexercises| can occur only once in a document,
% and it must appear before the first exercise.
% Otherwise we issue a warning message.
%    \begin{macrocode}
\newif\if@exnofixed
\def\numberexercises#1{%
  \if@exnofixed\@warning{Exercise numbering already fixed}
  \else\@addtoreset{exercise}{#1}%
     \renewcommand{\theexercise}{\csname
        the#1\endcsname--\arabic{exercise}}\fi
  \@exnofixedtrue}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\exercisehead}
% One can imagine quite a lot of different ways to start an exercise:
% compare ``{$\bullet$\,\small\bf EXERCISE \normalsize\bf 2--3}'' to
% ``{\sl Exercise 2--3.}'' or even ``\fbox{2--3}''.
% The |\exercisehead| command lets the user specify
% how the exercise headings are to be formatted---its
% first argument is inserted right in front of the exercise number,
% while the second argument is inserted right afterwards.
% The default is to print just the exercise number in boldface;
% the examples above would be realized by the commands
%\begin{verbatim}
%   \exercisehead{$\bullet$\,\small\bf EXERCISE \normalsize\bf}{}
%   \exercisehead{\sl Exercise }{.}
%   \exercisehead{\fbox}{}
%\end{verbatim}
% respectively.
% Note the (seemingly extraneous) braces around |\theexercise|
% in the definition of |\exercisehead|.
% They make the last example possible.
%    \begin{macrocode}
\def\exercisehead#1#2{\def\exercise@head{#1{\theexercise}#2}}
\exercisehead{\bf}{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\exenvname}
% We'll need the name of the {\tt exercise} environment
% later on, to check whether the |\answer| occurs at `top level'
% inside the environment.
%    \begin{macrocode}
\def\exenvname{exercise}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\exercise}
% Now we define the {\tt exercise} environment.
% The |\@exnofixedtrue| inhibits use of the
% |\numberexercises| command after the first exercise.
% The |\refstepcounter| command lets you |\label|
% exercises for cross-reference.
%    \begin{macrocode}
\def\exercise{\medbreak\@exnofixedtrue
     \refstepcounter{exercise}\trivlist\item[]{\exercise@head}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\endexercise}
% The |\endexercise| command finishes up an exercise.
%    \begin{macrocode}
\def\endexercise{\endtrivlist}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\answer}
% Now for the tougher bits.
% We check whether the name of the current environment equals
% ``{\tt exercise}''.
% If not, then some other environment has been opened but not closed
% before the |\answer|.
% That's bad, because the verbatim scanning mechanism will look for
% the wrong |\end|.
% It certainly rates an error message,
% which is output by |\@answererr|.
% Otherwise, all is well and we delegate the work to |\@answer|.
% Note that we call |\@answer| in a non-straightforward fashion:
% if we had
%\begin{verbatim}
%   \ifx\@currenvir\exenvname\@answer\else\@answererr\fi
%\end{verbatim}
% then |\@answer| would copy the |\else| and following
% tokens to the answer file.
% We have to make sure that the answer text is immediately next
% when |\@answer| is called.
%    \begin{macrocode}
\def\answer{%
  \ifx\@currenvir\exenvname\let\next\@answer
    \else\let\next\@answererr\fi\next}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@answererr}
% This macro issues an error message when the current environment name
% is found not to match {\tt exercise}.
% It tries to correct the error by finishing the current environment
% and repeating the test.
%    \begin{macrocode}
\def\@answererr{\errhelp{There may be no unmatched `\begin' between
     the^^J`\begin{exercise}' and `\answer'.}%
    \errmessage{LaTeX error: Wrong \string\answer\space (current
      environment is `\@currenvir')}%
    \edef\@tempa{{\@currenvir}} \expandafter\end\@tempa \answer}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@answer}
% The |\@answer| macro diverts subsequent lines to the answer file,
% up to the line that finishes the {\tt exercise} environment,
% namely |\end{exercise}|.
% Rainer Sch\"opf's {\tt verbatim} macros do the hard work;
% this macro is essentially adapted from his {\tt verbatimwrite}
% environment.
%
% Before we start copying the answer,
% we write a line containing the current exercise number.
% This line is of the form\\[2pt]
%   \hspace*{\MacroIndent}|\ansno{|\meta{exercise number}|}|\\[2pt]
% and |\ansno| will be suitably defined later on.
% |\ans| is the file descriptor for the answer file.
%    \begin{macrocode}
\def\@answer{%
   \immediate\write\ans{\string\ansno{\theexercise}}
%    \end{macrocode}
% Now we get ready for copying the answer.
% All special characters are disabled,
% while the end of line is made active.
% According to Rainer Sch\"opf's paper the |\verbatim@processline|
% macro is called from within the {\tt verbatim} environment when
% a whole line of stuff has been accumulated.
% We will define this macro such that this line is then output
% to the answer file.
% |\verbatim@start| launches the copying process.
%    \begin{macrocode}
  \let\do\@makeother\dospecials \catcode`\^^M\active
  \let\verbatim@processline=\answer@processline
  \verbatim@start}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\answer@processline}
% The {\tt verbatim} macros gather a complete line of input into the
% token variable |\verbatim@line|.
% Here we output the contents of this variable to the answer file.
% This macro is called whenever a line has been completely read.
%    \begin{macrocode}
\def\answer@processline{\immediate\write\ans{\the\verbatim@line}}
%    \end{macrocode}
% \end{macro}
%
% \DescribeEnv{exercises}
% We define another environment that will introduce a special section
% for the exercises. The name of the environment is unfortunate,
% but I couldn't think of anything else. Maybe {\tt homework} or
% {\tt assignment} might have been more sensible. (Any ideas, anyone?)
% Anyhow, you can say\\[2pt]
%   \hspace*{\MacroIndent}|\begin{exercises}|\\
%   \hspace*{\MacroIndent}|Make sure you attempt all of them.|\\
%   \hspace*{\MacroIndent}\quad|\begin{exercise}|\\
%   \hspace*{\MacroIndent}\quad\meta{exercise$_1$}\\
%   \hspace*{\MacroIndent}\quad|\end{exercise}|\\
%   \hspace*{\MacroIndent}\dots\\
%   \hspace*{\MacroIndent}\quad|\begin{exercise}|\\
%   \hspace*{\MacroIndent}\quad\meta{exercise$_n$}\\
%   \hspace*{\MacroIndent}\quad|\end{exercise}|\\
%   \hspace*{\MacroIndent}|\end{exercises}|\\[2pt]
% With {\tt article}, the exercises will be placed in a subsection,
% whereas, with {\tt report} and {\tt book}, the exercises will
% be put into a section.
% \DescribeMacro{\exercisetitle}
% The |\exercisetitle| can be redefined according to
% the desired language.
%    \begin{macrocode}
\def\exercisetitle{Exercises}
\@ifundefined{chapter}{\let\exsection\subsection}%
    {\let\exsection\section}
\newenvironment{exercises}{\exsection*{\exercisetitle}}{}
%    \end{macrocode}
%
% Now we open the file for the answers.
% Its name is the current job name plus {\tt.ans},
% i.\ e., if the document is {\tt paper.tex},
% the answer file is {\tt paper.ans}. In the original, the
% file name is always {\tt answers.tex}; using the job name makes
% it possible to put the answers into a separate document without
% causing undue confusion, since every document gets its own
% answer file.
%    \begin{macrocode}
\newwrite\ans
\immediate\openout\ans=\jobname.ans
\typeout{Writing answers to \jobname.ans.}
%    \end{macrocode}
%
% \begin{macro}{\listanswers}
% The |\listanswers| command will close the answer file
% and replace itself by its contents.
%    \begin{macrocode}
\def\listanswers{\immediate\closeout\ans \input\jobname.ans\relax}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ansno}
% Finally we have to define how the exercise numbers will appear
% with the answers.
% By default, we reuse whatever was defined for
% |\exercise@head|.
% Typographically speaking, this should be the sound thing to do.
% But conceivably one might want to let the exercise numbers stick
% out into the margin, by saying something like
%\begin{verbatim}
%   \def\ansno#1{\par{\noindent\strut\llap{\Ansno#1 }}}
%\end{verbatim}
% where |\Ansno| contains any commands necessary for formatting
% the exercise number.
%    \begin{macrocode}
\def\ansno#1{\par{\def\theexercise{#1}\exercise@head}}
%    \end{macrocode}
% \end{macro}
% \Finale
\endinput