texlive[67772] Master/texmf-dist: gamebooklib (30jul23)
commits+karl at tug.org
commits+karl at tug.org
Sun Jul 30 22:03:56 CEST 2023
Revision: 67772
http://tug.org/svn/texlive?view=revision&revision=67772
Author: karl
Date: 2023-07-30 22:03:56 +0200 (Sun, 30 Jul 2023)
Log Message:
-----------
gamebooklib (30jul23)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/gamebooklib/gamebooklib.pdf
trunk/Master/texmf-dist/doc/latex/gamebooklib/gamebooklib_test.pdf
trunk/Master/texmf-dist/source/latex/gamebooklib/gamebooklib.dtx
trunk/Master/texmf-dist/tex/latex/gamebooklib/gamebooklib.sty
Modified: trunk/Master/texmf-dist/doc/latex/gamebooklib/gamebooklib.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/gamebooklib/gamebooklib_test.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/latex/gamebooklib/gamebooklib.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/gamebooklib/gamebooklib.dtx 2023-07-30 20:03:46 UTC (rev 67771)
+++ trunk/Master/texmf-dist/source/latex/gamebooklib/gamebooklib.dtx 2023-07-30 20:03:56 UTC (rev 67772)
@@ -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,8 +166,13 @@
%
% 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
% |gentry| (gamebook entry) instead.
@@ -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,9 +281,8 @@
%
% 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
@@ -282,21 +289,19 @@
% 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 at rjlee.homelinux.org]
+\ProvidesPackage{gamebooklib}[2023/07/28 Gamebook by R Lee latex at 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 at info}, which throws away detail messages
% unless the |verbose| option is given.
@@ -376,9 +381,24 @@
\renewcommand{\gamebook at info}[1]{\PackageInfo{gamebooklib}{#1}}%
\gamebook at 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 at mark{\mark}
+%% \DeclareOption{mark}{%
+%% \gamebook at info{Using mark class \gamebooklibmarkclass}%
+%% \NewMarkClass{\gamebooklibmarkclass}%
+%% \renewcommand{\gamebooklib at 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 at beforelast{\eject}%
}%
% \end{macrocode}
-% \end{macro}
%
-% \begin{macro}{jukebox}
+% \popt{jukebox}
% The |jukebox| option defines the \cs{gamebox at 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 at info{Gamebook Library footnotes per gamebook entry}%
}%
% \end{macrocode}
-% \end{macro}
%
-% \begin{macro}{noshuffle}
+% \popt{noshuffle}
% \begin{macrocode}
\def\if at gamebook@shuffle{\iftrue}
\DeclareOption{noshuffle}{%
@@ -428,9 +445,8 @@
\gamebook at 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 at 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 at addto@macro{\@makefnmark}{%
\ifcsname in at out\endcsname\else%
- \mark{\arabic{\@mpfn}}%
+ \gamebooklib at mark{\arabic{\@mpfn}}%
\fi%
}%
% \end{macrocode}
Modified: trunk/Master/texmf-dist/tex/latex/gamebooklib/gamebooklib.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/gamebooklib/gamebooklib.sty 2023-07-30 20:03:46 UTC (rev 67771)
+++ trunk/Master/texmf-dist/tex/latex/gamebooklib/gamebooklib.sty 2023-07-30 20:03:56 UTC (rev 67772)
@@ -20,12 +20,25 @@
%% and version 1.3 or later is part of all distributions of
%% LaTeX version 2005/12/01 or later.
%%
-\ProvidesPackage{gamebooklib}[2022/05/25 Gamebook by R Lee latex at rjlee.homelinux.org]
+\ProvidesPackage{gamebooklib}[2023/07/28 Gamebook by R Lee latex at rjlee.homelinux.org]
\NeedsTeXFormat{LaTeX2e}[1994/06/01]
\newcommand{\gamebook at info}[1]{}%
\DeclareOption{verbose}{%
\renewcommand{\gamebook at info}[1]{\PackageInfo{gamebooklib}{#1}}%
\gamebook at info{Gamebook Library package is logging}}%
+%% 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.
+%% \newcommand{\gamebooklibmarkclass}{gamebooklibmark}
+\def\gamebooklib at mark{\mark}
+%% \DeclareOption{mark}{%
+%% \gamebook at info{Using mark class \gamebooklibmarkclass}%
+%% \NewMarkClass{\gamebooklibmarkclass}%
+%% \renewcommand{\gamebooklib at mark}[1]{\InsertMark{\gamebooklibmarkclass}{#1}}%
+%% }%
\newcommand\gamebook at beforelast{}
\DeclareOption{endpage}{%
\renewcommand\gamebook at beforelast{\eject}%
@@ -260,7 +273,7 @@
}%
\g at addto@macro{\@makefnmark}{%
\ifcsname in at out\endcsname\else%
- \mark{\arabic{\@mpfn}}%
+ \gamebooklib at mark{\arabic{\@mpfn}}%
\fi%
}%
\g at addto@macro{\gentry at footnotespergentry}{%
More information about the tex-live-commits
mailing list.