diff options
author | Norbert Preining <norbert@preining.info> | 2023-07-31 03:02:46 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-07-31 03:02:46 +0000 |
commit | 17d547a1effe2cafcdfbf704bdf8cb0484790ef2 (patch) | |
tree | 30556f1ebbb411da2d3e7297c0c4a2ffbd5af4ee /macros/latex/contrib/gamebooklib/gamebooklib.dtx | |
parent | 595d37aac232836c0519c45f2078c5272122eb32 (diff) |
CTAN sync 202307310302
Diffstat (limited to 'macros/latex/contrib/gamebooklib/gamebooklib.dtx')
-rw-r--r-- | macros/latex/contrib/gamebooklib/gamebooklib.dtx | 103 |
1 files changed, 61 insertions, 42 deletions
diff --git a/macros/latex/contrib/gamebooklib/gamebooklib.dtx b/macros/latex/contrib/gamebooklib/gamebooklib.dtx index deef74af4d..c8ec2742aa 100644 --- a/macros/latex/contrib/gamebooklib/gamebooklib.dtx +++ b/macros/latex/contrib/gamebooklib/gamebooklib.dtx @@ -17,7 +17,7 @@ % \iffalse % <package>\NeedsTeXFormat{LaTeX2e}[2005/12/01] % <package>\ProvidesPackage{gamebooklib} -% <package> [2022/05/26 v1.3 gamebooklib typesetting] +% <package> [2023/07/28 v1.4 gamebooklib typesetting] % %<*driver> \documentclass{ltxdoc} @@ -51,11 +51,12 @@ % Grave accent \` Left brace \{ Vertical bar \| % Right brace \} Tilde \~} % -% \CheckSum{708} +% \CheckSum{722} % % \changes{v1.0}{2021/08/10}{Initial Release} % \changes{v1.1}{2021/08/24}{Bugfix: edge case with clashing fixed-index entries} % \changes{v1.2}{2021/09/11}{Bugfix: footnotes set justified on last line} +% \changes{v1.4}{2022/07/28}{Improved documentation} % % \GetFileInfo{gamebooklib.sty} % @@ -95,7 +96,7 @@ % % This package provides macros and environments to allow the user to % typeset a series of cross-referenced, numbered ``entries'', -% shuffled into random order +% shuffled into random order. % % \end{abstract} % @@ -141,7 +142,7 @@ % % To load the class, use |\usepackage[|\textit{options}|]{gamebook}| % -% The class options are described below; |[footnotes,jukebox]| is +% The class options are described below; |[footnotes,jukebox,mark]| is % normally a good choice, although there are some limitations. % % The user simply writes entries like this inside the document: @@ -165,7 +166,12 @@ % % The first entry is given a label of |gentry:codea|, and the % \cs{turnto\{codea\}} in the second entry generates a link back to -% that label. +% that label. You might define \cs{turnto} like this: +% +% \begin{verbatim} +% \newcommand{\turnto}[1]{\ref{gentry:#1}} +% \end{verbatim} +% % % As |entry| is a common term likely to conflict with other % environments, the environment to declare an entry has been named @@ -215,21 +221,25 @@ % \begin{verbatim} % \renewcommand{\LettrineFontHook}{% % \color[gray]{0.5}\fontfamily{ppl}\fontseries{bx}} -% \renewcommand{\gentryheader}[4]{ -% \lettrine[lines=3,lhang=0.2,loversize=0.2]{\raisebox{0.1em}{#1}}% -% {\textbf{\Large\textbf{\raisebox{0.3em}{~#4} +% \renewcommand{\gentryheader}[4]{% +% % \typeout{Typesetting entry at original index #1} +% \lettrine[lines=3,lhang=0.2,loversize=0.2]{\raisebox{0.1em}{\arabic{gentryctr}}}% +% {\textbf{\Large\textbf{\raisebox{0.3em}{~#4}% % }}}% -% \ifstrempty{#1}{}{\linebreak\mbox{}~}} +% \ifstrempty{#1}{}{\linebreak\mbox{}~}}% % \end{verbatim} % On the last line, \cs{mbox} stops the \cs{parindent} space being % ignored; the $\sim$ brings it back up to the expected spacing. +% You may need to adjust the |lettrine| spacing parameters, depending on the font size +% and whether you use header text. % % \section*{Package options} +% \newcommand{\popt}[1]{\marginpar{\hfill |#1|}\index{#1 (option)}} % % These options can be specified as a comma-separated list to the % \cs{usepackage} line. % -% \begin{macro}{footnote} +% \popt{footnote} % \changes{v1.0}{2021/08/10}{Footnote option} % The |footnote| option causes \LaTeX\ to output footnotes at the end % of each entry, or the end of each page, whichever comes first after @@ -240,10 +250,9 @@ % Support for other packages that affect footnotes is limited. If % using |hyperref|, it is recommended to pass |[hyperfootnotes=false]| % to avoid broken links. -% \end{macro} % % -% \begin{macro}{jukebox} +% \popt{jukebox} % \changes{v1.3}{2022/05/26}{Feature: "jukebox" shuffle} % Use the Jukebox Index shuffling % algorithm\footnote{\texttt{https://github.com/robertjlee/jukeboxshuffle}}. @@ -251,7 +260,7 @@ % get a ``turn to~'' instrution referencing the next (or previous) % entry in the original order, by modifying the shuffle to ensure that % adjacent gentries in the input have much less chance of being -% adjacent in the final document. |jukebox| requires a \LaTeXe that +% adjacent in the final document. |jukebox| requires a \LaTeXe\ that % supports \cs{numexpr}, and a minimum of 6 gentries. If fewer than % 6~|gentry| environments are supplied before \cs{thegentries}, this % option will only log a warning in verbose mode. @@ -260,9 +269,8 @@ % without the option, for a given |seed| value; it may not eliminate % them completely unless the number of entries is large. The % performance is linear to the number of entries. -% \end{macro} % -% \begin{macro}{noshuffle} +% \popt{noshuffle} % \changes{v1.0}{2021/08/10}{Noshuffle option} % In general, it's easier to write gamebooks in a more linear fashion, % in which related entries are kept together. But this is much less @@ -273,30 +281,27 @@ % % Sometimes, perhaps for proofreading, you may not want the entries % to be shuffled. In this case, you can use the |noshuffle| option. -% \end{macro} % -% \begin{macro}{verbose} +% \popt{verbose} % \changes{v1.0}{2021/08/10}{Verbose option} % This macro causes the package to output information messages about % what it's doing to the log file. This is not generally too useful, but it does % include a mapping of the original paragraph indexes to their sorted % positons, which may be useful to keep for handling proofreading % corrections. -% \end{macro} % -% \begin{macro}{endpage} +% \popt{endpage} % \changes{v1.0}{2021/08/10}{Endpage option} % Puts the last entry on a page on its own. This typically produces a % better ``winning'' feel for reaching the last entry, but it can also % produce documents with ugly spacing, so it's recommended to try it % each way and see which works better for your text. -% \end{macro} % -% \begin{macro}{seed} +% \popt{seed} % It's suggested that users specify a value for ``seed'' for stable % builds, by adding the following before including this package: % |\usepackage[seed=123]{lcg}| -% \end{macro} +% % \section*{Footnotes} % % When typesetting a gamebook with footnotes, it is confusing if they @@ -360,13 +365,13 @@ %\StopEventually{\PrintChanges \pagebreak[4] \PrintIndex} % % \begin{macrocode} -\ProvidesPackage{gamebooklib}[2022/05/25 Gamebook by R Lee latex@rjlee.homelinux.org] +\ProvidesPackage{gamebooklib}[2023/07/28 Gamebook by R Lee latex@rjlee.homelinux.org] % \end{macrocode} % We need \LaTeXe, for the extra token registers. % \begin{macrocode} \NeedsTeXFormat{LaTeX2e}[1994/06/01] % \end{macrocode} -% \begin{macro}{verbose} +% \popt{verbose} % The package option |verbose| enables detailed logging. % Logging is via the macro \cs{gamebook@info}, which throws away detail messages % unless the |verbose| option is given. @@ -376,9 +381,24 @@ \renewcommand{\gamebook@info}[1]{\PackageInfo{gamebooklib}{#1}}% \gamebook@info{Gamebook Library package is logging}}% % \end{macrocode} -% \end{macro} % -% \begin{macro}{endpage} +%% RL: Untested start of mark support +%% % \popt{mark} +%% % The |mark| package option enables support for \LaTeXe Mark +%% % interface, intruduced in 2022. This enables |gamebooklib| to declare +%% % its own \cs{mark} class, ensuring that other packages' marks are +%% % unaffected. +% \begin{macrocode} +%% \newcommand{\gamebooklibmarkclass}{gamebooklibmark} +\def\gamebooklib@mark{\mark} +%% \DeclareOption{mark}{% +%% \gamebook@info{Using mark class \gamebooklibmarkclass}% +%% \NewMarkClass{\gamebooklibmarkclass}% +%% \renewcommand{\gamebooklib@mark}[1]{\InsertMark{\gamebooklibmarkclass}{#1}}% +%% }% +% \end{macrocode} +% +% \popt{endpage} % The |endpage| option puts the last entry on its own page. This can % work better when the last entry is about a page long, and also % the final ``winning'' entry of the gamebook. @@ -388,9 +408,8 @@ \renewcommand\gamebook@beforelast{\eject}% }% % \end{macrocode} -% \end{macro} % -% \begin{macro}{jukebox} +% \popt{jukebox} % The |jukebox| option defines the \cs{gamebox@jukebox} macro; % while the macro does nothing, \cs{ifcsname} can then be used to % determine if the option was set. @@ -401,9 +420,8 @@ pass}% }% % \end{macrocode} -% \end{macro} % -% \begin{macro}{footnote} +% \popt{footnote} % The |footnote| option enables our footnote processing, to throw out % footnotes at the end of each |gentry| so that they don't appear to be % against subsequent entries for that page. @@ -418,9 +436,8 @@ \gamebook@info{Gamebook Library footnotes per gamebook entry}% }% % \end{macrocode} -% \end{macro} % -% \begin{macro}{noshuffle} +% \popt{noshuffle} % \begin{macrocode} \def\if@gamebook@shuffle{\iftrue} \DeclareOption{noshuffle}{% @@ -428,9 +445,8 @@ \gamebook@info{Gamebook Library entries output in order}% }% % \end{macrocode} -% \end{macro} % -% \begin{macro}{seed} +% \popt{seed} % All unknown options are passed to |lcg|, as it's our only dependency with options. % \begin{macrocode} \DeclareOption*{% @@ -438,7 +454,7 @@ }% \ProcessOptions\relax% % \end{macrocode} -% \end{macro}% We need to capture environment contents +% We need to capture environment contents % \begin{macrocode} \RequirePackage{environ}% % \end{macrocode} @@ -650,7 +666,7 @@ % \subsection*{The Shuffling Algorithm} % % The basic shuffling algorithm is to first shuffle all entries, -% except for those marked with a fixed index, then to ge through the +% except for those marked with a fixed index, then to go through the % fixed-index entries in order and swap them into their final place. % % The original version of this package had a bug relating to multiple @@ -889,7 +905,7 @@ }% % \end{macrocode} % Finally, we clear the registers and reset the counter in case we want to start again -% (NB: fixedto is scope to the current block only, so no need to clear that) +% (NB: |fixedto| is scope to the current block only, so no need to clear that) % \begin{macrocode} \gamebook@info{All gamebook entries added to main vertical list}% \setcounter{gentryctr}{1}% @@ -920,13 +936,14 @@ % It takes 4 parameters: %\begin{enumerate} %\item The \textit{unshuffled} index value (to help an author find an -% entry in the original text) +% entry in the original text); this is numerically the same as |\gentryidxs| %\item The \textit{fixed} index value, if any; otherwise an empty argument %\item The user-entered unique code for this entry %\item The user-supplied title, if any; otherwise an empty argument %\end{enumerate} % -% The value of the output index can be obtained with |\arabic{gentryctr}| +% The arabic value of the output index can be obtained with |\gentryidxu|; +% the numeric value is also set in the counter |gentryctr|. % \begin{macrocode} \newcommand{\gentryheader}[4]{% \noindent\textbf{\Huge\arabic{gentryctr}\large\ #4}% @@ -962,7 +979,7 @@ % \end{macrocode} % \end{macro} % -% \DescribeMacro{\gentryfooter} +% \begin{macro}{gentryfooter} % This takes no arguments and is simply expanded after the entry is typeset. The default adds some vertical % space and a simple separator. % @@ -971,8 +988,9 @@ \par\vspace{2em}\centerline{---}\vspace{2em plus 1in}\par% }% % \end{macrocode} +% \end{macro} % -% \DescribeMacro{\ignorespacesandallpars@} +% \begin{macro}{ignorespacesandallpars@} % 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}. % % This is used to ensure that extra space at the start and end of the |gentry| @@ -985,6 +1003,7 @@ {}% }% % \end{macrocode} +% \end{macro} % % \DescribeMacro{\@footnotetext}\marg{token register} % Token registers to hold each footnote. @@ -1005,7 +1024,7 @@ % \begin{macrocode} \g@addto@macro{\@makefnmark}{% \ifcsname in@out\endcsname\else% - \mark{\arabic{\@mpfn}}% + \gamebooklib@mark{\arabic{\@mpfn}}% \fi% }% % \end{macrocode} |