| 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 |