Debian Codegraph @

texmf-dist/source/latex/gamebooklib/gamebooklib.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2021 by Robert J Lee
4 %
5 % This file may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of
13 % LaTeX version 2005/12/01 or later.
14 %
15 % \fi
16 %
17 % \iffalse
18 % <package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
19 % <package>\ProvidesPackage{gamebooklib}
20 % <package> [2023/07/28 v1.4 gamebooklib typesetting]
21 %
22 %<*driver>
23 \documentclass{ltxdoc}
24 \usepackage{makeidx}
25 \usepackage[seed=1234]{lcg}
26 \usepackage{gamebooklib}
27 \usepackage{indentfirst}
28 \EnableCrossrefs
29 \CodelineIndex
30 \RecordChanges
31 \makeindex
32 \begin{document}
33 \DocInput{gamebooklib.dtx}
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \CharacterTable
39 % {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
40 % 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
41 % Digits \0\1\2\3\4\5\6\7\8\9
42 % Exclamation \! Double quote \" Hash (number) \#
43 % Dollar \$ Percent \% Ampersand \&
44 % Acute accent \' Left paren \( Right paren \)
45 % Asterisk \* Plus \+ Comma \,
46 % Minus \- Point \. Solidus \/
47 % Colon \: Semicolon \; Less than \<
48 % Equals \= Greater than \> Question mark \?
49 % Commercial at \@ Left bracket \[ Backslash \\
50 % Right bracket \] Circumflex \^ Underscore \_
51 % Grave accent \` Left brace \{ Vertical bar \|
52 % Right brace \} Tilde \~}
53 %
54 % \CheckSum{722}
55 %
56 % \changes{v1.0}{2021/08/10}{Initial Release}
57 % \changes{v1.1}{2021/08/24}{Bugfix: edge case with clashing fixed-index entries}
58 % \changes{v1.2}{2021/09/11}{Bugfix: footnotes set justified on last line}
59 % \changes{v1.4}{2022/07/28}{Improved documentation}
60 %
61 % \GetFileInfo{gamebooklib.sty}
62 %
63 % \DoNotIndex{\let, \edef, \xdef, \relax, \newcommand}
64 % \DoNotIndex{\csname, \endcsname, \@M, \@MM, \@gobble}
65 % \DoNotIndex{\@ifnextchar, \@tmp, \@undefined, \\}
66 % \DoNotIndex{\arabic, \begin, \begingroup, \botmark, \break}
67 % \DoNotIndex{\@tmp, \@tmp@, \mytmp@, \tmp@, \tmp@@}
68 % \DoNotIndex{\centerline, \cs, \def, \detokenize, \else}
69 % \DoNotIndex{\endgroup, \equal, \expandafter, \fi}
70 % \DoNotIndex{\gdef, \global, \head, \hspace, \Huge, \if}
71 % \DoNotIndex{\ifcsname, \ifhmode, \ifnum, \ifthenelse, \ifvmode}
72 % \DoNotIndex{\numexpr}
73 % \DoNotIndex{\interlinepenalty, \interlinefootnotepenalty}
74 % \DoNotIndex{\large, \leftskip, \mark, \NeedsTeXFormat}
75 % \DoNotIndex{\newcounter, \newenvironment, \newtoks, \noexpand}
76 % \DoNotIndex{\noindexnt, \nopagebreak, \not, \PackageInfo, \pagebreak}
77 % \DoNotIndex{\par, \PassOptionsToClass, \penalty, \ProcessOptions}
78 % \DoNotIndex{\protected@xdef, \ProvidesPackage, \rand, \requirecommand}
79 % \DoNotIndex{\RequirePackage, \rightskip, \rule, \setbox}
80 % \DoNotIndex{\setcounter, \stepcounter, \textbf, \value}
81 % \DoNotIndex{\vbox, \unvbox, \vfill, \vspace, \vsize}
82 % \DoNotIndex{\WarningFilter, \whiledo, \Collect@Body, \CurrentOption}
83 % \DoNotIndex{\DeclareOption, \g@addto@macro, \the, \noindent}
84 % \DoNotIndex{\interfootnotelinepenalty, \marginpar}
85 % \DoNotIndex{\addtocounter, \refstepcounter, \label}
86 % \DoNotIndex{\iffalse, \iftrue, \outputpenalty, \renewcommand}
87 % \DoNotIndex{\noshuffle, \verbose, \endpage, \footnote}
88 % \DoNotIndex{\if\dots}
89 %
90 % \title{The Gamebooklib Package\thanks{This document corresponds to \textsf{Gamebooklib}~\fileversion, dated \filedate.}}
91 % \author{Robert J Lee \\ [email protected]}
92 %
93 % \maketitle
94 %
95 % \begin{abstract}
96 %
97 % This package provides macros and environments to allow the user to
98 % typeset a series of cross-referenced, numbered ``entries'',
99 % shuffled into random order.
100 %
101 % \end{abstract}
102 %
103 % \section{Introduction}
104 %
105 % This package was written to allow the typesetting of gamebooks.
106 %
107 % A gamebook is a book divided into ``entries'' (which may be a single
108 % paragraph or longer), each with a sequentially numbered value. At
109 % the end of each entry, a link to one or more other numbered
110 % entries is given; the reader selects one and they follow through
111 % the story in this order. Gamebooks traditionally start at the
112 % entry numbered~``1'' and some gamebooks have multiple endings,
113 % with the final section representing a success or victory for the
114 % reader.
115 %
116 % In particular, this package handles two technical challenges which
117 % are tricky to solve with \LaTeX\ directly: writing the ``entries''
118 % in order but presenting them in a randomised order; and presenting
119 % footnotes at the end of each ``entry'', numbered in the order in
120 % which they appear, not the order in which they are written.
121 %
122 % Aside from shuffling the paragraphs and fixing the handling of
123 % footnotes, this package provides little help for the actual
124 % typesetting of gamebook entries. For this, please consider using
125 % Andr\'e Miede's |gamebook| package, available on
126 % CTAN\footnote{\texttt{https://www.ctan.org/pkg/gamebook}}. That
127 % package is orthogonal to this one; both may be used together.
128 %
129 % \section*{Terminology}
130 %
131 % For the purposes of this document, the term \textit{entry} means a
132 % numbered section of text. This term helps describe the
133 % common format of a gamebook, while avoiding confusion with the terms
134 % \textit{paragraph} and a \textit{section}, both of which
135 % already have a clear definition.
136 %
137 % The term \textit{gamebook} means a book consisting of numbered
138 % sections, typically presented in a non-linear order with a
139 % tree or graph of possible reading options.
140 %
141 % \section*{Usage}
142 %
143 % To load the class, use |\usepackage[|\textit{options}|]{gamebook}|
144 %
145 % The class options are described below; |[footnotes,jukebox,mark]| is
146 % normally a good choice, although there are some limitations.
147 %
148 % The user simply writes entries like this inside the document:
149 % \begin{verbatim}
150 % \begin{gentry}{codea}
151 % This is the first entry
152 %
153 % Turn to \turnto{codeb}
154 % \end{gentry}
155 %
156 % \begin{gentry}[123]{codeb}[title]
157 % This is the second and final entry.\par
158 % To play again, turn to \turnto{codea}
159 % \end{gentry}
160 %
161 % % Output:
162 % \thegentries
163 % \end{verbatim}
164 %
165 % Here, two entries are defined, and then output.
166 %
167 % The first entry is given a label of |gentry:codea|, and the
168 % \cs{turnto\{codea\}} in the second entry generates a link back to
169 % that label. You might define \cs{turnto} like this:
170 %
171 % \begin{verbatim}
172 % \newcommand{\turnto}[1]{\ref{gentry:#1}}
173 % \end{verbatim}
174 %
175 %
176 % As |entry| is a common term likely to conflict with other
177 % environments, the environment to declare an entry has been named
178 % |gentry| (gamebook entry) instead.
179 %
180 % Sometimes it is convenient, when writing an entry, to give it a fixed
181 % index in the text. The first optional argument in the second entry
182 % --- |[123]| --- fixes the entry at that position during
183 % shuffling. This is implemented by iterating over each entry and
184 % swapping it with that index. Duplicates are not currently checked
185 % for, but they would not be lost; if two entries are defined with the
186 % same fixed index, one will end up somewhere else in the text.
187 %
188 % The first and last entries are automatically fixed without
189 % needing to specify the optional number.
190 %
191 % Specifying the optional number as a value greater than or equal to
192 % the number of entries, or less than~2, is not recommended. (Yes,
193 % this example used |123|, which is beyond the number of entries. This
194 % was done to show the syntax).
195 %
196 % The second optional argument is a title to be displayed alongside
197 % the numerical value.
198 %
199 % Finally, the command \cs{thegentries} will output all entries defined so
200 % far, handling shuffling and footnotes.
201 %
202 % \DescribeMacro{\gentryheader}\marg{counterIdx}\marg{fixedIdx}\marg{code}\marg{title}
203 %
204 % Users may also want to redefine \cs{gentryheader} to change how the
205 % entries are displayed. The initial version is quite basic and
206 % intended for debugging; users should use \cs{renewcommand} to change
207 % it to something more pleasant.
208 %
209 % Here's one suggestion, using packages from CTAN. It works well if you have either a
210 % title, or at least 2 lines of text before the first paragraph break
211 % inside the |gentry|.
212 %
213 %
214 % It also requires near the start of the document:
215 % \begin{verbatim}
216 % \usepackage{lettrine}
217 % \usepackage{etoolbox}
218 % \usepackage{color}
219 % \end{verbatim}
220 % And this anywhere before \cs{thegentries}:
221 % \begin{verbatim}
222 % \renewcommand{\LettrineFontHook}{%
223 % \color[gray]{0.5}\fontfamily{ppl}\fontseries{bx}}
224 % \renewcommand{\gentryheader}[4]{%
225 % % \typeout{Typesetting entry at original index #1}
226 % \lettrine[lines=3,lhang=0.2,loversize=0.2]{\raisebox{0.1em}{\arabic{gentryctr}}}%
227 % {\textbf{\Large\textbf{\raisebox{0.3em}{~#4}%
228 % }}}%
229 % \ifstrempty{#1}{}{\linebreak\mbox{}~}}%
230 % \end{verbatim}
231 % On the last line, \cs{mbox} stops the \cs{parindent} space being
232 % ignored; the $\sim$ brings it back up to the expected spacing.
233 % You may need to adjust the |lettrine| spacing parameters, depending on the font size
234 % and whether you use header text.
235 %
236 % \section*{Package options}
237 % \newcommand{\popt}[1]{\marginpar{\hfill |#1|}\index{#1 (option)}}
238 %
239 % These options can be specified as a comma-separated list to the
240 % \cs{usepackage} line.
241 %
242 % \popt{footnote}
243 % \changes{v1.0}{2021/08/10}{Footnote option}
244 % The |footnote| option causes \LaTeX\ to output footnotes at the end
245 % of each entry, or the end of each page, whichever comes first after
246 % the footnote mark.
247 %
248 % There are some limitations, described below.
249 %
250 % Support for other packages that affect footnotes is limited. If
251 % using |hyperref|, it is recommended to pass |[hyperfootnotes=false]|
252 % to avoid broken links.
253 %
254 %
255 % \popt{jukebox}
256 % \changes{v1.3}{2022/05/26}{Feature: "jukebox" shuffle}
257 % Use the Jukebox Index shuffling
258 % algorithm\footnote{\texttt{https://github.com/robertjlee/jukeboxshuffle}}.
259 % This is slightly slower, but tends to reduce the number of times you
260 % get a ``turn to~'' instrution referencing the next (or previous)
261 % entry in the original order, by modifying the shuffle to ensure that
262 % adjacent gentries in the input have much less chance of being
263 % adjacent in the final document. |jukebox| requires a \LaTeXe\ that
264 % supports \cs{numexpr}, and a minimum of 6 gentries. If fewer than
265 % 6~|gentry| environments are supplied before \cs{thegentries}, this
266 % option will only log a warning in verbose mode.
267 %
268 % The |jukebox| option guarantees no more adjacent entries than
269 % without the option, for a given |seed| value; it may not eliminate
270 % them completely unless the number of entries is large. The
271 % performance is linear to the number of entries.
272 %
273 % \popt{noshuffle}
274 % \changes{v1.0}{2021/08/10}{Noshuffle option}
275 % In general, it's easier to write gamebooks in a more linear fashion,
276 % in which related entries are kept together. But this is much less
277 % fun to play, as it's too easy for the reader to simply read the
278 % adjacent eentries to decide what to do.
279 % For this reason, this package shuffles the output entries by
280 % default. The first and last entries are never shuffled.
281 %
282 % Sometimes, perhaps for proofreading, you may not want the entries
283 % to be shuffled. In this case, you can use the |noshuffle| option.
284 %
285 % \popt{verbose}
286 % \changes{v1.0}{2021/08/10}{Verbose option}
287 % This macro causes the package to output information messages about
288 % what it's doing to the log file. This is not generally too useful, but it does
289 % include a mapping of the original paragraph indexes to their sorted
290 % positons, which may be useful to keep for handling proofreading
291 % corrections.
292 %
293 % \popt{endpage}
294 % \changes{v1.0}{2021/08/10}{Endpage option}
295 % Puts the last entry on a page on its own. This typically produces a
296 % better ``winning'' feel for reaching the last entry, but it can also
297 % produce documents with ugly spacing, so it's recommended to try it
298 % each way and see which works better for your text.
299 %
300 % \popt{seed}
301 % It's suggested that users specify a value for ``seed'' for stable
302 % builds, by adding the following before including this package:
303 % |\usepackage[seed=123]{lcg}|
304 %
305 % \section*{Footnotes}
306 %
307 % When typesetting a gamebook with footnotes, it is confusing if they
308 % migrate to the bottom of each page, as the footnote becomes visually
309 % detached from the entry to which it relates. Some effort has been taken to
310 % ensure that footnotes can be typeset at the bottom of the page on which
311 % the mark appears, or the bottom of each entry, whichever comes
312 % first.
313 %
314 % However, this implementation has some limitations:
315 %
316 % \begin{itemize}
317 % \item Footnotes are not expanded until they are typeset.
318 % \item As a consequence, attaching one footnote to another with the
319 % use of \cs{footnotemark} within a \cs{footnote} argument will not
320 % advance the counter in time, so \cs{footnotetext} may not behave as
321 % you expect unless it is also set inside the first footnote's text.
322 % \item Footnotes at the end of the page will not be broken across
323 % pages. Putting sufficient text into footnotes will cause the page
324 % to overflow.
325 % \item Where the footnote \textbf{mark} appears at the very end of a page,
326 % the footnote \textbf{text} may be set at the top of the subsequent
327 % page. \TeX\ is asked not to break the page there, but this influence
328 % is limited. It may be possible for the author to avoid this, eg by
329 % adding a rubber length to the interline spacing (it may be easier to
330 % simply choose a different |seed| value for the |lcg| package to
331 % reshuffle).
332 % \item If you have a lot of rubber space in the text, or
333 % variably-sized items, \LaTeX\ may expand the footnote at the end of
334 % the entry before it works out where to put the page break. In this
335 % case, the footnote will appear on the wrong page. The macro
336 % \cs{noentryfoot} is provided to allow the author to fix this case.
337 % \item Support for other footnotes packages may be limited and the
338 % behaviour of packages like |footnote|, |endnotes|, |footmisx|,
339 % |fnote|, |dblfnote| \textit{etc} may be affected.
340 % \item If using the |hyperref| package, it is recommended to pass the
341 % option |hyperfootnotes=false| to that package, as the footnote links
342 % will be incorrect.
343 % \item The package uses \TeX\ \cs{mark}s to indicate which footnotes
344 % should appear on each page. Because \TeX\ supports only one set of
345 % marks, this would break any other package or usage of \cs{mark}
346 % while a gamebook was being output.
347 % \item Because \cs{mark} does not escape a floating environment, such
348 % as |minipage|, it is likely that this footnote implementation will
349 % not work as expected if the gamebook or \cs{footnote} is set in a |minipage| or
350 % similar.
351 % \item Each footnote is evaluated in a group. Just conceivably, this
352 % might affect the behaviour of some macros that affect the document
353 % beyond the footnote.
354 % \item We rely on some non-``public'' macros, such as \cs{@mpfn} and
355 % \cs{@footnotetext} defined by \LaTeX\ standard document
356 % classes. Other document classes may override these, which would
357 % override this package's footnotes too.
358 % \end{itemize}
359 %
360 % For this reason, the improved footnote handling is only enabled if
361 % you pass the |footnote| option, and only while the environment is
362 % active.
363 %
364 % \section*{Implementation}
365 %\StopEventually{\PrintChanges \pagebreak[4] \PrintIndex}
366 %
367 % \begin{macrocode}
368 \ProvidesPackage{gamebooklib}[2023/07/28 Gamebook by R Lee [email protected]]
369 % \end{macrocode}
370 % We need \LaTeXe, for the extra token registers.
371 % \begin{macrocode}
372 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
373 % \end{macrocode}
374 % \popt{verbose}
375 % The package option |verbose| enables detailed logging.
376 % Logging is via the macro \cs{gamebook@info}, which throws away detail messages
377 % unless the |verbose| option is given.
378 % \begin{macrocode}
379 \newcommand{\gamebook@info}[1]{}%
380 \DeclareOption{verbose}{%
381 \renewcommand{\gamebook@info}[1]{\PackageInfo{gamebooklib}{#1}}%
382 \gamebook@info{Gamebook Library package is logging}}%
383 % \end{macrocode}
384 %
385 %% RL: Untested start of mark support
386 %% % \popt{mark}
387 %% % The |mark| package option enables support for \LaTeXe Mark
388 %% % interface, intruduced in 2022. This enables |gamebooklib| to declare
389 %% % its own \cs{mark} class, ensuring that other packages' marks are
390 %% % unaffected.
391 % \begin{macrocode}
392 %% \newcommand{\gamebooklibmarkclass}{gamebooklibmark}
393 \def\gamebooklib@mark{\mark}
394 %% \DeclareOption{mark}{%
395 %% \gamebook@info{Using mark class \gamebooklibmarkclass}%
396 %% \NewMarkClass{\gamebooklibmarkclass}%
397 %% \renewcommand{\gamebooklib@mark}[1]{\InsertMark{\gamebooklibmarkclass}{#1}}%
398 %% }%
399 % \end{macrocode}
400 %
401 % \popt{endpage}
402 % The |endpage| option puts the last entry on its own page. This can
403 % work better when the last entry is about a page long, and also
404 % the final ``winning'' entry of the gamebook.
405 % \begin{macrocode}
406 \newcommand\gamebook@beforelast{}
407 \DeclareOption{endpage}{%
408 \renewcommand\gamebook@beforelast{\eject}%
409 }%
410 % \end{macrocode}
411 %
412 % \popt{jukebox}
413 % The |jukebox| option defines the \cs{gamebox@jukebox} macro;
414 % while the macro does nothing, \cs{ifcsname} can then be used to
415 % determine if the option was set.
416 % \begin{macrocode}
417 \DeclareOption{jukebox}{%
418 \newcommand\gamebook@jukebox{}%
419 \gamebook@info{Gamebook Library to perform jukebox index reshuffle
420 pass}%
421 }%
422 % \end{macrocode}
423 %
424 % \popt{footnote}
425 % The |footnote| option enables our footnote processing, to throw out
426 % footnotes at the end of each |gentry| so that they don't appear to be
427 % against subsequent entries for that page.
428 %
429 % This is genearlly recommended, unless you have a reason to turn it
430 % off (such as a conflicting package). It's disabled by default
431 % because it could cause unexpected faults.
432 % \begin{macrocode}
433 \def\if@gamebook@footnotes{\iffalse}
434 \DeclareOption{footnote}{%
435 \gdef\if@gamebook@footnotes{\iftrue}%
436 \gamebook@info{Gamebook Library footnotes per gamebook entry}%
437 }%
438 % \end{macrocode}
439 %
440 % \popt{noshuffle}
441 % \begin{macrocode}
442 \def\if@gamebook@shuffle{\iftrue}
443 \DeclareOption{noshuffle}{%
444 \gdef\if@gamebook@shuffle{\iffalse}%
445 \gamebook@info{Gamebook Library entries output in order}%
446 }%
447 % \end{macrocode}
448 %
449 % \popt{seed}
450 % All unknown options are passed to |lcg|, as it's our only dependency with options.
451 % \begin{macrocode}
452 \DeclareOption*{%
453 \PassOptionsToClass{\CurrentOption}{lcg}%
454 }%
455 \ProcessOptions\relax%
456 % \end{macrocode}
457 % We need to capture environment contents
458 % \begin{macrocode}
459 \RequirePackage{environ}%
460 % \end{macrocode}
461 % |Macroswap|: used to swap the commands that evaluate the macros
462 % \begin{macrocode}
463 \RequirePackage{macroswap}%
464 % \end{macrocode}
465 % |Ifthen| makes branching and loops a little easier
466 % \begin{macrocode}
467 \RequirePackage{ifthen}
468 % \end{macrocode}
469 % |LCG|: random numbers for the shuffle
470 % \begin{macrocode}
471 \RequirePackage{lcg}%
472 % \end{macrocode}
473 % |Silence| is used to suppress a warning from~|lcg| that gamebook is
474 % \textbf{not} wasting counter registers. |debrief| ensures that the
475 % user is at least told than warnings were suppressed.
476 %
477 % To see the warnings, put the following line before
478 % |\usepackage{gamebook}|:
479 %
480 % |\usepackage[debrief,showwarnings]{silence}|:
481 % \begin{macrocode}
482 \RequirePackage[debrief]{silence}%
483 % \end{macrocode}
484 %
485 % Let's count the entries we're reading in so we can build up token
486 % registers.
487 % \begin{macrocode}
488 \newcounter{gentryctr}%
489 \setcounter{gentryctr}{0}%
490 % \end{macrocode}
491 %
492 % \begin{environment}{gentry}\oarg{fixedIdx}\marg{code}\oarg{title}
493 % First, we need to parse the optional arguments.
494 %
495 % When we say \cs{begin}\{gentry\}, \LaTeX\ does some stuff ending in \cs{gentry}
496 % so we redefine \cs{gentry} to take an optional argument and delegate to \cs{@gentry}
497 % \begin{macrocode}
498 \newcommand{\gentry}[1][]{\@gentry{#1}}%
499 % \end{macrocode}
500 % \cs{gentry} just makes the first argument mandatory.
501 %
502 % NB: If you define two entries with the same code, \LaTeX\ will print
503 % out a "multiply defined" label warning.
504 % \begin{macrocode}
505 \newenvironment{@gentry}[2]{%
506 \xdef\gentryidx{#1}%
507 \xdef\gentrycode{#2}%
508 \@@gentry%
509 }{\ignorespacesandallpars%
510 \global\let\gentryidx\@undefined%
511 \global\let\gentrycode\@undefined%
512 \global\let\gentryidxu\@undefined%
513 \global\let\gentryidxs\@undefined%
514 }%
515 % \end{macrocode}
516 % \begin{macro}{gentryidx}
517 % This can be used inside a |gentry|; it expands to the first optional
518 % argument of the |gentry| environment, which is either blank or the
519 % requested fixed index of the entry.
520 % To get the actual shuffled index, use \cs{gentryidxu}.
521 % \end{macro}
522 %
523 % \begin{macro}{gentrycode}
524 % This can be used inside a |gentry|; it expands to the first mandatory
525 % argument of the |gentry| environment, which is the code for this
526 % entry (without the |gentry:| prefix).
527 % \end{macro}
528 %
529 % \cs{@@gentry} then reads in the optional title argument, storing it in the \cs{gentrytitle}
530 % macro to supply the unsorted index number and the current entry's code respectively.
531 % \begin{macrocode}
532 \newcommand{\@@gentry}[1][]{%
533 \def\gentrytitle{#1}%
534 \stepcounter{gentryctr}%
535 % \end{macrocode}
536 % For fixed entries, define a macro to hold the requested index
537 % \begin{macrocode}
538 \ifthenelse{\equal{\gentryidx}{}}{}{%
539 \expandafter\xdef\csname fixedat\arabic{gentryctr}%
540 \endcsname{\gentryidx}%
541 }%
542 \expandafter\global\expandafter\newtoks\expandafter{%
543 \csname paratok\arabic{gentryctr}\endcsname}{ }%
544 \Collect@Body\gentry@store%
545 % \end{macrocode}
546 % This was supposed to discard any blank lines at the end of the
547 % |gentry| environment, but it still left odd spacing in the
548 % output somehow, and sometimes produced weird error messages about
549 % |\inaccessible| and |\head|. Removed for now.
550 % \begin{macrocode}
551 % \ignorespacesandallpars%
552 }
553 % \end{macrocode}
554 % Store the collected environment contents for \cs{thegentries} to output:
555 % This uses the token register \cs{gentry$N$}, where $N$ is the
556 % unsorted index of this entry.
557 % Later, we'll change the values of the $N$ bit of \cs{gentry$N$}
558 % macros when we shuffle (the underlying token registers stay the same).
559 %
560 % This relies on \cs{refstepcounter}\marg{gentryctr} being expanded
561 % before this macro. The label |gentry:\gentrycode| is thus set to the
562 % current index of the final output entry.
563 % \begin{macrocode}
564 \newcommand{\gentry@store}[1]{%
565 \edef\head{\noexpand\begingroup\noexpand\gentryheader%
566 {\arabic{gentryctr}}{\gentryidx}{\gentrycode}{\gentrytitle}%
567 \noexpand\label{gentry:\gentrycode}%
568 }%
569 \global\expandafter\csname paratok\arabic{gentryctr}\endcsname=%
570 % \end{macrocode}
571 % Output the header, the environment token list, flush any footnotes (if applicable) then the inter-gentry footer.
572 % \begin{macrocode}
573 \expandafter{\head #1%
574 \outputfootnotes@endgentry%
575 \gentryfooter\endgroup}%
576 }%
577 % \end{macrocode}
578 % \end{environment}
579 %
580 % \DescribeMacro{\gentry@footnotespergentry}
581 % This macro is executed inside the |gentry| group and sets up the
582 % commands to be run to allow footnotes. It is only expanded if
583 % \cs{if@gamebook@footnotes} is true, \textit{ie} the |footnotes|
584 % option is given.
585 % \begin{macrocode}
586 \newcommand{\gentry@footnotespergentry}{}
587 % \end{macrocode}
588 %
589 % \DescribeMacro{\thegentries}
590 %
591 % This macro shuffles the entries as required, then expands to them in
592 % the correct order.
593 % \begin{macrocode}
594 \newcommand{\thegentries}{%
595 % \end{macrocode}
596 % This command is in a group so that the output routine resets.
597 %
598 % The expansion of \cs{gentry@footnotespergentry} only happens if the
599 % |footnote| option was given; it sets up the output routine while the
600 % gamebook is running.
601 % \begin{macrocode}
602 \begingroup%
603 \if@gamebook@footnotes\gentry@footnotespergentry\fi%
604 % \end{macrocode}
605 % To begin, let's record the number of entries. This may come in
606 % useful. Note that you can use this macro in the |gentry| environment,
607 % because that's not been expanded yet.
608 % \begin{macrocode}
609 \xdef\gentrycount{\arabic{gentryctr}}%
610 % \end{macrocode}
611 %
612 % The next thing is to perform some surgery on LCG.
613 % This cuts out an \textbf{annoying} warning, hopefully more reliably
614 % than replacing the definition of \cs{p@stkeysr@nd}.
615 % The warning is simply that this package doesn't waste another
616 % counter every time it changes the random limits (which happens a lot
617 % during the Fisher-Yates shuffle):
618 % \begin{macrocode}
619 \WarningFilter{lcg}{Using an already existing counter rand}%
620 % \end{macrocode}
621 %
622 % \subsection*{The output routine and end-of-page footnotes}
623 % The idea is to keep footnotes always on the same page as their mark where possible.
624 %
625 % \LaTeX\ does lots of fun things with the output routine, which we
626 % want to keep. So grab a copy of whatever the code is currently doing:
627 %
628 % Here I'm using the \cs{edef} trick to expand \cs{the}\cs{output} into a token register, because using a macro
629 % causes a weird error about an ``|{|'' after ``\cs{the}''.
630 % \begin{macrocode}
631 \newtoks\gentry@oldoutput{}%
632 \edef\mytmp@{\noexpand\gentry@oldoutput={\the\output}}\mytmp@%
633 % \end{macrocode}
634 % For the footnotes, if we reach the end of a page without outputting
635 % them, we need to flush them.
636 %
637 % \cs{output} is the output routine. It takes the page built up in
638 % \cs{box255}, annotates it with headers, footers etc, then ships it
639 % out. For our purposes, we only need to append the footnotes to the
640 % bottom of \cs{box255}.
641 % \begin{macrocode}
642 \if@gamebook@footnotes\output={%
643 \def\gentry@deferoutput{\the\gentry@oldoutput}%
644 % \end{macrocode}
645 % The \cs{outputpenalty} tells us why the output routine was called; generally, it's invoked whenever
646 % a new floatable environment is generated, or when a page is full. Anything less than -1000 means that
647 % the page was filled, so we should add any footnotes only in this case.
648 % \begin{macrocode}
649 \ifnum\outputpenalty<-\@M\else%
650 \if\gentryshouldoutput0%
651 \unvbox255\def\gentry@deferoutput{}%
652 \else%
653 \expandafter\ifcsname footnotetoks\botmark\endcsname%
654 \expandafter\if\expandafter\relax\expandafter%
655 \detokenize\expandafter{\csname footnotetoks\botmark\endcsname}\relax\else%
656 \global\setbox255=\vbox to \vsize{%
657 \unvbox255\vfill\outputfootnotes@endpage}%
658 \fi\fi%
659 \fi\fi%
660 \gentry@deferoutput%
661 % \the\gentry@oldoutput
662 }\fi%
663 % \end{macrocode}
664 %
665 %
666 % \subsection*{The Shuffling Algorithm}
667 %
668 % The basic shuffling algorithm is to first shuffle all entries,
669 % except for those marked with a fixed index, then to go through the
670 % fixed-index entries in order and swap them into their final place.
671 %
672 % The original version of this package had a bug relating to multiple
673 % fixed-index entries (now fixed).
674 % In short, let $A$, $B$, and $C$ be indices; if $A<B$ and
675 % (unshuffled) entry number $A$ was fixed at (shuffled)
676 % location $B$, while (unshuffled) entry number $B$ was fixed at
677 % (shuffled) location $C$, so during the ``shuffle,'' $A$ would be
678 % swapped with $B$, then $B$ would be swapped with $C$, resulting in
679 % $A$ appearing at $C$ in the text, not $B$ as requested. Because the
680 % unshuffled index doesn't appear in either the source or output
681 % document, this could be difficult to diagnose; the author simply saw
682 % one of their entries ending up in the wrong place.
683 %
684 % \TeX\ has well beyond 255 token registers these days, so don't
685 % bother to check that limit.
686 %
687 % The |LCG| package provides a suitable pseudo-random number generator.
688 % What we want is a repeatable series of disparate numbers, not an
689 % especially random one.
690 %
691 %\begin{enumerate}
692 % \item Work out how many entries there are~($N$). Provided \cs{thegentries} is
693 % called at the end, this is just the value of |gentryctr|
694 % \item Declare a set of token registers named \cs{paratoks}$n$, where $n$ is
695 % each integer 1\dots$N$ inclusive. These will hold the contents of the entry.
696 % \item Declare a set of macros named \cs{paraidx}$n$, where $n$ is
697 % each integer 1\dots$N$ inclusive, each initialised to $n$. These will hold the number of the entry.
698 % \item Shuffle elements $\{2:N-1\}$, in that array. For $i=2$ through $N-2$
699 % \begin{enumerate}
700 % \item Let $R$ be a random number between $i$ and $N-1$ inclusive
701 % \item If $R\ne i$ then swap macros \cs{gentrytoks}$R$ and \cs{gentrytoks}$i$
702 % \item If $R\ne i$ then swap macros \cs{paraIdx}$R$ and \cs{gentryidx}$i$
703 % \end{enumerate}
704 % \item If a jukebox index sort is requested, perform an optimisation
705 % pass (see below)
706 % \item For $i=1:n$, output token reg $i$
707 %\end{enumerate}
708 %
709 % Define macros \cs{csname}~|paraIdx|$n$\cs{endcsname} containing the arabic
710 % original gentry number to be put out on the $n$th output gentry.
711 % \begin{macro}{gentrycount}
712 % \begin{macrocode}
713 \xdef\gentrycount{\arabic{gentryctr}}%
714 % \end{macrocode}
715 % \end{macro}
716 % we can reuse |gentryctr|; we've finished this set of paras and
717 % kept the total count.
718 % \begin{macrocode}
719 \setcounter{gentryctr}{0}%
720 % \end{macrocode}
721 % If there are fewer than 3 entries, don't try and shuffle.
722 % \begin{macrocode}
723 \ifthenelse{\gentrycount<3}{}{%SHUFFLE START
724 \whiledo{\not{\value{gentryctr}>\gentrycount}}{%
725 \edef\gentryidxu{\arabic{gentryctr}}%
726 \expandafter\xdef\csname paraIdx\gentryidxu\endcsname{\gentryidxu}%
727 \typeout{DEFINED paraIdx\gentryidxu}%
728 \stepcounter{gentryctr}%
729 }%
730 % \end{macrocode}
731 % \begin{macro}{gentryidxu}
732 % \changes{v1.1}{2021/08/24}{Access shuffled index}
733 % The \cs{gentryidxu} macro can be used inside a |gentry| to obtain the
734 % current arabic shuffled index of the entry.
735 % \end{macro}
736 % \begin{macro}{gentryidxs}
737 % \changes{v1.1}{2021/08/24}{Access original index}
738 % The \cs{gentryidxs} macro can be used inside a |gentry| to obtain the
739 % arabic original unshuffled index of the entry (the first |gentry| is
740 % 1, and this counter resets after each expansion of \cs{thegentries}).
741 % \end{macro}
742 % \begin{macrocode}
743 \if@gamebook@shuffle%
744 \setcounter{rand}{\gentrycount}%
745 \addtocounter{rand}{-1}\edef%
746 \stoppoint{\arabic{rand}}%
747 % \end{macrocode}
748 % First, shuffle everything that isn't fixed down.
749 % Don't renumber para~1 or \cs{gentrycount}; Fisher-Yates-shuffle the rest
750 % NB: we stop at \cs{gentrycount}$-2$, because \cs{gentrycount}$-1$ would only shuffle
751 % with itself.
752 % \begin{macrocode}
753 \setcounter{gentryctr}{2}%
754 \chgrand[last=\stoppoint]%
755 \whiledo{\value{gentryctr}<\stoppoint}{%
756 % \end{macrocode}
757 % If this is to be swapped with a fixed position, skip it
758 % \begin{macrocode}
759 \edef\gentryidxu{\arabic{gentryctr}}%
760 \expandafter\ifcsname fixedat\gentryidxu\endcsname%
761 \gamebook@info{Not shuffling \gentryidxu; fixed pos}%
762 \stepcounter{gentryctr}%
763 \else%
764 \gamebook@info{Shuffling \gentryidxu}%
765 \stepcounter{gentryctr}%
766 \edef\nextidx{\arabic{gentryctr}}%
767 % \end{macrocode}
768 % Roll the dice. If we've hit an entry with fixed position, we must
769 % skip it, or it would end up being swapped out into
770 % |fixedat\arabic{rand}| instead.
771 % \begin{macrocode}
772 \chgrand[first=\nextidx]%
773 \rand%
774 \expandafter\ifcsname fixedat\arabic{rand}\endcsname\else%
775 \gamebook@info{Shuffling \gentryidxu to \arabic{rand}}%
776 \macroswap{paraIdx\gentryidxu}{paraIdx\arabic{rand}}%
777 \fi%
778 \fi%
779 }%
780 % \end{macrocode}
781 % Now move fixed entries into their final place:
782 % \begin{macrocode}
783 \setcounter{gentryctr}{2}%
784 \whiledo{\not{\value{gentryctr}>\stoppoint}}{%
785 \edef\gentryidxu{\arabic{gentryctr}}%
786 \expandafter\ifcsname fixedat\gentryidxu\endcsname%
787 \expandafter\edef\expandafter\mydest\expandafter%
788 {\expandafter\csname fixedat\gentryidxu\endcsname}%
789 \gamebook@info{MOVING FIXED GAMEBOOK ENTRY INTO PLACE: \gentryidxu -> \mydest}%
790 \macroswap{paraIdx\gentryidxu}%
791 {paraIdx\expandafter\csname fixedat\gentryidxu\endcsname}%
792 % \end{macrocode}
793 % Edge case: It's possible that we also have |fixedat\mydest|; in which case that
794 % would be messed up with the reshuffling. So we need to rename that
795 % to |fixedat\gentryidxu| as well, then reprocess this index
796 % \begin{macrocode}
797 \expandafter\ifcsname fixedat\mydest\endcsname%
798 \macroswap{fixedat\gentryidxu}{fixedat\mydest}%
799 \expandafter\global\expandafter\let\csname fixedat\mydest\endcsname\@undefined%
800 \addtocounter{gentryctr}{-1}%
801 \fi%
802 % \end{macrocode}
803 % if we are doing a jukebox shuffle, remember which final entries are fixed, so
804 % they don't get moved.
805 % \begin{macrocode}
806 \ifcsname gamebook@jukebox\endcsname%
807 \expandafter\def\csname fixedto\mydest\endcsname{}%
808 \fi%
809 \fi%
810 \stepcounter{gentryctr}%
811 }%
812 % \end{macrocode}
813 % The jukebox shuffle requires an extra pass. This must come after
814 % moving fixed entries into their final place, to allow us to compare
815 % the initial indicies.
816 % We make a reasonable effort:\begin{itemize}
817 % \item $t$ is the current index
818 % \item $u$ is the next index
819 % \item $r$ is a random index after $u$ (make 3 attempts to find a
820 % non-fixed $r$)
821 % \item if abs$(t-u)=1$ and $r$ is not fixed, then swap $u$ and $r$
822 % \textbf{if} $u$ is not fixed; otherwise:
823 % \item if abs$(t-u)=1$ and $r$ is not fixed, then swap $t$ and $r$
824 % \textbf{if} $t$ is not fixed;
825 % \item otherwise, give up.
826 % \end{itemize}
827 % \begin{macrocode}
828 \ifcsname gamebook@jukebox\endcsname%
829 \ifnum\gentrycount<6%
830 \gamebook@info{Jukebox pass skipped; too few entries}%
831 \else%
832 \setcounter{gentryctr}{2}%
833 \whiledo{\not{\value{gentryctr}=\stoppoint}}{%
834 \edef\gentryidxt{\arabic{gentryctr}}%
835 \edef\curpos{\csname paraIdx\gentryidxt\endcsname}%
836 \stepcounter{gentryctr}%
837 \edef\gentryidxu{\arabic{gentryctr}}%
838 \edef\nextpos{\csname paraIdx\gentryidxu\endcsname}%
839 \edef\pdiff{\the\numexpr\curpos+\nextpos}%
840 \ifnum\pdiff<0\edef\pdiff{\the\numexpr-\pdiff}\fi%
841 \edef\sdiff{\the\numexpr\curpos-\nextpos}%
842 \ifnum\sdiff<0\edef\sdiff{\the\numexpr-\sdiff}\fi%
843 \ifnum\pdiff<\sdiff\relax\def\thediff{\pdiff}\else\def\thediff{\sdiff}\fi%
844 \ifnum\thediff=1%
845 \gamebook@info{Jukebox: entries are too close: %
846 \gentryidxt,\gentryidxu\space (original \curpos,\nextpos)}%
847 \chgrand[first=\numexpr\gentryidxu+1]%
848 \rand%
849 \expandafter\ifcsname fixedto\arabic{rand}\endcsname\rand\fi%
850 \expandafter\ifcsname fixedto\arabic{rand}\endcsname\rand\fi%
851 \expandafter\ifcsname fixedto\arabic{rand}\endcsname%
852 \gamebook@info{Can't reshuffle: failed to find non-fixed index}%
853 \else%
854 \ifcsname fixedto\gentryidxu\endcsname%
855 \ifcsname fixedto\gentryidxt\endcsname%
856 \gamebook@info{Can't reshuffle: \curpos\space and %
857 \nextpos\space are both fixed.}%
858 \else%
859 \gamebook@info{Reshuffling \gentryidxt\space to \arabic{rand}}%
860 \macroswap{paraIdx\gentryidxt}{paraIdx\arabic{rand}}%
861 \fi%
862 \else%
863 \gamebook@info{Reshuffling \gentryidxu\space to%
864 \arabic{rand} (alt)}%
865 \macroswap{paraIdx\gentryidxu}{paraIdx\arabic{rand}}%
866 \fi\fi\fi%
867 }%
868 \fi\fi%
869 }\fi%SHUFFLE END
870 % \end{macrocode}
871 % Now we can output the |gentry| token registers to let \LaTeX\ do its thing:
872 % \begin{macrocode}
873 \gamebook@info{Shuffled! Gentry order:}%
874 \setcounter{gentryctr}{1}%
875 \whiledo{\not{\value{gentryctr}>\gentrycount}}{%
876 \edef\gentryidxu{\arabic{gentryctr}}%
877 \gamebook@info{\gentryidxu -> \csname paraIdx\gentryidxu\endcsname}%
878 \stepcounter{gentryctr}%
879 }%
880 % \end{macrocode}
881 %
882 % We can reuse the same counter again to output
883 % \begin{macrocode}
884 \setcounter{gentryctr}{0}%
885 \gamebook@info{Outputting \gentrycount\space gamebook entries}%
886 \whiledo{\value{gentryctr}<\gentrycount}{%
887 % \end{macrocode}
888 % Use refstepcounter in the loop to allow \cs{label} to work as expected.
889 % \begin{macrocode}
890 \refstepcounter{gentryctr}%
891 % \end{macrocode}
892 % Keep last entry on its own page
893 % \begin{macrocode}
894 \ifthenelse{\value{gentryctr}=\gentrycount}{%
895 \gamebook@beforelast%
896 }{}%
897 \edef\gentryidxu{\arabic{gentryctr}}%
898 \xdef\gentryidxs{\csname paraIdx\gentryidxu\endcsname}%
899 \gamebook@info{Output gentry \gentryidxu\ of \gentrycount,%
900 original idx \gentryidxs}%
901 % \end{macrocode}
902 % Output the stored entry body, stripping any extraneous space:
903 % \begin{macrocode}
904 \the\csname paratok\gentryidxs\endcsname%
905 }%
906 % \end{macrocode}
907 % Finally, we clear the registers and reset the counter in case we want to start again
908 % (NB: |fixedto| is scope to the current block only, so no need to clear that)
909 % \begin{macrocode}
910 \gamebook@info{All gamebook entries added to main vertical list}%
911 \setcounter{gentryctr}{1}%
912 \whiledo{\not{\value{gentryctr}>\gentrycount}}{%
913 \edef\gentryidxu{\arabic{gentryctr}}%
914 \expandafter\global\expandafter\let%
915 \csname paratok\gentryidxu\endcsname\@undefined%
916 \expandafter\ifcsname fixedat\gentryidxu\endcsname%
917 \expandafter\global\expandafter\let%
918 \csname fixedat\gentryidxu\endcsname\@undefined%
919 \fi%
920 \stepcounter{gentryctr}%
921 }%
922 \setcounter{gentryctr}{0}%
923 \eject%
924 \endgroup%
925 }%
926 % \end{macrocode}
927 % The final \cs{eject} ensures that the output routine has flushed as
928 % many pages as it can, before the output routine is reset again.
929 %
930 % \DescribeMacro{\gentryheader}\marg{counterIdx}\marg{fixedIdx}\marg{code}\marg{title}
931 %
932 % This macro is called before outputting the header. Its
933 % job is to format whatever header information the user wants to see
934 % on each entry; generally, this will be the page number.
935 %
936 % It takes 4 parameters:
937 %\begin{enumerate}
938 %\item The \textit{unshuffled} index value (to help an author find an
939 % entry in the original text); this is numerically the same as |\gentryidxs|
940 %\item The \textit{fixed} index value, if any; otherwise an empty argument
941 %\item The user-entered unique code for this entry
942 %\item The user-supplied title, if any; otherwise an empty argument
943 %\end{enumerate}
944 %
945 % The arabic value of the output index can be obtained with |\gentryidxu|;
946 % the numeric value is also set in the counter |gentryctr|.
947 % \begin{macrocode}
948 \newcommand{\gentryheader}[4]{%
949 \noindent\textbf{\Huge\arabic{gentryctr}\large\ #4}%
950 \nopagebreak%
951 \vspace{0.3em}%
952 \nopagebreak%
953 \par%
954 \marginpar{#3}%
955 }%
956 % \end{macrocode}
957 %
958 % \begin{macro}{gentryshouldoutput}
959 % \changes{v1.3}{2022/05/26}{Suppress short pages option}
960 % This macro \textbf{may} be called from the output routine, and can
961 % be used to suppress page breaks. It was added because it proves
962 % fairly easy to write custom divider routines that can produce blank
963 % pages. If it expands to the number 1, then the page will be output;
964 % if it expands to 0, it will not be.
965 %
966 % For example, the following will prevent pages that are less than 80\% full.
967 %
968 % \verb!\renewcommand{\gentryshouldoutput}{%!
969 %
970 % \verb! \ifdim\pagetotal>0.8\pagegoal\relax1\else 0\fi}!
971 %
972 % \textbf{Caution:} if this macro continually tests false, then
973 % material will eventually be discarded from the main vertical list to
974 % ensure that \TeX\ can complete the output of the document. If you
975 % redefine this macro, make sure to check out output carefully for
976 % missing text.
977 % \begin{macrocode}
978 \newcommand{\gentryshouldoutput}{1}
979 % \end{macrocode}
980 % \end{macro}
981 %
982 % \begin{macro}{gentryfooter}
983 % This takes no arguments and is simply expanded after the entry is typeset. The default adds some vertical
984 % space and a simple separator.
985 %
986 % \begin{macrocode}
987 \newcommand{\gentryfooter}{%
988 \par\vspace{2em}\centerline{---}\vspace{2em plus 1in}\par%
989 }%
990 % \end{macrocode}
991 % \end{macro}
992 %
993 % \begin{macro}{ignorespacesandallpars@}
994 % This is a technique described on StackExchange\footnote{\small https://tex.stackexchange.com/questions/179016/\\\mbox{~}\hspace{1in}ignore-spaces-and-pars-after-an-environment\#179034}.
995 %
996 % This is used to ensure that extra space at the start and end of the |gentry|
997 % environment is ignored.
998 %
999 % \begin{macrocode}
1000 \def\ignorespacesandallpars@{%
1001 \@ifnextchar\par%
1002 {\expandafter\ignorespacesandallpars\@gobble}%
1003 {}%
1004 }%
1005 % \end{macrocode}
1006 % \end{macro}
1007 %
1008 % \DescribeMacro{\@footnotetext}\marg{token register}
1009 % Token registers to hold each footnote.
1010 %
1011 % Each footnote is held in its own token register, so that we can control
1012 % which footnotes appear on each page.
1013 %
1014 % \LaTeX\ would normally use saveboxes to store footnotes, but I
1015 % prefer to hold off on expanding them until we know which page
1016 % they're to be expanded on, which saves some difficulties (and
1017 % perhaps creates others).
1018 %
1019 % To start with, modify \LaTeX's \cs{@makefnmark} to output a mark for
1020 % the footnote, holding its index. This tells the output routine which
1021 % footnotes to include at the end of the page. The
1022 % \cs{in@out} macro is only defined when outputting footnotes, so
1023 % suppresses this mark when we don't need it.
1024 % \begin{macrocode}
1025 \g@addto@macro{\@makefnmark}{%
1026 \ifcsname in@out\endcsname\else%
1027 \gamebooklib@mark{\arabic{\@mpfn}}%
1028 \fi%
1029 }%
1030 % \end{macrocode}
1031 %
1032 % The \cs{footnotetext@save} is a convenience that takes the the
1033 % footnote counter value in the first argument, the token register as
1034 % a second argument, and the token list (footnote text) as the third.
1035 % \begin{macrocode}
1036 \g@addto@macro{\gentry@footnotespergentry}{%
1037 \newcommand{\@footnotetext@save}[3]{%
1038 \global\newtoks#2{}%
1039 \global#2={\noindent\@footnotemark{}#3}%
1040 }}%
1041 % \end{macrocode}
1042 % \cs{@footnotetext@save} unpacks the arguments for
1043 % \cs{@footnotetext@save@}. This one uses the value of the \cs{@mpfn}
1044 % counter to unpack the footnote counter, the token register (full csname) as
1045 % the first argument, and the token list (footnote text) as the second.
1046 % \begin{macrocode}
1047 \g@addto@macro{\gentry@footnotespergentry}{%
1048 \newcommand{\@footnotetext@save@}[2]{%
1049 \edef\@tmp@{\expandafter\arabic{\@mpfn}}%
1050 \expandafter\@footnotetext@save\expandafter{\@tmp@}{#1}{#2}%
1051 }}%
1052 % \end{macrocode}
1053 % Footnotes are built in a group, so that \cs{in@out} can be defined
1054 % locally to indicate that footnotes are being built (which stops
1055 % spurious \cs{mark}s).
1056 % \begin{macrocode}
1057 \g@addto@macro{\gentry@footnotespergentry}{%
1058 \renewcommand{\@footnotetext}[1]{%
1059 \begingroup%
1060 \def\in@out{}% flag that we're building footnotes
1061 \edef\@tmp{\expandafter\csname footnotetoks\arabic{\@mpfn}\endcsname}%
1062 \expandafter\@footnotetext@save@\expandafter{\@tmp}{%
1063 % This fixes up the use of \cs{footnotemark} within footnotes:
1064 #1}%
1065 \endgroup%
1066 }}%
1067 % \end{macrocode}
1068 %
1069 % \DescribeMacro{\outputfootnotes}\marg{maxIdx}
1070 %
1071 % Command to output the footnotes, which are just in \cs{footnotetoks$N$}
1072 % for now.
1073 %
1074 % An end user can call this at any point in the text to set out the footnotes.
1075 %
1076 % This macro takes one argument, being the maximum index of footnotes to output, inclusive.
1077 % Footnotes after this index will be excluded. If not provided, the
1078 % value provided by the counter \cs{@mfpn}, which is the default
1079 % \LaTeX\ counter, will be used.
1080 % \begin{macrocode}
1081 \newcounter{fncounter}%
1082 \newcommand{\outputfootnotes}[1]{%
1083 \begingroup%
1084 \def\in@out{}% flag that footnotes are outputting; suppresses marks
1085 \setcounter{fncounter}{1}%
1086 % \end{macrocode}
1087 % Called in vertical mode, and don't want to throw a page break.
1088 %
1089 % I'm not sure how \LaTeX\ renders the footnote rule exactly, so I'm just using my own.
1090 % \begin{macrocode}
1091 \def\footnote@rule{%
1092 % \end{macrocode}
1093 % The next line comes from the TUGboat suggestions, and protect against various user changes
1094 % \begin{macrocode}
1095 \leftskip=0pt\rightskip=0pt\interlinepenalty=1000%
1096 \penalty-1000%
1097 \vspace{1pt plus 2pt minus 0.5pt}%
1098 \hspace{-0.5in}\rule{1.5in}{0.4pt}\\%
1099 }%
1100 % \end{macrocode}
1101 % Invoke the output routine. This attempts to stop the output routine
1102 % being invoked while we're adding the footnote rule, which could
1103 % cause a blank footnote to appear.
1104 %
1105 % Instead, it means some footnotes could appear on the subsequent
1106 % page. To guard against this, footnotes are set into a \cs{vbox}
1107 % to prevent page breaking.
1108 %
1109 % The macro \cs{footnote@rule} is output before each footnote. The
1110 % first time, it outputs a divider rule; subsequently, it just throws
1111 % a new paragraph to keep footnotes on separate lines.
1112 %
1113 % The next line comess from the TUGboat suggestions, and protect against various user changes
1114 % \begin{macrocode}
1115 \outputpenalty=-\@MM\break%
1116 \vbox{%
1117 \whiledo{\not{\value{fncounter}>#1}}{%
1118 % \end{macrocode}
1119 % We are now looping over all possible entry numbers, in
1120 % order. Some will already have been output, but we check them all
1121 % anyway (it doesn't take much time).
1122 %
1123 % First, we check if the macro exists. If it does, it must contain the
1124 % value of the token register.
1125 %
1126 % Next, we make sure that the token register has contents.
1127 %
1128 % \begin{macrocode}
1129 \expandafter\ifcsname footnotetoks\arabic{fncounter}\endcsname%
1130 \edef\tmp@@{\csname footnotetoks\arabic{fncounter}\endcsname}%
1131 % \end{macrocode}
1132 % This \cs{detokenize} black magic tests if a token reg is actually
1133 % empty\footnote{\texttt{https://tex.stackexchange.com/questions/263733/\\\mbox{~}\hspace{1in}whats-the-best-practice-way-to-test-whether-parameter-is-empty}}
1134 % \begin{macrocode}
1135 \expandafter\if\expandafter\relax\expandafter%
1136 \detokenize\expandafter{\the\tmp@@}\relax\else%
1137 \footnote@rule\gdef\footnote@rule{\ifvmode\else\par\fi}%
1138 \interlinepenalty\interfootnotelinepenalty%
1139 % \end{macrocode}
1140 % Actually output the footnotes.
1141 %
1142 % Having output the footnote, clear the token register (to save
1143 % memory), then use \cs{let} to clear the definition of the
1144 % macro. This ensures that we don't try to output the same footnote
1145 % twice (at page end and entry end).
1146 % \begin{macrocode}
1147 \expandafter\the\tmp@@%
1148 \global\expandafter\tmp@@={}%
1149 \expandafter\let\tmp@@\@undefined%
1150 \fi\fi%
1151 \stepcounter{fncounter}%
1152 }%
1153 }%
1154 \endgroup%
1155 }%
1156 % \end{macrocode}
1157 % \LaTeX\ works by building up a little more than a page, then calling the output routine.
1158 % The output routine then decides where to put the page end from the built-up material.
1159 % If there is a footnote mark, it could come after the page end, so we can't rely on the
1160 % fact that there's footnote register to determine if we should output footnotes or not.
1161 % The edge case is: if the footnote mark is held back for the next page, the footnote text
1162 % would appear on the footer of the page where being built when the mark was expanded, which
1163 % is the page before the footnote.
1164 %
1165 % One fix for this is to have each footnote mark in the main body of
1166 % the text output a \cs{mark} containing the footnote's counter value,
1167 % and output the footnotes only to \cs{botmark}, which is the last
1168 % \cs{mark} actually typeset on the page.
1169 %
1170 % (see https://www.tug.org/TUGboat/Articles/tb11-4/tb30salomon.pdf,
1171 % page 598, to read around footnotes).
1172 %
1173 % \DescribeMacro{\outputfootnotes@endgentry}
1174 % This macro is called at the end of each |gentry|. It switches into
1175 % vertical mode (as ending |gentry| doesn't throw a \cs{break} or line
1176 % end by itself), then we output all footnotes so far (by reading the
1177 % footnote counter \cs{@mpfn}, as this is ``sequential'').
1178 % \begin{macrocode}
1179 \newcommand{\outputfootnotes@endgentry}{%
1180 \if@gamebook@footnotes%
1181 \nopagebreak\ifhmode\\\fi% get into vertical mode
1182 \nopagebreak\outputfootnotes{\arabic{\@mpfn}}%
1183 \fi%
1184 }%
1185 % \end{macrocode}
1186 % \DescribeMacro{\noentryfoot}
1187 % This method simply suppresses footnotes at the end of the entry
1188 % within the current group. This forces footnotes within the current
1189 % group to be printed at the bottom of the page.
1190 %
1191 % This is useful in the case where \LaTeX\ expands the footnote at the
1192 % end of the entry, then decides to put the page split between the
1193 % footnote mark and the text.
1194 % \begin{macrocode}
1195 \newcommand{\noentryfoot}{\def\outputfootnotes@endgentry{}}
1196 % \end{macrocode}
1197 % \DescribeMacro{\outputfootnotes@endpage}
1198 % This is called by the output routine at the end of each page. If
1199 % \cs{botmark} has a value, then we can output all footnotes up to
1200 % that index.
1201 % \begin{macrocode}
1202 \g@addto@macro{\gentry@footnotespergentry}{%
1203 \newcommand{\outputfootnotes@endpage}{%
1204 \expandafter\if\expandafter\relax\expandafter%
1205 \detokenize\expandafter{\botmark}\relax\else%
1206 \outputfootnotes{\botmark}%
1207 \fi%
1208 }}%
1209 % \end{macrocode}
1210 % \Finale
1211 \endinput