Debian Codegraph @

texmf-dist/source/latex/dialogl/menus.dtx

raw
1 %%% ====================================================================
2 %%% @LaTeX-style-file{
3 %%% filename = "menus.dtx",
4 %%% version = "1.99a",
5 %%% date = "2013/01/24",
6 %%% author = "Michael Downes",
7 %%% copyright = "This file is part of the dialogl package, released
8 %%% under the LPPL; see dialogl.ins for details."
9 %%% keywords = "TeX, menus",
10 %%% supported = "no",
11 %%% abstract = "This file provides functions for writing
12 %%% messages and menus on screen, and reading user responses. It
13 %%% can be used with LaTeX as a documentstyle option, or in
14 %%% other forms of TeX by a standard \input statement.",
15 %%% }
16 %%% ====================================================================
17 %
18 % \iffalse
19 %<*driver>
20 \input{dia-driv.tex}
21 %</driver>
22 % \fi
23 %
24 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
25 % \section{Function descriptions}
26 %
27 %\begin{usage}
28 %\fmenu\foobar{
29 % <preliminary text>
30 %}{
31 % <menu lines>
32 %}{
33 % <following text>
34 %}
35 %\end{usage}
36 % Defines \cw{foobar} as a function that puts the preliminary text,
37 % the menu lines (list of choices), and the after text on screen.
38 % Normal usage:
39 %
40 %^^V \foobar % print the menu on screen
41 %^^V \readline{}\reply % read the answer
42 %
43 % (See the description of \cw{readline} in \fn{dialog.doc}.) In the
44 % various text parts all special characters have category 12 except
45 % for braces, as with \cw{mesj}. Note the recommended placement of
46 % the braces: no closing brace falls at the end of a line, except
47 % the very last one. Because of the special catcodes in effect when
48 % reading the final three arguments, a \ctrl{M} or \qc{\%} between
49 % arguments would be read as an active character or category-12
50 % character respectively, instead of being ignored. But actually,
51 % after some rather difficult programming, I managed to make it
52 % possible to write just about anything (except brace characters)
53 % between the arguments and have it be ignored, so the recommended
54 % style is not mandatory. The first and last newline of each
55 % argument are stripped off anyway in order to produce consistent
56 % clean connections with \cw{menuprefix} etc.; see below.
57 %
58 % Menu functions created by \cw{fmenu} are allowed optionally to
59 % have arguments, like functions created with \cw{fmesj} (from
60 % \fn{dialog.sty}), so that pieces of text can be inserted at the
61 % time of use. This makes it possible for several similar menus to
62 % share the same menu function if there are only minor variations
63 % between them.
64 %
65 %\begin{usage}
66 %\menuprefix, \menusuffix
67 %\inmenuA, \inmenuB
68 %\end{usage}
69 % The text \cw{menuprefix} will be added at the beginning of each
70 % menu; \cw{menusuffix} will be added at the end. The text
71 % \cw{inmenuA} and \cw{inmenuB} will be added between the first and
72 % second, respectively second and third parts of the menu; their
73 % default values produce a blank line on screen. (But
74 % \cw{inmenuA} will be omitted if the first part is empty, and
75 % \cw{inmenuB} will be omitted if the last part is empty.) To change
76 % any of these texts, use \cw{storemesj} or \cw{storexmesj}. For
77 % example:
78 %
79 %^^V\storemesj\menuprefix{********* MENU **********}
80 %
81 %\begin{usage}
82 %\menuprompt
83 %\end{usage}
84 % Furthermore, the function \cw{menuprompt} is called at the very
85 % end of the menu, so that for example a standard prompt such as
86 % \verb'Enter a number:' could be applied at the end of all menus,
87 % if desired. To change \cw{menuprompt}, use \cw{fmesj} or
88 % \cw{fxmesj}.
89 %
90 %\begin{usage}
91 %\menuline, \endmenuline
92 %\menutopline, \menubotline
93 %\end{usage}
94 % Each line in the middle argument of \cw{fmenu} (the list of
95 % choices) is embedded in a statement
96 % \cw{menuline}\verbdots\cw{endmenuline}. The default definition of
97 % \cw{menuline} is to add two spaces at the beginning and a newline
98 % at the end. Lines in the top or bottom part of the menu are
99 % embedded in \cw{menutopline}\verbdots\cw{endmenuline} or
100 % \cw{menubotline}\verbdots\cw{endmenuline} respectively. (Notice
101 % that all three share the same ending delimiter; if different
102 % actions are wanted at the end of a top or bottom line as opposed
103 % to a middle menu line, they must be obtained by defining
104 % \cw{menutopline} or \cw{menubotline} to read the entire line as
105 % an argument and perform the desired processing.)
106 %
107 % An enclosing box for a menu can be obtained by
108 % defining \cw{menuline} and its relatives appropriately and using
109 % \cw{fxmenu} (see below).
110 %
111 %\begin{usage}
112 %\fxmenu\foobar{
113 % <preliminary text>
114 %}{
115 % <menu lines>
116 %}{
117 % <following text>
118 %}
119 %\end{usage}
120 % Similar to \cw{fmenu} but with full expansion in each part of the
121 % text, as with \cw{xmesj}.
122 %
123 % To get an enclosing box for a menu, write \cs{\.} at the end of
124 % each menu line (to protect the preceding spaces from \tex/'s
125 % propensity to remove character 32 at the end of a line,
126 % regardless of its catcode), and then make sure that \cw{menuline}
127 % and \cw{endmenuline} put in the appropriate box-drawing
128 % characters on either side. I.e.:
129 %
130 %^^V \fxmenu\foobar{
131 %^^V First line \.
132 %^^V Second line \.
133 %^^V }{
134 %^^V Third line \.
135 %^^V ...
136 %^^V }{
137 %^^V Last line \.
138 %^^V }
139 %
140 % With the \verb'/o' option of em\tex/, you can use the box-drawing
141 % characters in the standard PC DOS character set.
142 %
143 %\begin{usage}
144 %\nmenu\Alph\foobar#1{
145 % <preliminary text>
146 %}{
147 % <menu lines>
148 %}{
149 % <following text>
150 %}
151 %\end{usage}
152 % \cw{nmenu} and \cw{nxmenu} are like \cw{fmenu}, \cw{fxmenu}
153 % except that they automatically number each line of the middle
154 % part of the menu. (This allows menu choices to be added or deleted
155 % without tedious renumbering.) The first argument indicates the
156 % type of numbers to be used: \cw{alph}, \cw{Alph}, \cw{arabic},
157 % \cw{roman}, \cw{Roman} (following \latex/). {\em These are not yet
158 % implemented.}
159 %^^A [15-May-1993,mjd]
160 %
161 % The function \cw{menunumber} (taking one argument) is applied to
162 % each automatically generated number. The default value is to add
163 % brackets and a space after:
164 %
165 %^^V \def\menunumber#1{[#1] }
166 %
167 % but by redefining \cw{menunumber} you can add parentheses or extra
168 % spaces or what have you around each number. Internally a line of
169 % an autonumbered menu is stored as
170 %
171 %^^V \menuline\menunumber{5}Text text ...\endmenuline
172 %
173 %\begin{usage}
174 %\optionexec\answer
175 %\end{usage}
176 % This is a companion function for \cw{readChar} and the menu
177 % functions: it checks to see if the answer is equal to any one of
178 % the characters \qc{\?} \qc{\Q} \qc{\q} \qc{\X} \qc{\x}, and if so
179 % executes \cw{moption?} or \cw{moptionQ} or \cw{moptionX}
180 % respectively, otherwise executes
181 %
182 %^^V \csname moption\curmenu C\endcsname
183 %
184 % where \qc{\C} means the character that was read and \cw{curmenu} is
185 % a string identifying the current location in the menu system.
186 % (\cw{optionexec} pushes and pops \cw{curmenu} when going between
187 % menus, to keep it up to date.) If this control sequence is
188 % undefined, \cw{optionexec} gives a generic ``Sorry, I don't
189 % understand'' message and repeats the current menu.
190 %
191 % Thus the major work involved in making a menu system is to define
192 % the menu screens using \cw{fmenu}, \cw{fxmenu}, and then define
193 % corresponding functions \cw{moptionXXX} that display one of the
194 % menu screens, read a menu choice, and call \cw{optionexec} to
195 % branch to the next action.
196 %
197 %\begin{usage}
198 %\specialhelp\answer{Substitute message}
199 %\end{usage}
200 % As it turns out, it is sometimes desirable to substitute some
201 % other message in place of the generic ``Sorry, I don't
202 % understand'' message given by \cw{optionexec}. For instance,
203 % suppose a given menu choice leads to a secondary prompt where you
204 % ask the user to enter a number of columns for printing some data.
205 % If the user accidentally mistypes \verb'0', it would be better to
206 % respond with something like
207 %
208 %^^V Number of columns must be greater than 0.
209 %
210 % than with the generic message. The function \cw{specialhelp}
211 % allows you to do this. The first argument is the name of the
212 % macro that will be passed to \cw{optionexec}. \cw{specialhelp}
213 % modifies that macro to a flag value that will trigger the
214 % substitute message. (But does it carefully, so that you can still
215 % use the macro naturally in the substitute message text.)
216 %
217 %\begin{usage}
218 %\optionfileexec\answer
219 %\end{usage}
220 % Like \cw{optionexec}, but gets the next menu from a file instead
221 % of from main memory, if applicable. This is not yet
222 % implemented.
223 %^^A [mjd,24-May-1993]
224 % The technical complications involved in managing the menu files
225 % are many\Dash for example: How do you prevent the usual file name
226 % message of \tex/ from intruding on your carefully designed menu
227 % screens, if \cw{input} is used to read the next menu file?
228 % Alternatively if you try to use \cw{read} to read the next menu
229 % file, how do you deal with catcode changes?
230 %
231 %\begin{usage}
232 %\lettermenu{MN}
233 %\end{usage}
234 % This is an abbreviation for
235 %
236 %^^V \menuMN \readChar{Q}\reply \optionexec\reply
237 %
238 % It calls the menu function associated with the menu name \verb"MN",
239 % reads a single uppercase letter into \cw{reply}, and then calls
240 % \cw{optionexec} to branch to the case selected by the reply.
241 %
242 %\begin{usage}
243 %\if\xoptiontest\answer ... \else ... \fi
244 %\end{usage}
245 % The function \cw{xoptiontest} is for use with \cw{readline} or
246 % \cw{xreadline}, to trap the special responses \verb'? Q q X x'
247 % before executing some conditional code. It returns a `true' value
248 % suitable for \cw{if} testing, if and only if the replacement text
249 % of \cw{answer} is a single character matching one of those
250 % listed. This is used when you are prompting for a response that
251 % can be an arbitrary string of characters, but you want to allow
252 % the user still to get help or quit with the same one-character
253 % responses that are recognized in other situations.
254 %
255 % \StopEventually{}
256 %
257 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
258 %
259 % \section{Implementation}
260 % Standard package identification:
261 % \begin{macrocode}
262 %<*2e>
263 \NeedsTeXFormat{LaTeX2e}
264 \ProvidesPackage{menus}[1994/11/08 v0.9x]
265 % \end{macrocode}
266 % Load the dialog package if necessary.
267 % \begin{macrocode}
268 \RequirePackage{dialog}
269 %</2e>
270 % \end{macrocode}
271 %
272 % This file requires \fn{grabhedr.sty} and \fn{dialog.sty}. If
273 % \fn{grabhedr.sty} is not already loaded, load it now and call
274 % \cw{fileversiondate}, since it's too late to apply \cw{inputfwh}
275 % to {\em this\/} file. See the documentation of \cw{trap.input} in
276 % \fn{grabhedr.doc}.
277 % \begin{macrocode}
278 %<*209>
279 \csname trap.input\endcsname
280 \input grabhedr.sty \relax
281 \fileversiondate{menus.sty}{0.9x}{1994/11/08}
282 % \end{macrocode}
283 %
284 % \begin{macrocode}
285 \inputfwh{dialog.sty}
286 %</209>
287 % \end{macrocode}
288 %
289 %\section{Definitions}
290 %
291 % We start by using the \cw{localcatcodes} function from
292 % \fn{grabhedr.sty} to save current catcodes and set new catcodes
293 % for certain significant characters, as explained at more length
294 % in \fn{dialog.doc}.
295 %
296 % \begin{macrocode}
297 \localcatcodes{\@{11}%
298 \~{13}\"{12}\#{6}\^{7}\`{12}\${3}\:{12}}
299 % \end{macrocode}
300 %
301 %\begin{macro}{\menuprefix}
302 % \cw{menuprefix} is a string added at the beginning of each menu to
303 % pretty it up a little (or uglify it a little, depending on your
304 % taste). The length of the default string is 70 characters, not
305 % counting the two newline characters. By using \cw{storexmesj} we
306 % get embedded newlines corresponding to the ones seen here. [That
307 % is, except for the extra line break (where the newline character is
308 % commented out), needed to make this fit in the current column
309 % width.]
310 %
311 %\iftrue
312 %^^V \storexmesj\menuprefix{
313 %^^V ===================================%
314 %^^V ===================================
315 %^^V }
316 %
317 %\else
318 % \begin{macrocode}
319 \storexmesj\menuprefix{
320 ======================================================================
321 }
322 % \end{macrocode}
323 %\fi
324 % \end{macro}
325 %
326 % \begin{macro}{\menusuffix}
327 % The default value for \cw{menusuffix} is the same as for
328 % \cw{menuprefix}.
329 % \begin{macrocode}
330 \let\menusuffix=\menuprefix
331 % \end{macrocode}
332 % \end{macro}
333 %
334 % \begin{macro}{\inmenuA}
335 % \begin{macro}{\inmenuB}
336 % The default for \cw{inmenuA} and \cw{inmenuB} is a single
337 % newline, which will produce a blank line on screen because they
338 % will occur after an \cw{endmenuline}, which also
339 % contains a newline.
340 % \begin{macrocode}
341 \storemesj\inmenuA{
342 }
343 \storemesj\inmenuB{
344 }
345 % \end{macrocode}
346 % \end{macro}
347 % \end{macro}
348 %
349 %\begin{macro}{\menuline}
350 % The default value for \cw{menuline} is two spaces. This means
351 % that each line in the middle section of a menu defined by
352 % \cw{fmenu} or \cw{fxmenu} will be indented two spaces.
353 % \begin{macrocode}
354 \storemesj\menuline{ }
355 % \end{macrocode}
356 % \end{macro}
357 %
358 % \begin{macro}{\menutopline}
359 % \begin{macro}{\menubotline}
360 % By default, no spaces are added at the beginning of a line in the
361 % top or bottom section of a menu:
362 % \begin{macrocode}
363 \def\menutopline{}
364 \def\menubotline{}
365 % \end{macrocode}
366 % \end{macro}
367 % \end{macro}
368 %
369 % \begin{macro}{\endmenuline}
370 % \cw{endmenuline} is just a newline.
371 % \begin{macrocode}
372 \storemesj\endmenuline{
373 }%
374 % \end{macrocode}
375 % \end{macro}
376 %
377 % \begin{macro}{\menunumber}
378 % This definition of \cw{menunumber} adds square brackets and a
379 % following space around each item number.
380 % \begin{macrocode}
381 \def\menunumber#1{[#1] }
382 % \end{macrocode}
383 % \end{macro}
384 %
385 % \begin{macro}{\menuprompt}
386 % This definition of \cw{menuprompt} is suitable for the purposes
387 % of \fn{listout.tex} but will probably need to be no-op'd or
388 % changed for other applications.
389 % \begin{macrocode}
390 \def\menuprompt{\promptmesj{Your choice? }}
391 % \end{macrocode}
392 % \end{macro}
393 %
394 % \begin{macro}{\menufirstpart}
395 % \begin{macro}{\menuchoices}
396 % \begin{macro}{\menulastpart}
397 % Each of the three pieces of a menu gets its own token register.
398 % \begin{macrocode}
399 \newtoks\menufirstpart
400 \newtoks\menuchoices
401 \newtoks\menulastpart
402 % \end{macrocode}
403 % \end{macro}
404 % \end{macro}
405 % \end{macro}
406 %
407 % \begin{macro}{\fmenu}
408 %
409 % The `arguments' of \cw{fmenu} are \arg{1} menu name, \arg{2}
410 % optional argument specifiers, \arg{3} preliminary text, \arg{4}
411 % list of menu choices, \arg{5} following text. But at first we read
412 % only the first two because we want to change some catcodes before
413 % reading the others. The auxiliary function \cw{fxmenub} is shared
414 % with \cw{fxmenu}.
415 %
416 % Because of the catcode changes done by \cw{mesjsetup}, newlines,
417 % spaces, or percent signs between the three final arguments will
418 % not be ignored. To get around this, we use the peculiar
419 % \verb'#{' feature of \tex/, in intermediate scratch functions
420 % called \cw{@tempa}, to read and discard anything that may occur
421 % between one closing brace and the next opening brace. Token
422 % register assignments are used to read the arguments proper.
423 %
424 % \begin{macrocode}
425 \def\fmenu#1#2#{\mesjsetup
426 \catcode`\#=6 % for parameters
427 \toks@{\fxmenub{\gdef}{\begingroup}{}#1{#2}}%
428 \def\@tempa##1##{%
429 \def\@tempa####1####{%
430 \def\@tempa{\the\toks@}%
431 \afterassignment\@tempa \menulastpart}%
432 \afterassignment\@tempa \menuchoices}%
433 \afterassignment\@tempa \menufirstpart
434 }
435 % \end{macrocode}
436 % \end{macro}
437 %
438 % Before proceeding to define \cw{fxmenub}, we must deal with a
439 % subproblem. What we will have to work with is three pieces of text
440 % in the token registers \cw{menufirstpart}, \cw{menuchoices}, and
441 % \cw{menulastpart}, containing active \ctrl{M} characters to mark
442 % line breaks, including possibly but not necessarily \ctrl{M} at the
443 % beginning and at the end of each piece. What we would like to do,
444 % for each piece, is to remove the first \ctrl{M}, if there is one,
445 % and the last one, if there is one. The function \cw{stripcontrolMs}
446 % does this.
447 %
448 % If you are one of those rare \tex/ hackers who might actually
449 % want to understand the workings of \cw{stripcontrolMs}, the best
450 % way is probably to watch it in action with \cw{tracingmacros} =
451 % \cw{tracingcommands} = 2, rather than attempt to follow my labored
452 % commentary below.
453 % \begin{macrocode}
454 \begingroup % localize \lccode change
455 \lccode`\~=`\^^M
456 % \end{macrocode}
457 % The functions \cw{stripM}, \cw{stripMa}, \cw{stripMb}, \ldots\ are
458 % auxiliary functions for \cw{stripcontrolMs}. They all carry along
459 % an extra last argument, the name of the token register originally
460 % given to \cw{stripcontrolMs}, so that when we finally reach
461 % \cw{stripMd} we can carry out the assignment of the token
462 % register.
463 %
464 % When \cw{stripM} is called, it should be called like this:
465 %\begin{verbatim}
466 % \expandafter\stripM\expandafter$\the\sometoks
467 % $^^M$$\stripM\sometoks
468 %\end{verbatim}
469 % That is, \qc{\$} should be added at the beginning and \verb'$^^M$$'
470 % at the end of the text to be processed. And \cw{expandafter}'s
471 % should be added to pre-expand the token register.
472 %
473 % These examples illustrate the possible contents of (e.g.\@)
474 % \cw{menufirstpart}, before processing
475 %\begin{enumerate}\renewcommand{\theenumi}{\alph{enumi}}
476 %\renewcommand{\labelenumi}{(\theenumi)}
477 % \item \label{mmm}
478 % \verb'^^Maaa^^Mbbb^^M'
479 % \item \verb'aaa^^Mbbb'
480 % \item \verb'^^Maaa^^Mbbb'
481 % \item \verb'aaa^^Mbbb^^M'
482 %\end{enumerate}
483 % The processing of example (\ref{mmm}) would proceed as follows.
484 % Call \cw{stripM}, adding \qc{\$} at the beginning and \verb'$^^M$$'
485 % at the end.
486 %\begin{verbatim}
487 % \stripM $^^Maaa^^Mbbb^^M$^^M$$\stripM
488 %\end{verbatim}
489 % This finds a match with the \verb'$^^M' at the beginning. The
490 % remaining text is passed on to \cw{stripMb}. We know that there is
491 % now an extra \verb'$^^M$$' at the end, but we don't know if the
492 % first \qc{\$} is preceded by \ctrl{M}.
493 %\begin{verbatim}
494 % \stripMb aaa^^Mbbb^^M$^^M$$\stripMb
495 %\end{verbatim}
496 % If it turns out that \arg{2} = \qc{\$}, then there was {\em not\/}
497 % a \ctrl{M} at the end of the original text, and we need to strip
498 % off a last remaining \qc{\$} sign. Otherwise we are finished if we
499 % just discard \arg{2} and \arg{3} (the remaining \ctrl{M} and
500 % \qc{\$} characters of the ones that we added).
501 %
502 % We use \qc{\$} as a marker since any \qc{\$} characters that
503 % happen to occur in the menu text will have category 12 and thus
504 % not match the category-3 \qc{\$} used in the definition of
505 % \cw{stripMa} etc. A control sequence could also be used as a
506 % marker if we took care to give it a bizarre name that would never
507 % arise in the menu text (\cw{fxmenub} is used not just by
508 % \cw{fmenu} but also by \cw{fxmenu}, which might have arbitrary
509 % control sequences in its arguments); but that means using up one
510 % more hash table entry and additional string pool.
511 %
512 % \begin{macro}{\stripM}
513 % \begin{macrocode}
514 \lowercase{%
515 \long\gdef\stripM#1$~#2#3\stripM#4{%
516 \ifx$#2%
517 \stripMa#1\stripMa#4%
518 \else
519 \stripMb#2#3\stripMb#4%
520 \fi
521 }
522 }% end lowercase
523 % \end{macrocode}
524 % \end{macro}
525 %
526 % \begin{macro}{\stripMa}
527 % \begin{macrocode}
528 \lowercase{%
529 \long\gdef\stripMa $#1\stripMa#2{%
530 \stripMb#1$~$$\stripMb#2}
531 }% end lowercase
532 % \end{macrocode}
533 % \end{macro}
534 %
535 % \begin{macro}{\stripMb}
536 % \begin{macrocode}
537 \lowercase{%
538 \long\gdef\stripMb#1~$#2#3\stripMb#4{%
539 \ifx$#2%
540 \stripMc#1\stripMc#4%
541 \else
542 \stripMd#1\stripMd#4%
543 \fi
544 }
545 }% end lowercase
546 % \end{macrocode}
547 % \end{macro}
548 %
549 % \begin{macro}{\stripMc}
550 % \begin{macrocode}
551 \long\gdef\stripMc#1$#2\stripMc#3{%
552 \stripMd#1\stripMd#3}
553 % \end{macrocode}
554 % \end{macro}
555 %
556 % \begin{macro}{\stripMd}
557 % \begin{macrocode}
558 \long\gdef\stripMd#1\stripMd#2{#2{#1}}
559 \endgroup
560 % \end{macrocode}
561 % \end{macro}
562 %
563 % Some tests.
564 %\begin{verbatim}
565 % %\lowercase{\def\test#1{\stripM $#1$~$$\stripM}
566 % %\tracingmacros=2 \tracingcommands=2 \tracingonline=1
567 % %\test{~aaa~bbb~}
568 % %\test{aaa~bbb}
569 % %\test{~aaa~bbb}
570 % %\test{aaa~bbb~}
571 % %\tracingmacros=0 \tracingcommands=0 \tracingonline=0
572 % %}% end lowercase
573 %\end{verbatim}
574 %
575 % \begin{macro}{\stripcontrolMs}
576 % The argument of \cw{stripcontrolMs} is a token register. The text
577 % of the token register will be stripped of a leading and trailing
578 % \ctrl{M} if either or both are present, and the remainder text will
579 % be left in the token register.
580 %
581 % \begin{macrocode}
582 \begingroup \lccode`\~=`\^^M
583 \lowercase{%
584 \gdef\stripcontrolMs#1{\xp@\stripM
585 \xp@$\the#1$~$$\stripM#1}
586 }% end lowercase
587 % \end{macrocode}
588 % \end{macro}
589 %
590 % \begin{macro}{\addmenulines}
591 % \begin{macrocode}
592 \lowercase{%
593 \gdef\addmenulines#1#2#3{%
594 % \end{macrocode}
595 % Add \arg{2} at the beginning and \arg{3} at the end of every line
596 % of token register \arg{1}.
597 % \begin{macrocode}
598 \def ~##1~##2{%
599 #1\xp@{\the#1#2##1#3}%
600 \ifx\end##2\xp@\@gobbletwo\fi~##2}%
601 \edef\@tempa{\nx@~\the#1\nx@~}#1{}%
602 \@tempa\end}
603 }% end lowercase
604 \endgroup % restore lccode of ~
605 % \end{macrocode}
606 % \end{macro}
607 %
608 % \begin{macro}{\fxmenub}
609 %
610 % The function \cw{fxmenub} is the one that does most of the hard
611 % work for \cw{fmenu} and \cw{fxmenu}. Argument \arg{4} is the name
612 % of the menu, \arg{5} is the argument specifiers (maybe empty).
613 % Arguments \arg{1}\arg{2}\arg{3} are assignment type, extra setup,
614 % and expansion control; specifically, these arguments are
615 % \cw{gdef} \cw{begingroup} \cw{empty} for \cw{fmenu} or \cw{xdef}
616 % \cw{xmesjsetup} and an extra \cw{noexpand} for \cw{fxmenu}.
617 %
618 % That this function actually works should probably be regarded as
619 % a miracle rather than a result of my programming efforts.^^A
620 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
621 % \footnote{Let's see, three miracles is a prerequisite for sainthood
622 % in the Catholic church\Dash only two more needed for Don
623 % Knuth to be a candidate \dots}
624 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
625 % \begin{macrocode}
626 \def\fxmenub#1#2#3#4#5{%
627 \stripcontrolMs\menufirstpart
628 \stripcontrolMs\menulastpart
629 \stripcontrolMs\menuchoices
630 \addmenulines\menuchoices\menuline\endmenuline
631 \actively\let\^^M\relax % needed for \xdef
632 % \end{macrocode}
633 % Define \arg{4}. Expansion control is rather tricky because of the
634 % possibility of parameter markers inside \cw{menufirstpart},
635 % \cw{menuchoices} or \cw{menulastpart}.
636 % \begin{macrocode}
637 \toks@{\long#1#4#5}% e.g. \xdef\foo##1##2
638 % \end{macrocode}
639 % If \cw{menufirstpart} is empty, we don't add the separator
640 % material \cw{inmenuA}.
641 % \begin{macrocode}
642 \edef\@tempa{\the\menufirstpart}%
643 \ifx\@tempa\@empty
644 \let\nxa@\@gobble
645 \else
646 \addmenulines\menufirstpart
647 \menutopline\endmenuline
648 \let\nxa@\nx@
649 \fi
650 % \end{macrocode}
651 % If \cw{menulastpart} is empty, we don't add the separator
652 % material \cw{inmenuB}.
653 % \begin{macrocode}
654 \edef\@tempa{\the\menulastpart}%
655 \ifx\@tempa\@empty
656 \let\nxb@\@gobble
657 \else
658 \addmenulines\menulastpart
659 \menubotline\endmenuline
660 \let\nxb@\nx@
661 \fi
662 % \end{macrocode}
663 % Set up the definition statement that will create the new menu.
664 % \arg{2} = \cw{begingroup} or \cw{xmesjsetup}.
665 % \begin{macrocode}
666 \edef\@tempa{{#3\nx@#3#2%
667 \def#3\nx@#3\mesjtext{%
668 #3\nx@#3\menuprefix
669 \the\menufirstpart #3\nxa@#3\inmenuA
670 \the\menuchoices #3\nxb@#3\inmenuB
671 \the\menulastpart #3\nx@#3\menusuffix}%
672 #3\nx@#3\sendmesj
673 #3\nx@#3\menuprompt}}%
674 \toks2 \xp@{\@tempa}%
675 \edef\@tempa{\the\toks@\the\toks2 }%
676 % \end{macrocode}
677 % Temporarily \cw{relax}ify \cw{menuline} etc. in order to prevent
678 % their premature expansion if \cw{xdef} is applied.
679 % \begin{macrocode}
680 \let\menutopline\relax \let\menuline\relax
681 \let\menubotline\relax \let\endmenuline\relax
682 \let\menunumber\relax
683 \@tempa % finally, execute the \gdef or \xdef
684 \endgroup % matches \mesjsetup done by \fxmenu
685 }% end \fxmenub
686 % \end{macrocode}
687 % \end{macro}
688 %
689 % \begin{macro}{\fxmenu}
690 %
691 % Expanding analog of \cw{fmenu}.
692 % \begin{macrocode}
693 \def\fxmenu#1#2#{\xmesjsetup
694 \toks@{\fxmenub{\xdef}{\xmesjsetup}\nx@#1{#2}}%
695 \def\@tempa##1##{%
696 \def\@tempa####1####{%
697 \def\@tempa{\the\toks@}%
698 \afterassignment\@tempa \menulastpart}%
699 \afterassignment\@tempa \menuchoices}%
700 \afterassignment\@tempa \menufirstpart
701 }
702 % \end{macrocode}
703 % \end{macro}
704 %
705 % \begin{macro}{\notyet}
706 %
707 % \begin{macrocode}
708 \def\notyet#1{%
709 \errmessage{Not yet implemented: \string#1}}
710 % \end{macrocode}
711 % \end{macro}
712 %
713 % \begin{macro}{\nmenu}
714 % \begin{macro}{\nxmenu}
715 % These two functions aren't implemented yet.
716 %^^A [mjd,24-May-1993]
717 % \begin{macrocode}
718 \long\def\nmenu#1#2#3#4#5{\notyet\nmenu}
719 \long\def\nxmenu#1#2#3#4#5{\notyet\nxmenu}
720 % \end{macrocode}
721 % \end{macro}
722 % \end{macro}
723 %
724 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
725 % \section{Menu traversal functions}
726 %
727 % For reliable travel up and down the menu tree, we need to push
728 % and pop the value of \cw{curmenu} as we go along. Among other
729 % things, \cw{curmenu} is used to repeat the current menu after a
730 % help message.
731 %
732 % \begin{macro}{\optionstack}
733 % \begin{macrocode}
734 \newtoks\optionstack
735 % \end{macrocode}
736 % \end{macro}
737 %
738 % \begin{macro}{\curmenu}
739 % \begin{macrocode}
740 \let\curmenu\@empty
741 % \end{macrocode}
742 % \end{macro}
743 %
744 % \begin{macro}{\estart}
745 % Start of a stack element.
746 % \begin{macrocode}
747 \let\estart\relax
748 % \end{macrocode}
749 % \end{macro}
750 %
751 % \begin{macro}{\eend}
752 % End of a stack element.
753 % \begin{macrocode}
754 \let\eend\relax
755 % \end{macrocode}
756 % \end{macro}
757 %
758 % \begin{macro}{\pushoptions}
759 % \begin{macrocode}
760 \def\pushoptions#1{%
761 \edef\pushtemp{\estart
762 \def\nx@\curmenu{\curmenu}%
763 \eend
764 \the\optionstack}%
765 \global\optionstack\xp@{\pushtemp}%
766 \edef\curmenu{\curmenu#1}%
767 }
768 % \end{macrocode}
769 % \end{macro}
770 %
771 % \begin{macro}{\popoptions}
772 % \begin{macrocode}
773 \def\popoptions{%
774 \edef\@tempa{\the\optionstack}%
775 \ifx\@empty\@tempa
776 \errmessage{Can't pop empty stack
777 (\string\optionstack)}%
778 \else
779 \def\estart##1\eend##2\@nil{%
780 \global\optionstack{##2}%
781 \let\estart\relax##1}%
782 \the\optionstack\@nil
783 \fi
784 }
785 % \end{macrocode}
786 % \end{macro}
787 %
788 % \begin{macro}{\moptionX}
789 %
790 % The \qc{\X} option is a total exit from the menu maze, as
791 % compared to \cw{moptionQ}, which returns you to the previous menu
792 % level.
793 %
794 % \begin{macrocode}
795 \fmesj\moptionX{Exiting . . .}
796 % \end{macrocode}
797 % \end{macro}
798 %
799 % \begin{macro}{\repeatoption}
800 % \begin{macrocode}
801 \def\repeatoption{%
802 \csname moption\curmenu\endcsname}
803 % \end{macrocode}
804 % \end{macro}
805 %
806 % \begin{macro}{\moptionQ}
807 % \begin{macrocode}
808 \def\moptionQ{\popoptions \repeatoption}
809 % \end{macrocode}
810 % \end{macro}
811 %
812 % \begin{macro}{\badoptionmesj}
813 % The sole reason for using \cw{fxmesj} rather than \cw{fmesj} here
814 % is to use \qc{\%} to comment out the initial newline, as the line
815 % break was needed only for convenient printing of this
816 % documentation within a narrow column width.
817 % \begin{macrocode}
818 \fxmesj\badoptionmesj#1{%
819 ?---I don't understand "#1".}
820 % \end{macrocode}
821 % \end{macro}
822 %
823 % \begin{macro}{\optionexec}
824 %
825 % The function \cw{optionexec} takes one argument, which it uses
826 % together with \cw{curmenu} to determine the next action. The
827 % argument is expected to be a macro containing a single letter,
828 % the most recent menu choice received from the user.
829 %
830 % Common options such as \qc{\?}, \qc{\Q}, or \qc{\X} that may
831 % occur at any level of the menu system are handled specially, to
832 % cut down on the number of control sequence names needed for a
833 % csname implementation of the menus.
834 % \begin{macrocode}
835 \def\optionexec#1{%
836 \if ?#1\relax \let\@tempa\moptionhelp
837 \else \if Q#1\relax
838 \ifx\curmenu\@empty \let\@tempa\moptionX
839 \else \let\@tempa\moptionQ \fi
840 \else \if X#1\relax \let\@tempa\moptionX
841 \else
842 % \end{macrocode}
843 % Because special characters, including backslash, are deactivated
844 % by \cw{readChar}, we can apply \cw{csname} without fearing problems
845 % from responses such as \cw{relax}.
846 % \begin{macrocode}
847 \xp@\let\xp@\@tempa
848 \csname moption\curmenu#1\endcsname
849 \ifx\@tempa\relax
850 \badoptionmesj{#1}\let\@tempa\repeatoption
851 \else
852 \pushoptions{#1}%
853 \fi
854 \fi\fi\fi
855 % \end{macrocode}
856 % We save up the next action in \cw{@tempa} and execute it last, to
857 % get tail recursion.
858 % \begin{macrocode}
859 \@tempa
860 }
861 % \end{macrocode}
862 % \end{macro}
863 %
864 % Really big menu systems could get around \tex/ memory limits by
865 % storing individual menus or groups of menus in separate files and
866 % using \cw{optionfileexec} in place of \cw{optionexec} to
867 % retrieve the menu text from disk storage instead of from main
868 % memory. However there are a number of technical complications and
869 % I probably won't get around to working on them in the near future.
870 %^^A [mjd,24-May-1993]
871 %
872 % \begin{macro}{\optionfileexec}
873 % \begin{macrocode}
874 \def\optionfileexec#1{\notyet\optionfileexec}
875 % \end{macrocode}
876 % \end{macro}
877 %
878 % \begin{macro}{\xoptiontest}
879 % The function \cw{xoptiontest} must return true if and only if the
880 % macro \arg{1} consists entirely of one of the one-letter
881 % responses \verb"? Q q X x" that correspond to special menu
882 % actions. The rather cautious implementation with \cw{aftergroup}
883 % avoids rescanning the contents of \verb"#1", just in case it
884 % contains anything that's \cw{outer}.
885 % \begin{macrocode}
886 \def\xoptiontest#1{TT\fi
887 \begingroup \def\0{?}\def\1{Q}%
888 \def\2{q}\def\3{x}\def\4{X}%
889 \aftergroup\if\aftergroup T%
890 \ifx\0#1\aftergroup T%
891 \else\ifx\1#1\aftergroup T%
892 \else\ifx\2#1\aftergroup T%
893 \else\ifx\3#1\aftergroup T%
894 \else\ifx\4#1\aftergroup T%
895 \else \aftergroup F%
896 \fi\fi\fi\fi\fi
897 \endgroup
898 }
899 % \end{macrocode}
900 % \end{macro}
901 %
902 % \begin{macro}{\menuhelpmesj}
903 %
904 % Default help message, can be redefined if necessary. The extra
905 % newlines commented out with \qc{\%} are here only for convenient
906 % printing within a narrow column width.
907 %
908 % \begin{macrocode}
909 \fxmesj\menuhelpmesj{&\menuprefix%
910 A response of Q will usually send you back to %
911 the previous menu.
912 A response of X will get you entirely out of %
913 the menu system.
914 &\menusuffix%
915 Press the <Return> key ( Enter ) to continue:
916 }
917 % \end{macrocode}
918 % \end{macro}
919 %
920 % \begin{macro}{\moptionhelp}
921 % \begin{macrocode}
922 \def\moptionhelp{%
923 \menuhelpmesj \readline{}\reply \repeatoption}
924 % \end{macrocode}
925 % \end{macro}
926 %
927 % \begin{macro}{\moptionhelp}
928 % \cw{moptionhelp} is the branch that will be taken if the user
929 % enters a question mark in response to a menu.
930 % \begin{macrocode}
931 \def\moptionhelp{%
932 \menuhelpmesj \readline{}\reply \repeatoption}
933 % \end{macrocode}
934 % \end{macro}
935 %
936 % \begin{macro}{\moption?}
937 % \begin{macrocode}
938 \xp@\def\csname moption?\endcsname{%
939 \moptionhelp}
940 % \end{macrocode}
941 % \end{macro}
942 %
943 % \begin{macro}{\specialhelp}
944 % The function \cw{specialhelp} can be used to provide a one-time
945 % alternate help message tailored to a specifc response given by
946 % the user. It defines the first argument (the macro containing the
947 % response) to contain \qc{\?}, then redefines \cw{menuhelpmesj} to
948 % use the message text given in arg \arg{2}.
949 % \begin{macrocode}
950 \def\specialhelp#1#2{%
951 \let\specialhelpreply=#1\def#1{?}\begingroup
952 \def\menuhelpmesj{\let#1\specialhelpreply
953 \promptxmesj{#2\
954 Press <return> to continue:}\endgroup}%
955 }
956 % \end{macrocode}
957 % \end{macro}
958 %
959 % \begin{macro}{\specialhelpreply}
960 % Init.
961 % \begin{macrocode}
962 \def\specialhelpreply{}
963 % \end{macrocode}
964 % \end{macro}
965 %
966 % \begin{macro}{\lettermenu}
967 % This is a convenient abbreviation for an often-used combination.
968 % \begin{macrocode}
969 \def\lettermenu#1{%
970 \csname menu#1\endcsname
971 \readChar{Q}\reply \optionexec\reply
972 }
973 % \end{macrocode}
974 % \end{macro}
975 %
976 % Restore any catcodes changed locally, and depart.
977 % \begin{macrocode}
978 \restorecatcodes
979 \endinput
980 % \end{macrocode}
981 %
982 % \CheckSum{513}
983 % \Finale