summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-05-19 21:06:02 +0000
committerKarl Berry <karl@freefriends.org>2017-05-19 21:06:02 +0000
commit910f589664407d620dc2a30c7b1de1a10e715df1 (patch)
treec158aaf1176ec1b644af62552d07e4ae6ab66cdf
parent7482e30efe28ea00047350822337d8a4defbd87a (diff)
ran_toks (19may17)
git-svn-id: svn://tug.org/texlive/trunk@44429 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/README.md12
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdfbin81844 -> 224675 bytes
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex242
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/db1.tex76
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/db2.tex65
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/db3.tex65
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/db4.tex65
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex75
-rw-r--r--Master/texmf-dist/doc/latex/ran_toks/examples/ran_toks.tex46
-rw-r--r--Master/texmf-dist/source/latex/ran_toks/ran_toks.dtx519
-rw-r--r--Master/texmf-dist/tex/latex/ran_toks/ran_toks.sty231
-rwxr-xr-xMaster/tlpkg/libexec/ctan2tds1
12 files changed, 1077 insertions, 320 deletions
diff --git a/Master/texmf-dist/doc/latex/ran_toks/README.md b/Master/texmf-dist/doc/latex/ran_toks/README.md
index ca048779fa6..6e47bf5109b 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/README.md
+++ b/Master/texmf-dist/doc/latex/ran_toks/README.md
@@ -1,7 +1,6 @@
The ran_toks Package
Author: D. P. Story
-Dated: 2016/02/06
-Version: v1.0e
+Dated: 2017/05/04
This short package, with minimal requirements, defines macros for
randomizing a list of tokens. There are two approaches:
@@ -38,15 +37,16 @@ myList, we would write \useRanTok{1}, \useRanTok{2}, \useRanTok{3},
\useRanTok{4}, and {\useRanTok{5}} to obtain a random listing of the
tokens in the myList list.
-For user of AeB or eqexam, the latter structure can be used to randomize
+For users of AeB or eqexam, the latter structure can be used to randomize
the order of the questions on a quiz or exam.
-If the ran_toks.sty file is not provided in the distribution, then tex (not latex)
-the file ran_toks.dtx.
+What's new in v1.1: Added the convenience command \useTheseDBs to input files for
+an application to constructing exams (using eqexam) from a series of DB files. Refer to the
+new demo file mc-db.tex.
Enjoy!
Now, I must get back to my retirement.
dps
-2016/02/08
+
diff --git a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf
index 08b4e443b69..66c8f3cbfd0 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf
+++ b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex
index b36612f1590..2776e3863db 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex
+++ b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex
@@ -7,13 +7,15 @@
]{aeb_pro}
\usepackage{ran_toks}
-%\useThisSeed{1441984427}
+\useThisSeed{1441984427}
%\useLastAsSeed
-\useThisSeed{2001383846}
+%\useThisSeed{2001383846}
%2001383846 % initializing seed value
%1629639958 % last random number used
+\let\pkg\textsf
+\let\env\texttt
%\rtdebugtrue
%\ranToksOn
@@ -41,11 +43,13 @@
\makeatother
\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$}
+\let\ameta\anglemeta
\def\meta#1{\textit{\texttt{#1}}}
\def\darg#1{\texttt{\{#1\}}}
\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei}
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
+
\usepackage[active]{srcltx}
\let\amtIndent\leftmargini
@@ -68,7 +72,7 @@
email={dpstory@acrotex.net},
subject=Documentation for the ran\_toks package,
talksite={\url{www.acrotex.net}},
- version={1.0e},
+ version={1.1},
Keywords={LaTeX,PDF,random, tokens, JavaScript,Adobe Acrobat},
copyrightStatus=True,
copyrightNotice={Copyright (C) \the\year, D. P. Story},
@@ -94,17 +98,52 @@
%\pagestyle{empty}
%\parindent0pt\parskip\medskipamount
-
-\definePath\bgPath{"C:/Users/Public/Documents/%
- ManualBGs/Manual_BG_Print_AeB.pdf"}
+\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
-\addWatermarkFromFile({%
- bOnTop: false,
- cDIPath: \bgPath
-})
-\executeSave()
+var titleOfManual="The ran_toks Package";
+var manualfilename="Manual_BG_Print_rt.pdf";
+var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
+var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
+var doc;
+var buildIt=false;
+if ( buildIt ) {
+ console.println("Creating new " + manualfilename + " file.");
+ doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
+ var _path=this.path;
+ var pos=_path.lastIndexOf("/");
+ _path=_path.substring(0,pos)+"/"+manualfilename;
+ \docSaveAs\newDO ({ cPath: _path });
+ doc.closeDoc();
+ doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
+ f=doc.getField("ManualTitle");
+ f.value=titleOfManual;
+ doc.flattenPages();
+ \docSaveAs\newDO({ cPath: manualfilename });
+ doc.closeDoc();
+} else {
+ console.println("Using the current "+manualfilename+" file.");
+}
+var _path=this.path;
+var pos=_path.lastIndexOf("/");
+_path=_path.substring(0,pos)+"/"+manualfilename;
+\addWatermarkFromFile({
+ bOnTop:false,
+ bOnPrint:false,
+ cDIPath:_path
+});
+\executeSave();
\end{docassembly}
+%\definePath\bgPath{"C:/Users/Public/Documents/%
+% ManualBGs/Manual_BG_Print_AeB.pdf"}
+%\begin{docassembly}
+%\addWatermarkFromFile({%
+% bOnTop: false,
+% cDIPath: \bgPath
+%})
+%\executeSave()
+%\end{docassembly}
+
\begin{document}
\maketitle
@@ -123,12 +162,18 @@ that matter.
\newtopic\noindent\exSrc The \texttt{examples} folder contains three demonstration files:
\begin{enumerate}
\item \texttt{ran\_toks.tex} reproduces the sample code of this manual.
- \item \texttt{random\_tst.tex} shows how to use \textsf{ran\_toks} to
+ \item \texttt{random\_tst.tex} shows how to use \pkg{ran\_toks} to
randomize the \emph{questions} of an exam document created by the
- \textsf{eqexam} package.
+ \pkg{eqexam} package.
\item \texttt{random\_tst\_qz.tex} shows how to randomize choices of a
- multiple choice field in a \texttt{quiz} environment of the
- \textsf{exerquiz} package, when the choices contain verbatim text.
+ multiple choice field in a \env{quiz} environment of the
+ \pkg{exerquiz} package, when the choices contain verbatim text.
+ \item \texttt{mc-db.tex} is an \pkg{eqexam} file that draws from the
+ database files \texttt{db1.tex}, \texttt{db2.tex},
+ \texttt{db3.tex}, and \texttt{db4.tex}, to construct the questions
+ of the exam. The questions are drawn at random from the DB files. Refer
+ to \hyperref[s:DBConcept]{Section~\ref*{s:DBConcept}} for a few more details.
+
\end{enumerate}
\section{The Preamble and Package Options}
@@ -144,7 +189,7 @@ The package itself has no options.
The requirements for \textsf{ran\_toks} are the \textsf{verbatim} package
(part of the standard {\LaTeX} distribution, and the macro file
-\texttt{random.tex} by Donald Arseneau
+\texttt{random.tex} by Donald Arseneau.
\section{The main commands and environments}\label{rtmain}
@@ -153,8 +198,7 @@ There are two styles for defining a series of tokens to be randomized,
using either the \cs{ranToks} command or the \cs{bRTVToks}/\cs{eRTVToks}
pair. Each of these is discussed in the next two subsections.
-\subsection{The \texorpdfstring{\protect\cs{ranToks}
-command}{\CMD{ranToks}} command}
+\subsection{The \texorpdfstring{\protect\cs{ranToks}}{\CMD{ranToks}} command}
The \cs{ranToks} command was the original concept; declare a series of
tokens to be randomized.
@@ -234,15 +278,41 @@ enclosed in braces to generate a space following the insertion of the text.
Repeating the sentence yields, ``I have {\nToksFor{myPals}} pals, they are
\useRanTok{1}, \useRanTok{2}, \useRanTok{3}, \useRanTok{4},
-{\useRanTok{5}} and \useRanTok{6}'' the exact same random order. To obtain
-a different order, re-execute the \cs{ranToks} command with the same
-arguments. Doing just that, \ranToks{myPals}{{Jim}{Richard}{Don}
+{\useRanTok{5}} and \useRanTok{6}'', which is the exact same random order. To
+obtain a different order, re-execute the \cs{ranToks} command with the same
+arguments.\footnote{{\ttfamily\string\ranToks\darg{myPals}\darg{\darg{Jim}\darg{Richard}\darg{Don}\darg{Alex}\darg{Tom}\darg{J\string\"\darg{u}rgen}}} in this example.} Doing just that, \ranToks{myPals}{{Jim}{Richard}{Don}
{Alex}{Tom}{J\"{u}rgen}}we obtain, ``I have {\nToksFor{myPals}} pals, they
are \useRanTok{1}, \useRanTok{2}, \useRanTok{3}, \useRanTok{4},
-{\useRanTok{5}} and \useRanTok{6}.'' A new order? For most applications,
-re-randomizing the same token list in the same document is not very likely
-something you need to do.
+{\useRanTok{5}} and \useRanTok{6}.'' A new order?
+An alternative to re-executing \cs{ranToks} is to use the \cs{reorderRanToks} command:
+\bVerb\takeMeasure{\string\reorderRanToks\darg{\meta{name}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\reorderRanToks{!meta(name)}
+\end{Verbatim}
+\end{minipage}\eVerb Now, executing \verb~\reorderRanToks{myPals}~ and compiling the sentence again yields,
+``I have {\nToksFor{myPals}} pals, they are
+\useRanTok{1}, \useRanTok{2}, \useRanTok{3}, \useRanTok{4},
+{\useRanTok{5}} and \useRanTok{6}.'' For most applications, re-randomizing
+the same token list in the same document is not very likely something you
+need to do.
+
+The \cs{reorderRanToks\darg{\meta{name}}} rearranges the list of tokens
+associated with \ameta{name}, which may not be what you want; the
+\cs{copyRanToks} command, on the other hand, makes a (randomized) copy of its
+first required argument \ameta{name\SUB1} and saves it as \ameta{name\SUB2}, without
+effecting the order of \ameta{name\SUB1}.
+\bVerb\takeMeasure{\string\copyRanToks\darg{\ameta{name\SUB1}}\darg{\ameta{name\SUB2}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\copyRanToks{!ameta(name!SUB1)}{!ameta(name!SUB2)}
+\end{Verbatim}
+\end{minipage}\eVerb Thus, if \verb!\copyRanToks{myPals}{myPals1}! is executed, the token list name
+\texttt{myPals1} contains the names of my pals in another randomized order,
+while maintaining the same order of \texttt{myPals}.
+
+\newtopic
My original application for this, the one that motivated writing this
package at long last, was the need to arrange several form buttons
randomly on the page. My point is that the listing given in the argument
@@ -252,25 +322,25 @@ and verbatim environments.
\subsection{The
\texorpdfstring{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
- {\CMD{bRTVToks}/\CMD{eRTVToks}} pair of commands}
+ {\CMD{bRTVToks}/\CMD{eRTVToks}} pair of commands}\label{ss:RTVToks}
Sometimes the content to be randomized is quite large or contains verbatim
text. For this, it may be more convenient to use the
\cs{bRTVToks}/\penalty0\cs{eRTVToks} command pair. The syntax is
\bVerb\takeMeasure{\string\bRTVToks\darg{\meta{name}}\quad}%
\edef\WIDTH{\the\wd\webtempboxi}%
-\def\1{\rlap{\hspace*{\WIDTH}\texttt{\% End token listing}}}%
-\takeMeasure{\string\bRTVToks\darg{\meta{name}}\quad\% <- Begin token listing}%
+\def\1{\rlap{\hspace*{\WIDTH}\texttt{\% <-{\sffamily{ End token listing}}}}}%
+\takeMeasure{\string\bRTVToks\darg{\meta{name}}\quad\% <-{\sffamily{ Begin token listing}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\bRTVToks{!meta(name)}!quad% <- Begin token listing
+\bRTVToks{!meta(name)}!quad% <-!sffamily( Begin token listing)
\begin{rtVW}
- !anglemeta(content!SUB(1))
+!qquad!ameta(content!SUB(1))
\end{rtVW}
...
...
\begin{rtVW}
- !anglemeta(content!SUB(n))
+!qquad!ameta(content!SUB(n))
\end{rtVW}
!1\eRTVToks
\end{Verbatim}
@@ -278,7 +348,7 @@ text. For this, it may be more convenient to use the
The \cs{bRTVToks}\texttt{\{\meta{name}\}} command begins the (pseudo)
environment and is ended by \cs{eRTVToks}. Between these two are a series of
\texttt{rtVW} (random toks verbatim write) environments. When the document is
-compiled, the contents (\anglemeta{content\SUB{i}}) of each of these environments
+compiled, the contents (\ameta{content\SUB{i}}) of each of these environments
are written to the computer hard drive and saved under a different name
(based on the parameter \meta{name}). Later, using the \cs{useRanTok}
commands, they are input back into the document in a random order.
@@ -349,6 +419,14 @@ The verbatim listing of the example above is
\item \useRanTok{3}
\end{enumerate}
\end{Verbatim}
+The \cs{reorderRanToks} works for lists created by the \cs{bRTVToks}/\penalty0\cs{bRTVToks} construct.
+If we say \cs{reorderRanToks\darg{myThoughts}} and reissue the above list, we obtain,
+\begin{enumerate}\ranToksOn\reorderRanToks{myThoughts}
+ \displayListRandomly[\item]{myThoughts}
+\end{enumerate}
+The command \cs{copyRanToks} works for list created by
+\cs{bRTVToks}/\penalty0\cs{bRTVToks} as well.
+
\paragraph*{On the \cs{displayListRandomly} command.}\label{para:DLR}
In the enumerate example immediately above, the items in the list are
@@ -359,18 +437,49 @@ alternate approach is to use the command \cs{displayListRandomly}, like so,
\displayListRandomly[\item]{myThoughts}
\end{enumerate}
\end{Verbatim}
-The \cs{displayListRandomly} has the syntax,
-\bVerb\takeMeasure{\string\displayListRandomly[\anglemeta{prior}]\darg{\meta{name}}}%
+The full syntax for \cs{displayListRandomly} is displayed next.
+\bVerb\takeMeasure{\string\displayListRandomly[\ameta{prior}][\ameta{post}]\darg{\meta{name}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\displayListRandomly[!anglemeta(prior)]{!meta(name)}
+\displayListRandomly[!ameta(prior)][!ameta(post)]{!meta(name)}
\end{Verbatim}
\end{minipage}
\eVerb The action of \cs{displayListRandomly} is to expand all tokens that
-are listed in the \meta{name} token list, each entry is displayed with
-\anglemeta{prior}\cs{useRanTok\darg{i}}, where \texttt{i} goes from~1 to
-\cs{nToksFor\darg{\meta{name}}}. In the example above, \meta{prior} is
-\cs{item}, but normally, its default is empty.
+are listed in the \meta{name} token list, each entry is displayed as
+\ameta{prior}\cs{useRanTok\darg{i}}\ameta{post}, where \texttt{i}
+goes from~1 to \cs{nToksFor\darg{\meta{name}}}. In the example above,
+\meta{prior} is \cs{item}, but normally, its default is empty. The defaults
+for \ameta{prior} and \ameta{post} are both empty.
+
+\subparagraph*{The optional arguments.} When only one optional argument is present,
+if is interpreted as \ameta{prior}. To obtain a \ameta{post} with no \ameta{prior}
+use the syntax,
+\begin{quote}
+\cs{displayListRandomly[][\ameta{post}]\darg{\ameta{name}}}
+\end{quote}
+Within \emph{each optional argument}, the four commands \cs{i},
+\cs{first}, \cs{last}, and \cs{lessone} are (locally) defined. The \cs{i} command is the index
+counter of the token currently being typeset; \cs{first} is the index of the
+first item; \cs{last} is the index of the last item; and \cs{lessone} is one
+less than \cs{last}. The two optional arguments and the four commands may use
+to perform logic on the token as it is being typeset. For example:
+\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
+List of pals: \displayListRandomly
+ [\ifnum\i=\last and \fi]
+ [\ifnum\i=\last.\else, \fi]{myPals}
+\end{Verbatim}
+yields,
+\begin{quote}
+List of pals: \displayListRandomly
+ [\ifnum\i=\last and \fi]
+ [\ifnum\i=\last.\else, \fi]{myPals}
+\end{quote}
+The optional arguments are wrapped to the next line to keep them within the margins, cool.
+
+The example above shows the list of my pals with an Oxford comma. How would
+you modify the optional argument to get the same listing without the Oxford
+comma? (\displayListRandomly[\ifnum\i=\last and \fi][\ifnum\i=\last.\else\ifnum\i=\lessone\relax\space\else, \fi\fi]{myPals})
+Hint: a solution involves the other command \cs{lessone}.
@@ -390,11 +499,11 @@ token in the range of 1 and \cs{nToksFor\darg{\meta{name}}},
inclusive. The optional argument is useful in special circumstances when
you want to mix two random lists together.
-\newtopic\noindent To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{1}
+\newtopic\noindent To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{2}
\newtopic\noindent The verbatim listing is
\begin{Verbatim}[xleftmargin=\amtIndent]
-To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{1}
+To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{2}
\end{Verbatim}
The typeset version looks a little strange, but recall, the text of
\texttt{myThoughts} were each put in a \texttt{minipage} of width \texttt{.67\cs{linewidth}}.
@@ -440,6 +549,29 @@ As a check, executing `$\cs{useRanTok\darg{3}} = \cs{rtTokByNum\darg{3}} = 3 $'
`\ranToksOff\ranToks{integers}{ {1}{2}{3}{4}}\ranToksOn
$\useRanTok{3} = \rtTokByNum{3} = 3 $'? As anticipated.
+To create a non-randomized list of tokens that already have been created (and randomized), use
+\cs{copyRanToks}:
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\ranToksOff\copyRanToks{myPals}{myOriginalPals}\ranToksOn
+\end{Verbatim}
+Then, using \cs{displayListRandomly} in a clever way,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\displayListRandomly[\ifnum\i=\last\space and \fi(\the\i)~]
+ [\ifnum\i=\last.\else,\fi\space]{myOriginalPals}
+\end{Verbatim}
+we obtain: \ranToksOff\copyRanToks{myPals}{myOriginalPals}\ranToksOn
+\displayListRandomly[\ifnum\i=\last\space and \fi(\the\i)~][\ifnum\i=\last.\else,\fi\space]{myOriginalPals}
+The original list for \texttt{myPals} remains unchanged:
+\displayListRandomly[\ifnum\i=\last\space and \fi(\the\i)~][\ifnum\i=\last.\else,\fi\space]{myPals}
+
+The \cs{useRanTok} command---whether it operates on a randomized token list
+or not---behaves similarly to an array. Thus, if we wanted the extract
+the third entry of the non-randomized token list (array)
+\texttt{myOriginalPals}, we do so by expanding the command
+\verb!\useRanTok[myOriginalPals]{3}! to produce
+\useRanTok[myOriginalPals]{3}.
+
+\subparagraph*{Document preparation.}
The command \cs{ranToksOff} is probably best in the preamble to turn off
all randomization while the rest of the document is being composed.
@@ -515,6 +647,36 @@ If you are using \textsf{eqexam}, the process can be automated as follows:
\end{Verbatim}
Again, this goes in the preamble.
+\section{Commands to support a DB application}\label{s:DBConcept}
+
+One user wanted to create exams using \pkg{eqexam}, but wanted to randomly
+select questions from a series of `database' files. My thought was that
+\pkg{ran\_toks} would do the job for him. After setting up a demo for him, I
+added the new command \cs{useTheseDBs} to \pkg{ran\_toks}:
+\bVerb\takeMeasure{\string\useTheseDBs\darg{\ameta{db\SUB{1}},\ameta{db\SUB{2}},...,\ameta{db\SUB{n}}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\useTheseDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}
+\useProbDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}
+\end{Verbatim}
+\end{minipage}\eVerb The argument of \cs{useTheseDBs} is a comma-delimited
+list of file names. Each file name contains a
+\cs{bRTVToks}/\penalty0\cs{eRTVToks} construct. Within this pair are
+\env{rtVW} environments, as described in
+\hyperref[ss:RTVToks]{Section~\ref*{ss:RTVToks}}. The \cs{useTheseDBs}
+command inputs the files listed in its comma-delimited argument; a warning is
+emitted if one or more of the files are not found. The default extension is
+\texttt{.tex}, \cs{useTheseDBs\darg{db1,db2}} inputs the files
+\texttt{db1.tex} and \texttt{db2.tex}, if they exist, while
+\cs{useTheseDBs\darg{db1.def,db2.db}} inputs the files \texttt{db1.def} and
+\texttt{db2.db}, if they exist. The command \cs{useProbDBs} is an alias for
+\cs{useTheseDBs}.
+
+The placement of \cs{useTheseDBs} is anywhere prior to the insertion of the
+problems into the document, usually in the preamble.
+
+Refer to the demonstration file \texttt{mc-db.tex} for an example.
+
\newtopic\noindent
Now, I simply must get back to my retirement. \dps
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/db1.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/db1.tex
new file mode 100644
index 00000000000..45a8b671246
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/db1.tex
@@ -0,0 +1,76 @@
+%
+% First DB, uses ran_toks and eqexam
+%
+\bRTVToks{DB1-}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB1: First: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=1,random,label=db1-1]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\begin{solution}
+It is obvious that the answer is `\useSavedAns{db1-1}', that is, alternative \useSavedAlts{db1-1} is correct.
+\end{solution}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB1: Second: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=1,random,label=db1-2]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\begin{solution}
+According to the guy sitting next to me, the answer might be \useSavedAlts{db1-2}
+\end{solution}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB1: Third: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=1,random,label=db1-3]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\begin{solution}
+I know the answer in advance to be \useSavedAlts{db1-3}, but don't tell anyone.
+\end{solution}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB1: Fourth: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=1,random,label=db1-4]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\begin{solution}
+After meditating in the lotus position on this question for many hours, we determine that the correct answer is \textbf{\useSavedAltsAns{db1-4}}.
+\end{solution}
+\end{problem}
+\end{rtVW}
+
+\eRTVToks
+
+\endinput
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/db2.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/db2.tex
new file mode 100644
index 00000000000..dc18b86faad
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/db2.tex
@@ -0,0 +1,65 @@
+%
+% Second DB, uses ran_toks and eqexam
+%
+
+\bRTVToks{DB2-}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB2: First: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB2: Second: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB2: Third: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB2: Fourth: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\eRTVToks
+
+\endinput \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/db3.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/db3.tex
new file mode 100644
index 00000000000..1948692f1f8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/db3.tex
@@ -0,0 +1,65 @@
+%
+% Third DB, uses ran_toks and eqexam
+%
+
+\bRTVToks{DB3-}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB3: First: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB3: Second: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB3: Third: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB3: Fourth: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\eRTVToks
+
+\endinput \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/db4.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/db4.tex
new file mode 100644
index 00000000000..64b1d241ef3
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/db4.tex
@@ -0,0 +1,65 @@
+%
+% Fourth DB, uses ran_toks and eqexam
+%
+
+\bRTVToks{DB4-}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB4: First: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB4: Second: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB4: Third: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\begin{rtVW}
+\begin{problem}[5]
+DB4: Fourth: Which is correct?
+\begin{answers}{4}
+\bChoices[nCols=2,random]
+ \Ans1 True\eAns
+ \Ans0 False\eAns
+ \Ans0 Maybe\eAns
+ \Ans0 Perhaps\eAns
+\eChoices
+\end{answers}
+\end{problem}
+\end{rtVW}
+
+\eRTVToks
+
+\endinput \ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex
new file mode 100644
index 00000000000..0e8ceab7b7d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex
@@ -0,0 +1,75 @@
+\documentclass{article}
+\usepackage[allowrandomize,nosolutions,
+ forpaper,pointsonleft,noparttotals]{eqexam}
+\usepackage{ran_toks}
+
+\useLastAsSeed
+% To reproduce the same pseudo-random sequence, you need to supply a seed
+%\useThisSeed{1125676795}
+
+\examNum{1}
+\title[T\nExam]{Test \nExam}
+\author{D. P. Story}
+\subject[MC]{My Course}
+\date{Spring \the\year}
+\keywords{Test~\nExam, Section 001}
+
+\university
+{%
+ THE UNIVERSITY OF AKRON\\
+ Theoretical and Applied Mathematics
+}
+\email{dpstory@uakron.edu}
+
+% Input the DB files used in the demo file
+\useTheseDBs{db1,db2,db3,db4}
+
+
+\begin{document}
+\maketitle
+
+\begin{exam}{Part1}
+
+\begin{instructions}
+Solve each without error. Passing is 100\%.
+
+\medskip\noindent
+This part demonstrates how to not only randomly pull problems (two from each of the DB files) at random, but
+to randomize the order they are listed in the exam.
+\end{instructions}
+
+\ranToks{myExam}{%
+ {\useRanTok[DB1-]{1}}
+ {\useRanTok[DB1-]{2}}
+ {\useRanTok[DB2-]{1}}
+ {\useRanTok[DB2-]{2}}
+ {\useRanTok[DB3-]{1}}
+ {\useRanTok[DB3-]{2}}
+ {\useRanTok[DB4-]{1}}
+ {\useRanTok[DB4-]{2}}
+}
+\displayListRandomly{myExam}
+
+\end{exam}
+
+\begin{exam}{Part2}
+
+\begin{instructions}
+In this part, we take the same two problems from each of the four DB files, but do not randomize
+the order of the questions.
+\end{instructions}
+
+\useRanTok[DB1-]{1}
+\useRanTok[DB1-]{2}
+\useRanTok[DB2-]{1}
+\useRanTok[DB2-]{2}
+\useRanTok[DB3-]{1}
+\useRanTok[DB3-]{2}
+\useRanTok[DB4-]{1}
+\useRanTok[DB4-]{2}
+
+\end{exam}
+
+\end{document}
+
+
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/ran_toks.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/ran_toks.tex
index 9bbe5ef985d..e10238aa5a7 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/examples/ran_toks.tex
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/ran_toks.tex
@@ -1,14 +1,16 @@
\documentclass{article}
\usepackage{ran_toks}
+\usepackage{ifthen}
-%\useThisSeed{606574325}
-\useLastAsSeed
-%\rtdebugtrue
-%\ranToksOn
+\useThisSeed{606574325} % comment out this line, and uncomment next line to get ...
+%\useLastAsSeed % a new pseudo-random sequence each time you compile.
+
+% Other useful switches
+%\ranToksOn % the default
%\ranToksOff
\parindent0pt \parskip6pt
-
+\def\cs#1{\texttt{\char`\\#1}}
\begin{document}
\begin{center}\bfseries
@@ -26,8 +28,8 @@ I have {\nToksFor{myPals}} pals, they are \useRanTok{1}, \useRanTok{2},
\useRanTok{3}, \useRanTok{4}, {\useRanTok{5}} and \useRanTok{6}. (Listed
in the order of best friend to least best friend.)
-Test of the \verb!\bRTVToks!/\verb!\eRTVToks! pair of commands and of the
-\texttt{rtVW} environment.
+Test of the \verb!\bRTVToks!/\verb!\eRTVToks! pair of commands, which encloses
+\texttt{rtVW} environments.
\bRTVToks{myThoughts}%
\begin{rtVW}
@@ -53,11 +55,8 @@ How did that other stuff get in there?
\end{rtVW}
\eRTVToks
\begin{enumerate}
- \item \useRanTok{1}
- \item \useRanTok{2}
- \item \useRanTok{3}
+ \displayListRandomly[\item]{myThoughts}
\end{enumerate}
-
Use \verb!\useRTName! command when another list separates the current
position from the list you want to use. Here we want to use the list named
\texttt{myPals}, but since that definition, a new list named
@@ -70,8 +69,27 @@ List of pals: \useRanTok{1}, \useRanTok{2}, \useRanTok{3},
For mixing lists. it might be easier to use the optional parameter:
{\useRanTok[myPals]{1}} and \useRanTok[myThoughts]{1}
-The \verb!\rtTokByNum! can retrieve an item from the list, in its declared
-order; eg, from the \texttt{myPals} list, the first and last are {\rtTokByNum[myPals]{1}}
-and \rtTokByNum[myPals]{\nToksFor{myPals}}.
+The \cs{rtTokByNum} can retrieve an item from the list in its declared order;
+eg, from the \texttt{myPals} list, the first and last are
+{\rtTokByNum[myPals]{1}} and \rtTokByNum[myPals]{\nToksFor{myPals}}.
+
+We demonstrate the command \cs{reorderRanToks} and the optional parameters of \cs{displayListRandomly}:
+\begin{quote}\reorderRanToks{myPals}%
+List of pals: \displayListRandomly[\ifnum\i=\last\space and \fi][\ifnum\i=\last.\else,\fi\space]{myPals}
+\end{quote}
+The reordering is global, so \displayListRandomly[\ifnum\i=\last\space and \fi][\ifnum\i=\last\else, \fi]{myPals}
+are listed in the same order as above, and different from the original random order seen in the second paragraph
+of this document.
+
+Without the Oxford comma: My pals are
+\displayListRandomly[\ifnum\i=\last and \fi][\ifnum\i=\last.\else\ifnum\i=\lessone\relax\space\else, \fi\fi]{myPals}
+
+The following is the same logic but uses the syntax of the \textsf{ifthen} package: My pals are
+\displayListRandomly[\ifthenelse{\i=\last}{and }{}][\ifthenelse{\i=\last}{.}{\ifthenelse{\i=\lessone}{\space}{, }}]{myPals}
+
+Test the \cs{copyRanToks} command:
+\copyRanToks{myPals}{myPals1}\displayListRandomly[\ifthenelse{\i=\last}{and }{}][\ifthenelse{\i=\last}{.}{\ifthenelse{\i=\lessone}{\space}{, }}]{myPals1}
+This does not change the order of the \texttt{myPals} list, which is still
+\displayListRandomly[\ifnum\i=\last\space and \fi][\ifnum\i=\last.\else,\fi\space]{myPals}
\end{document}
diff --git a/Master/texmf-dist/source/latex/ran_toks/ran_toks.dtx b/Master/texmf-dist/source/latex/ran_toks/ran_toks.dtx
index be22614b340..0a36c48614f 100644
--- a/Master/texmf-dist/source/latex/ran_toks/ran_toks.dtx
+++ b/Master/texmf-dist/source/latex/ran_toks/ran_toks.dtx
@@ -1,36 +1,10 @@
-% \iffalse meta-comment
-%<*internal>
-\iffalse
-%</internal>
-%<*internal>
-\fi
-\def\nameofplainTeX{plain}
-\ifx\fmtname\nameofplainTeX\else
- \expandafter\begingroup
-\fi
-%</internal>
-%<*install>
-\input docstrip.tex
-\keepsilent
-\askforoverwritefalse
-\preamble
-\endpreamble
-\ifx\fmtname\nameofplainTeX
-\generate{
- \file{\jobname.sty}{\from{\jobname.dtx}{copyright,package}}
-}
-\fi
-%</install>
-%<install>\endbatchfile
-%<*internal>
-\ifx\fmtname\nameofplainTeX
- \expandafter\endbatchfile\else
- \expandafter\endgroup\fi
-%</internal>
+%\iffalse
+% makeindex -s gglo.ist -o ran_toks.gls ran_toks.glo
+% makeindex -s gind.ist -o ran_toks.ind ran_toks.idx
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% ran_toks.sty package, 2013/08/03 %%
-%% Copyright (C) 2012 D. P. Story %%
+%% Web package, %%
+%% Copyright (C) 1999-2017 D. P. Story %%
%% dpstory@uakron.edu %%
%% %%
%% This program can redistributed and/or modified under %%
@@ -40,74 +14,97 @@
%% License, or (at your option) any later version. %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
-%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
%<package>\ProvidesPackage{ran_toks}
-%<package> [2016/02/06 v1.0e Randomizing tokens]
+%<package> [2017/05/04 v1.1 Randomizing tokens (dps)]
%<*driver>
\documentclass{ltxdoc}
-%\usepackage{\jobname}
-%\usepackage[numbered]{hypdoc}
-%\EnableCrossrefs
-%\CodelineIndex
-%\RecordChanges
+\usepackage[colorlinks,hyperindex=false]{hyperref}
+%\def\texorpdfstring#1#2{#1}
+%\pdfstringdefDisableCommands{\let\\\textbackslash}
+\OnlyDescription % comment out for implementation details
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\bgroup\ttfamily
+\gdef\brpr#1{\char123\relax#1\char125\relax}\egroup
+\let\darg\brpr
+\let\env\texttt
+\let\opt\texttt
+\let\app\textsf
+\def\visispace{\symbol{32}}
+\def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
+\def\meta#1{\textsl{\texttt{#1}}}
+\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
+\def\cs#1{\texttt{\bslash#1}}
+\InputIfFileExists{aebdocfmt.def}{\PackageInfo{ran_toks}{Inputting aebdocfmt.def}}
+ {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
+ \PackageInfo{ran_toks}{aebdocfmt.def cannot be found}}
\begin{document}
- \DocInput{\jobname.dtx}
+\def\CMD#1{\textbackslash#1}
+\let\pkg\textsf
+\let\opt\texttt
+\addtolength{\marginparwidth}{3pt}
+ \GetFileInfo{ran_toks.sty}
+ \title{The \textsf{ran\_toks} Package}
+ \author{D. P. Story\\
+ Email: \texttt{dpstory@uakron.edu}}
+ \date{processed \today}
+ \maketitle
+ \tableofcontents
+ \DocInput{ran_toks.dtx}
+\IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here.\\Execute
+ \texttt{makeindex -s gind.ist -o ran\_toks.ind ran\_toks.idx} on the command line and recompile
+ \texttt{ran\_toks.dtx}.}
+\IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here.\\Execute
+ \texttt{makeindex -s gglo.ist -o ran\_toks.gls ran\_toks.glo} on the command line and recompile
+ \texttt{ran\_toks.dtx}.}
\end{document}
%</driver>
% \fi
-%
-%\GetFileInfo{\jobname.sty}
-%
-%\title{The \textsf{ran\_toks} Package}
-%\author{D. P. Story}
-%\date{Released \today}
-%
-%\maketitle
-%
-%\StopEventually{^^A
-% \PrintChanges
-% \PrintIndex
-%}
+% \MakeShortVerb{|}
+% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{ran_toks}{Inputting aebdonotindex.def}}
+% {\PackageInfo{ran_toks}{cannot find aebdonotindex.def}}
%
% \begin{macrocode}
%<*package>
% \end{macrocode}
% \paragraph*{Description.}
% This short package randomizes a list of tokens. The command, \cs{ranToks},
-% takes one argument, which is, in turn, a list of tokens:
-%\begin{verbatim}
-% \ranToks{<name>}
-% {
-% {tok_1}{tok_2}...{tok_n}
+% takes one argument, which is a list of tokens:
+%\begin{quote}\ttfamily
+% \string\ranToks\darg{\ameta{name}}\\
+% \darg{\\\null
+% \qquad\darg{\ameta{tok\SUB1}}\darg{\ameta{tok\SUB2}}...\darg{\ameta{tok\SUB{n}}}\\
% }
-%\end{verbatim}
+%\end{quote}
% The command defines a series of $n$ internal commands, one for each of the tokens.
% The definitions are essentially randomized. The randomized tokens are accessed through
% the command \cs{useRanTok}. For example
-%\begin{verbatim}
-% \useRanTok{1}, \useRanTok{2},..., \useRanTok{n}
-%\end{verbatim}
+%\begin{quote}\ttfamily
+%\cs{useRanTok\darg{1}}, \cs{useRanTok\darg{2}},..., \cs{useRanTok\darg{n}}
+%\end{quote}
% gives a random listing of the $n$ tokens. These can be arranged on the page
% as desired.
%
% There is a second construct, designed for more elaborate randomization.
-%\begin{verbatim}
-%\bRTVToks{<name>}
-%\begin{rtVW}
-% <some content>
-%\end{rtVW}
-%...
-%...
-%\begin{rtVW}
-%<some content>
-%\end{rtVW}
-%\eRTVToks
-%\end{verbatim}
-% The contents of each of the \texttt{rtVW} environments are written to disk, then input
-% back in in random order, using \cs{useRanTok}, eg,
-%\begin{verbatim}
-% \useRanTok{1}, \useRanTok{2},..., \useRanTok{n}
-%\end{verbatim}
+%\begin{quote}\ttfamily
+%\string\bRTVToks\darg{\ameta{name}}\\
+%\string\begin\darg{rtVW}\\
+%\null\qquad\ameta{some content}\\
+%\string\end\darg{rtVW}\\
+%...\\
+%...\\
+%\string\begin\darg{rtVW}\\
+%\null\qquad\ameta{some content}\\
+%\string\end\darg{rtVW}\\
+%\string\eRTVToks
+%\end{quote}
+% The contents of each of the \texttt{rtVW} environments are written to the computers hard drive, then input
+% back in random order, using \cs{useRanTok}, eg,
+%\begin{quote}\ttfamily
+%\cs{useRanTok\darg{1}}, \cs{useRanTok\darg{2}},..., \cs{useRanTok\darg{n}}
+%\end{quote}
% Other details are left to the readers' imagination.
%
% \paragraph{Requirements.} As of this writing, we require only the \texttt{verbatim} package
@@ -115,7 +112,7 @@
% \begin{macrocode}
\RequirePackage{verbatim}
% \end{macrocode}
-% Input \texttt{random.tex} if now already input.
+% \paragraph*{Input \texttt{random.tex}.} Input \texttt{random.tex} if not already input.
%\changes{v1.0d}{2013/08/03}{Added conditional input of random.tex}
% \begin{macrocode}
\@ifundefined{nextrandom}{\input{random.tex}}{}
@@ -132,7 +129,7 @@
\nextrandom \nextrandom \nextrandom
% \end{macrocode}
% Save the initial seed value to \cs{rtInitSeedValue}.
-% \changes{v1.0c}{2013/08/03}{Save the initial seed value to \cs{rtInitSeedValue}.}
+% \changes{v1.0c}{2013/08/03}{Save the initial seed value to \string\cs{rtInitSeedValue}.}
% \begin{macrocode}
\xdef\InitSeedValue{\the\randomi}%
\fi
@@ -229,51 +226,50 @@
% We write only if \cs{ifsaveseed} is true.
% \begin{macrocode}
\def\InitSeedValue{\the\randomi}
-\def\rt@writeSeedData{%
- \ifsaveseed
- \@ifundefined{saveseedinfo}{\newwrite\saveseedinfo}{}
- \immediate\openout \saveseedinfo \jobname_rt.sav
- \let\verbatim@out\saveseedinfo
- \def\rt@msgi{initializing seed value}%
- \def\rt@msgii{last random number used}%
- \uccode`c=`\%\uppercase{%
- \rt@IWVO{\InitSeedValue\space c \rt@msgi}%
- \rt@IWVO{\the\randomi\space c \rt@msgii}%
- }\immediate\closeout\saveseedinfo
- \fi
-}
+\def\rt@writeSeedData{\ifsaveseed
+ \@ifundefined{saveseedinfo}{\newwrite\saveseedinfo}{}
+ \immediate\openout \saveseedinfo \jobname_rt.sav
+ \let\verbatim@out\saveseedinfo
+ \def\rt@msgi{initializing seed value}%
+ \def\rt@msgii{last random number used}%
+ \uccode`c=`\%\uppercase{%
+ \rt@IWVO{\InitSeedValue\space c \rt@msgi}%
+ \rt@IWVO{\the\randomi\space c \rt@msgii}}\immediate
+ \closeout\saveseedinfo\fi}
% \end{macrocode}
% Save the initial seed value to hard drive.
% \begin{macrocode}
\AtEndDocument{\rt@writeSeedData}%
% \end{macrocode}
-% \DescribeMacro{\rt@populateList} is a utility command, its argument is a positive integer, \texttt{n},
+% \DescribeMacro{\rt@populateList}\hskip-\marginparsep|{|\ameta{n}|}| is a utility command,
+% its argument \ameta{n} is a positive integer,
% and it generates a list of the form \verb!\\{1}\\{2}...\\{n}! and is held in the
% token register \cs{rt@listIn} This listing is later
% randomly permuted by \cs{rt@RandomizeList}.
% \begin{macrocode}
-\def\rt@populateList#1{%
- \rt@listIn={}%
- \rt@nCnt=0
- \@whilenum\rt@nCnt<#1\do{%
- \advance\rt@nCnt1
+\def\rt@populateList#1{\rt@listIn={}\rt@nCnt\z@
+ \@whilenum\rt@nCnt<#1\do{\advance\rt@nCnt\@ne
\edef\rt@listInHold{\the\rt@listIn\noexpand\\{\the\rt@nCnt}}%
- \rt@listIn=\expandafter{\rt@listInHold}%
- }%
-}
+ \rt@listIn=\expandafter{\rt@listInHold}}}
% \end{macrocode}
-% \DescribeMacro{\rt@RandomizeList} is the command that gets the process of randomizing
-% the input list going. The argument is the number of tokens. If
+% \DescribeMacro{\rt@RandomizeList}\hskip-\marginparsep\thinspace|{|\ameta{n}|}|
+% is the command that gets the process of randomizing
+% the input list going. The argument is the number \ameta{n} of tokens. If
% \cs{werandomize} is false, it just returns the input list; otherwise, it
% calls \cs{rt@randomizeList} to actually do the work.
% \begin{macrocode}
-\def\rt@RandomizeList#1{%
- \global\rt@listIn={}\global\rt@newListIn={}\global\rt@listOut={}%
+\def\rt@RandomizeList#1{\global
+ \rt@listIn={}\global\rt@newListIn={}\global\rt@listOut={}%
\rt@nMax=#1\relax\rt@populateList{\the\rt@nMax}%
\ifwerandomize
\expandafter\rt@randomizeList\else
\global\rt@listOut=\expandafter{\the\rt@listIn}\fi
-}
+% \end{macrocode}
+% Save the list out as \cs{rt@BaseName-List} for later retrieval. This is the randomized
+% list of integers for this base name.
+% \changes{v1.1}{2017/05/04}{Save out list for later use}
+% \begin{macrocode}
+ \global\rt@nameedef{\rt@BaseName-List}{\the\rt@listOut}}
% \end{macrocode}
% \DescribeMacro{\rt@randomizeList} randomizes the list of consecutive integers, and leaves the
% results,
@@ -283,17 +279,16 @@
% in the token register \cs{rt@listOut}.
% \cs{rt@randomizeList} is a loop, looping between itself and \cs{rt@loopTest}.
% \begin{macrocode}
-\def\rt@randomizeList{%
- \let\\=\rt@processi
+\def\rt@randomizeList{\let\\=\rt@processi
\setrannum{\rt@getRanNum}{1}{\the\rt@nMax}%
\ifrtdebug\typeout{\string\rt@getRanNum=\the\rt@getRanNum}\fi
- \rt@nCnt=0\relax
+ \rt@nCnt\z@
\ifrtdebug\typeout{LISTING: \the\rt@listIn}\fi
\the\rt@listIn
\rt@loopTest
}
-\def\rt@loopTest{\advance\rt@nMax-1\relax
- \ifnum\rt@nMax>0\relax
+\def\rt@loopTest{\advance\rt@nMax\m@ne
+ \ifnum\rt@nMax>\z@
\def\rt@next{%
\rt@listIn=\expandafter{\the\rt@newListIn}%
\rt@newListIn={}\rt@randomizeList}%
@@ -309,7 +304,7 @@
% contents of \cs{rt@listIn}. We then go into a loop \cs{rt@loopTest}. \cs{rt@getRanNum}
% is the random integer between 1 and \cs{rt@nMax}.
% \begin{macrocode}
-\def\rt@processi#1{\advance\rt@nCnt1
+\def\rt@processi#1{\advance\rt@nCnt\@ne
\ifnum\rt@nCnt=\rt@getRanNum
\edef\rt@listOutHold{\the\rt@listOut}%
\global\rt@listOut=\expandafter{\rt@listOutHold\\{#1}}%
@@ -322,52 +317,94 @@
\fi
}
% \end{macrocode}
+% We perform modular arithmetic when the index of \cs{useRanTok} is too large.
+% \DescribeMacro{\rt@modarith}\cs{rt@modarith} performs modular arithmetic on its arguments (\texttt{\#1 mod \#2})
+% and returns the result in the macro \cs{rt@mod}.
+% \begin{macrocode}
+\def\rt@modarith#1#2{\count\z@=#1\relax\count\tw@=#1\relax
+% \end{macrocode}
+% This macro uses \cs{dimen0} and
+% \cs{dimen2}, so it should be called within a group.
+% \begin{macrocode}
+ \advance\count\z@\m@ne\divide\count\z@ #2\relax
+ \multiply\count\z@ #2\relax
+ \advance\count\tw@-\count\z@
+ \edef\rt@mod{\the\count\tw@}}
+% \end{macrocode}
+% Warning messages, these are \DescribeMacro{\rt@badIndex}\cs{rt@badIndex} and
+% \cs{rt@badTokName}\DescribeMacro{\rt@badTokName}.
+% \begin{macrocode}
+\def\rt@badIndex#1#2{\PackageWarningNoLine{ran_toks}
+ {The argument of \string\useRanTok{#1} on line
+ \the\inputlineno\space is\MessageBreak
+ greater than \string\nToksFor{#2} (\nToksFor{#2}),
+ instead will use\MessageBreak
+ \string\useRanTok{\rt@mod}, obtained from modular
+ arithmetic.\MessageBreak
+ You might want to fix this}
+}
+\def\rt@badTokName#1{%
+ \PackageWarningNoLine{ran_toks}
+ {The token list `#1' on line \the\inputlineno\space
+ is undefined,\MessageBreak
+ possibly simply mispelled; check spelling.\MessageBreak
+ If undefined, use \string\ranToks\space or \string\bRTVToks/%
+ \string\eRTVToks\space\MessageBreak
+ to define a list with the name `#1'}%
+}
+\def\rt@warnTokName#1{%
+ \PackageWarningNoLine{ran_toks}
+ {The token list `#1' on line \the\inputlineno\space
+ is already defined,\MessageBreak
+ will overwrite this list}%
+}
+% \end{macrocode}
% \section{The main commands}
-% \DescribeMacro{\ranToks} takes one argument, a list of tokens. It randomizes them.
+% \begin{macro}{\ranToks}\hskip-\marginparsep\,\texttt{\darg{\ameta{token-list}}}
+% takes one argument, \texttt{\darg{\ameta{token-list}}}, a list of tokens. It randomizes them.
% The randomized listing can be accessed using \cs{useRanTok}.
% \begin{macrocode}
\def\ranToks#1{\begingroup
\useRTName{#1}%
\r@nToks
}
-\long\def\r@nToks#1{%
- \rt@nMax=0
- \r@ndToks#1\rt@NIL
-}
+\long\def\r@nToks#1{\rt@nMax\z@\r@ndToks#1\rt@NIL}
\def\rt@NIL{@nil}
% \end{macrocode}
-% \DescribeMacro{\useRTName} sets the base name (use prior to the use of \cs{useRanTok}).
+% \end{macro}
+% \begin{macro}{\useRTName}\hskip-\marginparsep\,\texttt{\darg{\ameta{name}}}
+% sets the base name (use prior to the use of \cs{useRanTok}).
% \begin{macrocode}
\newcommand{\useRTName}[1]{\gdef\rt@BaseName{#1}}%
\let\rt@BaseName\@empty
% \end{macrocode}
-% \DescribeMacro{\bRTVToks}\cs{bRTVToks} and \DescribeMacro{\eRTVToks}\cs{eRTVToks} enclose a series
+% \end{macro}
+% \begin{macro}{\bRTVToks}\hskip-\marginparsep\,\texttt{\darg{\ameta{name}}}
+% \cs{bRTVToks} and \cs{eRTVToks} enclose a series
% of \texttt{rtVW} environments. The single argument is the name of this set of
% verbatim write ``tokens''.
% \begin{macrocode}
-\newcommand{\bRTVToks}[1]{%
- \rt@nCnt=0
- \useRTName{#1}%
-}
+\newcommand{\bRTVToks}[1]{\rt@nCnt\z@\useRTName{#1}}
% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\eRTVToks}
% At the end of the \texttt{rtVW} environments, initiated by \cs{bRTVToks}, the
% \cs{eRTVToks} command saves the number of tokens counted, and randomizes the
% access to the contents of the \texttt{rtVW} environments, this done by
% \cs{r@nVToks}.
% \begin{macrocode}
-\newcommand{\eRTVToks}{%
- \global\rt@nameedef{\rt@BaseName Cnt}{\the\rt@nCnt}%
- \expandafter\r@nVToks\expandafter{\rt@BaseName}%
-}
+\newcommand{\eRTVToks}{\global
+ \rt@nameedef{\rt@BaseName Cnt}{\the\rt@nCnt}%
+ \expandafter\r@nVToks\expandafter{\rt@BaseName}}
% \end{macrocode}
+% \end{macro}
% \begin{environment}{rtVW}
% \cs{rtVW} is a verbatim write environment. It saves its contents to the file
% \verb!\jobname_\rt@BaseName\the\rt@nCnt.cut!. The file is later input back into
% the source file in a random way.
% \begin{macrocode}
\def\reVerbEnd{\ifhmode\unskip\fi}
-\newenvironment{rtVW}{%
- \global\advance\rt@nCnt1
+\newenvironment{rtVW}{\global\advance\rt@nCnt\@ne
\immediate\openout\rt@Verb@write
\jobname_\rt@BaseName\the\rt@nCnt.cut
\let\verbatim@out\rt@Verb@write
@@ -386,21 +423,18 @@
\gdef\rt@BaseName{#1}%
\expandafter\rt@nMax\@nameuse{#1Cnt}%
\rt@listIn={}\rt@nCnt=0\relax\let\rt@listInHold\@empty
- \@whilenum\rt@nCnt<\rt@nMax\do{%
- \advance\rt@nCnt1
- \edef\rt@listInHold{%
- \the\rt@listIn{\noexpand\rt@inputVerb{#1\the\rt@nCnt}}}%
- \rt@listIn=\expandafter{\rt@listInHold}%
- }%
-\ifrtdebug\typeout{\string\r@nVToks: \the\rt@listIn}\fi
- \expandafter\r@nToks\expandafter{\the\rt@listIn}%
-}
+ \@whilenum\rt@nCnt<\rt@nMax\do{\advance\rt@nCnt\@ne
+ \edef\rt@listInHold{%
+ \the\rt@listIn{\noexpand\rt@inputVerb{#1\the\rt@nCnt}}}%
+ \rt@listIn=\expandafter{\rt@listInHold}}\ifrtdebug
+ \typeout{\string\r@nVToks: \the\rt@listIn}\fi
+ \expandafter\r@nToks\expandafter{\the\rt@listIn}}
\def\rt@inputVerb#1{\input{\jobname_#1.cut}}
% \end{macrocode}
% \DescribeMacro{\r@ndToks} is main looping command for \cs{ranToks}
% and \cs{eRTVToks} (through \cs{r@nVToks}). If the ending token \cs{rt@NIL} is detected, we
% break off and go to \cs{rt@endToks}.
-% \changes{v1.0e}{2016/02/06}{Fixed a bug, when the first two tokens \texttt{\#1} are the same,
+% \changes{v1.0e}{2016/02/06}{Fixed a bug, when the first two tokens \string\texttt{\#1} are the same,
% we get an incorrect decision}
% \begin{macrocode}
\def\rt@PAR{\par}
@@ -409,74 +443,201 @@
% If the current argument is \cs{par}, we skip it
% \begin{macrocode}
\ifx\rt@rgi\rt@PAR\def\rt@next{\r@ndToks}\else
- \advance\rt@nMax1\relax
+ \advance\rt@nMax\@ne
\global\@namedef{rtTok\the\rt@nMax\rt@BaseName}{#1}%
\def\rt@next{\@ifnextchar\rt@NIL
- {\rt@endToks\@gobble}{\r@ndToks}}%
- \fi\rt@next
-}
+ {\rt@endToks\@gobble}{\r@ndToks}}\fi\rt@next}
+% \end{macrocode}
+% \hskip-\marginparsep|{|\ameta{n}|}| The \DescribeMacro{\rt@performRanDefns}\cs{rt@performRanDefns} performs code that
+% is repeated in several other macros: \cs{rt@endToks}, \cs{reorderRanToks}, and
+% \cs{copyRanToks}. It randomizes the list {\cs{rt@RandomizeList}, then assignments
+% the randomized list to the definitions.
+% \begin{macrocode}
+\def\rt@performRanDefns#1{%
+% \end{macrocode}
+% Now we randomize the order of the integers 1, 2,\dots \texttt{\#1}.
+% \begin{macrocode}
+ \rt@RandomizeList{#1}\rt@nCnt\z@
% \end{macrocode}
-% The final destination for \cs{r@ndToks}.
+% Now we randomize the definitions. We \verb!\let\\=\rt@ssign!, then
+% let loose the tokens!
+% \begin{macrocode}
+ \let\\\rt@ssign\the\rt@listOut}
+% \end{macrocode}
+% The final destination for \DescribeMacro{\rt@endToks}\cs{r@ndToks}.
% \begin{macrocode}
-\def\rt@endToks{%
+\def\rt@endToks{\global
% \end{macrocode}
% Save the number of tokens counted
% \begin{macrocode}
- \global\rt@nameedef{nMax4\rt@BaseName}{\the\rt@nMax}%
+ \rt@nameedef{nMax4\rt@BaseName}{\the\rt@nMax}%
+ \rt@performRanDefns{\the\rt@nMax}\endgroup}
% \end{macrocode}
-% Now we randomize the order of the integers 1, 2,\dots\cs{rt@nMax}.
+% \begin{macro}{\reorderRanToks}\hskip-\marginparsep\,\texttt{\darg{\ameta{name}}}
+% The \cs{reorderRanToks} command reorders (or re-indexes)
+% the family with name \ameta{name} (\texttt{\#1}).
% \begin{macrocode}
- \rt@RandomizeList{\the\rt@nMax}%
- \rt@nCnt=0
+\def\reorderRanToks#1{\begingroup\useRTName{#1}\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
% \end{macrocode}
-% Now we randomized the definitions. We \verb!\let\\=\assignRanToks!, then
-% let loose the tokens!
+% Document author has not run \cs{ranToks} yet for this basename (\texttt{\#1})
% \begin{macrocode}
- \let\\\assignRanToks
- \the\rt@listOut
- \endgroup
-}
+ \rt@badTokName{#1}\else
+% \end{macrocode}
+% Good to go. We reorder this list.
+% \begin{macrocode}
+ \rt@performRanDefns{\@nameuse{nMax4#1}}\fi
+\endgroup}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\copyRanToks}\hskip-\marginparsep
+% \texttt{\darg{\ameta{name1}}\darg{\ameta{name2}}}
+% Use this command to copy \ameta{name1} to \ameta{name2}. This gives
+% a randomization of the same list, without affecting the original order of \ameta{name1}.
+% \begin{macrocode}
+\newcommand\copyRanToks[2]{\begingroup\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+% \end{macrocode}
+% Source list is not defined
+% \begin{macrocode}
+ \rt@badTokName{#1}%
+ \else\expandafter
+% \end{macrocode}
+% Source list is defined
+% \begin{macrocode}
+ \ifx\csname nMax4#2\endcsname\relax
+% \end{macrocode}
+% Destination list is not defined, which is good in this instance. This is
+% the case we copy the list.
+% \begin{macrocode}
+ \useRTName{#2}\global
+ \rt@nameedef{nMax4#2}{\@nameuse{nMax4#1}}%
+ \rt@nCnt=\csname nMax4#2\endcsname\relax
+ \@whilenum\rt@nCnt>\z@\do{\global
+ \rt@nameedef{rtTok\the\rt@nCnt#2}%
+ {\noexpand\@nameuse{rtTok\the\rt@nCnt#1}}%
+ \advance\rt@nCnt\m@ne}%
+ \rt@performRanDefns{\@nameuse{nMax4#2}}\else
+% \end{macrocode}
+% Destination list is defined already, warn the user.
+% \begin{macrocode}
+ \rt@warnTokName{#2}\fi
+ \fi
+\endgroup}
% \end{macrocode}
-%\DescribeMacro{\assignRanToks} makes the assignments that are expanded by \cs{useRanTok}.
-% We \cs{let} the assignment \verb!\let\\=\assignRanToks! in \cs{rt@endToks}, just before we dump out the
+% \end{macro}
+%\DescribeMacro{\rt@ssign}\hskip-\marginparsep\texttt{\darg{\ameta{name}}} makes the assignments that are expanded by \cs{useRanTok}.
+% We \cs{let} the assignment \verb!\let\\=\rt@ssign! in \cs{rt@endToks}, just before we dump out the
% contents of \verb!\the\rt@listOut!.
% \begin{macrocode}
-\def\assignRanToks#1{\advance\rt@nCnt1
- \global\rt@nameedef{rtRanTok\the\rt@nCnt\rt@BaseName}%
- {\noexpand\@nameuse{rtTok#1\rt@BaseName}}%
-% {\noexpand\rtTokByNum[\rt@BaseName]{#1}}%
-}
+\def\rt@ssign#1{\advance\rt@nCnt\@ne\global
+ \rt@nameedef{rtRanTok\the\rt@nCnt\rt@BaseName}{\noexpand
+ \@nameuse{rtTok#1\rt@BaseName}}}
% \end{macrocode}
% \subsection{Additional user access commands}
-% \DescribeMacro{\nToksFor} expands the the number of tokens whose name is \texttt{\#1}.
+% \DescribeMacro{\nToksFor}\hskip-\marginparsep\texttt{\darg{\ameta{name}}}
+% expands the the number of tokens whose name is \ameta{name} (\texttt{\#1}).
% \begin{macrocode}
-\newcommand{\nToksFor}[1]{\@nameuse{nMax4#1}}
+\newcommand{\nToksFor}[1]{\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \textbf{??}\rt@badTokName{#1}\else
+ \@nameuse{nMax4#1}\fi}
% \end{macrocode}
-% \DescribeMacro{\rtTokByNum} is an internal macro, but it can be used publicly.
+% \DescribeMacro{\rtTokByNum}\hskip-\marginparsep\texttt{[\ameta{name}]\darg{\ameta{num}}} is an internal macro, but it can be used publicly.
% The argument of it is an integer, eg, \verb!\rtTokByNum{3}! is the third token, as listed in the order
% given in the argument of \cs{ranToks}.
% \begin{macrocode}
-\newcommand{\rtTokByNum}[2][\rt@BaseName]{\@nameuse{rtTok#2#1}%
- \ignorespaces}
+\newcommand{\rtTokByNum}[2][\rt@BaseName]{\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \textbf{??}\rt@badTokName{#1}\else
+ \@nameuse{rtTok#2#1}\expandafter\ignorespaces\fi}
+% \end{macrocode}
+%\DescribeMacro{\useRanTok}\hskip-\marginparsep\texttt{[\ameta{name}]\darg{\ameta{num}}}
+% After \cs{ranToks} has been executed, the user has access to the
+% randomized tokens through \cs{useRanTok}. The argument \ameta{num} is an integer 1 through max.
+% \begin{macrocode}
+\newcommand{\useRanTok}[2][\rt@BaseName]{\bgroup
+ \expandafter\ifx\csname nMax4#1\endcsname\relax
+ \rt@badTokName{#1}\else
+ \ifnum#2>\nToksFor{#1}\rt@modarith{#2}{\nToksFor{#1}}%
% \end{macrocode}
-%\DescribeMacro{\useRanTok} After \cs{ranToks} has been executed, the user has access to the
-% randomized tokens through \cs{useRanTok}. The argument is an integer 1 through max.
+% If index (\texttt{\#2}) is greater than array length, use modular arithmetic to resolve
+% the issue, and send a warning to the user.
+% \changes{v1.1}{2017/05/04}{Add modular arithmetic to resolve case where index is greater than length}
% \begin{macrocode}
-\newcommand{\useRanTok}[2][\rt@BaseName]{\@nameuse{rtRanTok#2#1}}
+ \rt@badIndex{#2}{#1}\@nameuse{rtRanTok\rt@mod#1}\else
+ \@nameuse{rtRanTok#2#1}\fi\fi\egroup}
% \end{macrocode}
-% \DescribeMacro{\displayListRandomly} lists all items in the list as passed
+% \DescribeMacro{\displayListRandomly}\hskip-\marginparsep\texttt{[\ameta{prior}][\ameta{post}]\darg{\ameta{name}}}
+% lists all items in the list as passed
% by the required argument. For expanding in a list environment, use \cs{item} as
% the optional argument. Designed for listing all question in an eqexam
% document in random order.
-%\changes{v1.0b}{2013/07/29}{Added \cs{displayListRandomly}}
-%\changes{v1.0e}{2016/02/06}{Added optional argument to \cs{displayListRandomly}}
-% \begin{macrocode}
-\newcommand{\displayListRandomly}[2][]{\rt@nCnt=0\relax
- \@whilenum\rt@nCnt<\nToksFor{#2}\advance\rt@nCnt1\relax
- \do{#1\useRanTok{\the\rt@nCnt}}%
+%\changes{v1.0b}{2013/07/29}{Added \string\cs{displayListRandomly}}
+%\changes{v1.0e}{2016/02/06}{Added optional argument to \string\cs{displayListRandomly}}
+%\changes{v1.1}{2017/05/04}{Added second optional argument to \string\cs{displayListRandomly}}
+% \begin{macrocode}
+\newcommand{\displayListRandomly}[1][]{\bgroup\def\rt@prior{#1}%
+ \displ@yListRandomly}
+\newcommand{\displ@yListRandomly}[2][]{\rt@nCnt\z@
+ \expandafter\ifx\csname nMax4#2\endcsname\relax
+ \rt@rgi\space\textbf{??}\rt@badTokName{#2}#1%
+ \else
+% \end{macrocode}
+% Within the optional arguments, we define \DescribeMacro{\i}\cs{i},
+% \DescribeMacro{\first}\cs{first}, \DescribeMacro{\last}\cs{last}, and
+% \DescribeMacro{\lessone}\cs{lessone} to do some logic on the arguments.
+% These four macro are defined locally and not available outside the command
+% \cs{displayListRandomly}.
+% \begin{macrocode}
+ \def\rt@post{#1}\useRTName{#2}\let\i\rt@nCnt
+ \def\first{1}\edef\last{\@nameuse{nMax4#2}}%
+ \@tempcnta\last \advance\@tempcnta\m@ne
+ \edef\lessone{\the\@tempcnta}%
+ \@whilenum\rt@nCnt<\last\advance\rt@nCnt\@ne
+ \do{\rt@prior\useRanTok{\the\rt@nCnt}\rt@post}%
+ \fi\egroup
}
% \end{macrocode}
+% \section{Commands that support a DB application}
+% We begin with some utility commands to help parse the argument of \cs{useProbDBs}.
+% \begin{macrocode}
+\def\rt@gettonil#1\@nil{\def\to@nilarg{#1}}
+\def\rt@ifspc{\ifx\@let@token\@sptoken
+ \let\rt@next\rt@xifspc\else
+ \let\rt@next\rt@gettonil\fi\rt@next}
+\begingroup
+\def\:{\rt@xifspc}
+\expandafter\gdef\: {\futurelet\@let@token\rt@ifspc}
+\endgroup
+\def\rt@strpspcs{\futurelet\@let@token\rt@ifspc}
+% \end{macrocode}
+% \begin{macro}{\useTheseDBs}\hskip-\marginparsep\thinspace|{|\ameta{list}|}|
+% Inputs any files included in the comma-delimited list. The base names need only be listed,
+% as the extension is assumed to be \texttt{.tex}. The command \cs{useProbDBs} can only be used
+% in the preamble. Refer to the demo file \texttt{mc\_db.tex} for an illustration of its intended use.
+% \begin{macrocode}
+\def\ProbDBWarningMsg#1{\filename@parse{#1}
+ \PackageWarning{ran_toks}
+ {The file \filename@area\filename@base.\ifx\filename@ext\relax
+ tex\else\filename@ext\fi\space cannot be found}}
+\def\useTheseDBs#1{\def\rt@dblist{#1}\ifx\rt@dblist\@empty\else
+ \let\rt@DB@List\@empty
+ \edef\temp@expand{\noexpand\@for\noexpand\@@tmp:=\rt@dblist}%
+ \temp@expand\do{\ifx\@@tmp\@empty\else
+ \expandafter\rt@strpspcs\@@tmp\@nil\edef\@@tmp{\to@nilarg}%
+ \edef\rt@nextDB{\noexpand
+ \InputIfFileExists{\@@tmp}{}{\noexpand
+ \ProbDBWarningMsg{\@@tmp}}}%
+ \toks\tw@=\expandafter{\rt@DB@List}%
+ \toks@=\expandafter{\rt@nextDB}%
+ \edef\rt@DB@List{\the\toks\tw@\space\the\toks@}\fi
+ }\expandafter\rt@DB@List\fi}
+\let\useProbDBs\useTheseDBs
+% \end{macrocode}
+% \end{macro}
% \begin{macrocode}
%</package>
% \end{macrocode}
-%\Finale
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/tex/latex/ran_toks/ran_toks.sty b/Master/texmf-dist/tex/latex/ran_toks/ran_toks.sty
index f656d89a241..f5f253e0b17 100644
--- a/Master/texmf-dist/tex/latex/ran_toks/ran_toks.sty
+++ b/Master/texmf-dist/tex/latex/ran_toks/ran_toks.sty
@@ -7,8 +7,8 @@
%% ran_toks.dtx (with options: `copyright,package')
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-%% ran_toks.sty package, 2013/08/03 %%
-%% Copyright (C) 2012 D. P. Story %%
+%% Web package, %%
+%% Copyright (C) 1999-2017 D. P. Story %%
%% dpstory@uakron.edu %%
%% %%
%% This program can redistributed and/or modified under %%
@@ -17,9 +17,9 @@
%% macros/latex/base/lppl.txt; either version 1 of the %%
%% License, or (at your option) any later version. %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\NeedsTeXFormat{LaTeX2e}
+\NeedsTeXFormat{LaTeX2e}[1997/12/01]
\ProvidesPackage{ran_toks}
- [2016/02/06 v1.0e Randomizing tokens]
+ [2017/05/04 v1.1 Randomizing tokens (dps)]
\RequirePackage{verbatim}
\@ifundefined{nextrandom}{\input{random.tex}}{}
\def\nextrandom{\begingroup
@@ -89,47 +89,38 @@
\def\endverbatimwrite{\@esphack}
\def\rt@IWVO{\immediate\write\verbatim@out}
\def\InitSeedValue{\the\randomi}
-\def\rt@writeSeedData{%
- \ifsaveseed
- \@ifundefined{saveseedinfo}{\newwrite\saveseedinfo}{}
- \immediate\openout \saveseedinfo \jobname_rt.sav
- \let\verbatim@out\saveseedinfo
- \def\rt@msgi{initializing seed value}%
- \def\rt@msgii{last random number used}%
- \uccode`c=`\%\uppercase{%
- \rt@IWVO{\InitSeedValue\space c \rt@msgi}%
- \rt@IWVO{\the\randomi\space c \rt@msgii}%
- }\immediate\closeout\saveseedinfo
- \fi
-}
+\def\rt@writeSeedData{\ifsaveseed
+ \@ifundefined{saveseedinfo}{\newwrite\saveseedinfo}{}
+ \immediate\openout \saveseedinfo \jobname_rt.sav
+ \let\verbatim@out\saveseedinfo
+ \def\rt@msgi{initializing seed value}%
+ \def\rt@msgii{last random number used}%
+ \uccode`c=`\%\uppercase{%
+ \rt@IWVO{\InitSeedValue\space c \rt@msgi}%
+ \rt@IWVO{\the\randomi\space c \rt@msgii}}\immediate
+ \closeout\saveseedinfo\fi}
\AtEndDocument{\rt@writeSeedData}%
-\def\rt@populateList#1{%
- \rt@listIn={}%
- \rt@nCnt=0
- \@whilenum\rt@nCnt<#1\do{%
- \advance\rt@nCnt1
+\def\rt@populateList#1{\rt@listIn={}\rt@nCnt\z@
+ \@whilenum\rt@nCnt<#1\do{\advance\rt@nCnt\@ne
\edef\rt@listInHold{\the\rt@listIn\noexpand\\{\the\rt@nCnt}}%
- \rt@listIn=\expandafter{\rt@listInHold}%
- }%
-}
-\def\rt@RandomizeList#1{%
- \global\rt@listIn={}\global\rt@newListIn={}\global\rt@listOut={}%
+ \rt@listIn=\expandafter{\rt@listInHold}}}
+\def\rt@RandomizeList#1{\global
+ \rt@listIn={}\global\rt@newListIn={}\global\rt@listOut={}%
\rt@nMax=#1\relax\rt@populateList{\the\rt@nMax}%
\ifwerandomize
\expandafter\rt@randomizeList\else
\global\rt@listOut=\expandafter{\the\rt@listIn}\fi
-}
-\def\rt@randomizeList{%
- \let\\=\rt@processi
+ \global\rt@nameedef{\rt@BaseName-List}{\the\rt@listOut}}
+\def\rt@randomizeList{\let\\=\rt@processi
\setrannum{\rt@getRanNum}{1}{\the\rt@nMax}%
\ifrtdebug\typeout{\string\rt@getRanNum=\the\rt@getRanNum}\fi
- \rt@nCnt=0\relax
+ \rt@nCnt\z@
\ifrtdebug\typeout{LISTING: \the\rt@listIn}\fi
\the\rt@listIn
\rt@loopTest
}
-\def\rt@loopTest{\advance\rt@nMax-1\relax
- \ifnum\rt@nMax>0\relax
+\def\rt@loopTest{\advance\rt@nMax\m@ne
+ \ifnum\rt@nMax>\z@
\def\rt@next{%
\rt@listIn=\expandafter{\the\rt@newListIn}%
\rt@newListIn={}\rt@randomizeList}%
@@ -140,7 +131,7 @@
\fi
\rt@next
}
-\def\rt@processi#1{\advance\rt@nCnt1
+\def\rt@processi#1{\advance\rt@nCnt\@ne
\ifnum\rt@nCnt=\rt@getRanNum
\edef\rt@listOutHold{\the\rt@listOut}%
\global\rt@listOut=\expandafter{\rt@listOutHold\\{#1}}%
@@ -152,28 +143,49 @@
\ifrtdebug\typeout{\string\rt@newListIn: \the\rt@newListIn}\fi
\fi
}
+\def\rt@modarith#1#2{\count\z@=#1\relax\count\tw@=#1\relax
+ \advance\count\z@\m@ne\divide\count\z@ #2\relax
+ \multiply\count\z@ #2\relax
+ \advance\count\tw@-\count\z@
+ \edef\rt@mod{\the\count\tw@}}
+\def\rt@badIndex#1#2{\PackageWarningNoLine{ran_toks}
+ {The argument of \string\useRanTok{#1} on line
+ \the\inputlineno\space is\MessageBreak
+ greater than \string\nToksFor{#2} (\nToksFor{#2}),
+ instead will use\MessageBreak
+ \string\useRanTok{\rt@mod}, obtained from modular
+ arithmetic.\MessageBreak
+ You might want to fix this}
+}
+\def\rt@badTokName#1{%
+ \PackageWarningNoLine{ran_toks}
+ {The token list `#1' on line \the\inputlineno\space
+ is undefined,\MessageBreak
+ possibly simply mispelled; check spelling.\MessageBreak
+ If undefined, use \string\ranToks\space or \string\bRTVToks/%
+ \string\eRTVToks\space\MessageBreak
+ to define a list with the name `#1'}%
+}
+\def\rt@warnTokName#1{%
+ \PackageWarningNoLine{ran_toks}
+ {The token list `#1' on line \the\inputlineno\space
+ is already defined,\MessageBreak
+ will overwrite this list}%
+}
\def\ranToks#1{\begingroup
\useRTName{#1}%
\r@nToks
}
-\long\def\r@nToks#1{%
- \rt@nMax=0
- \r@ndToks#1\rt@NIL
-}
+\long\def\r@nToks#1{\rt@nMax\z@\r@ndToks#1\rt@NIL}
\def\rt@NIL{@nil}
\newcommand{\useRTName}[1]{\gdef\rt@BaseName{#1}}%
\let\rt@BaseName\@empty
-\newcommand{\bRTVToks}[1]{%
- \rt@nCnt=0
- \useRTName{#1}%
-}
-\newcommand{\eRTVToks}{%
- \global\rt@nameedef{\rt@BaseName Cnt}{\the\rt@nCnt}%
- \expandafter\r@nVToks\expandafter{\rt@BaseName}%
-}
+\newcommand{\bRTVToks}[1]{\rt@nCnt\z@\useRTName{#1}}
+\newcommand{\eRTVToks}{\global
+ \rt@nameedef{\rt@BaseName Cnt}{\the\rt@nCnt}%
+ \expandafter\r@nVToks\expandafter{\rt@BaseName}}
\def\reVerbEnd{\ifhmode\unskip\fi}
-\newenvironment{rtVW}{%
- \global\advance\rt@nCnt1
+\newenvironment{rtVW}{\global\advance\rt@nCnt\@ne
\immediate\openout\rt@Verb@write
\jobname_\rt@BaseName\the\rt@nCnt.cut
\let\verbatim@out\rt@Verb@write
@@ -187,45 +199,104 @@
\gdef\rt@BaseName{#1}%
\expandafter\rt@nMax\@nameuse{#1Cnt}%
\rt@listIn={}\rt@nCnt=0\relax\let\rt@listInHold\@empty
- \@whilenum\rt@nCnt<\rt@nMax\do{%
- \advance\rt@nCnt1
- \edef\rt@listInHold{%
- \the\rt@listIn{\noexpand\rt@inputVerb{#1\the\rt@nCnt}}}%
- \rt@listIn=\expandafter{\rt@listInHold}%
- }%
-\ifrtdebug\typeout{\string\r@nVToks: \the\rt@listIn}\fi
- \expandafter\r@nToks\expandafter{\the\rt@listIn}%
-}
+ \@whilenum\rt@nCnt<\rt@nMax\do{\advance\rt@nCnt\@ne
+ \edef\rt@listInHold{%
+ \the\rt@listIn{\noexpand\rt@inputVerb{#1\the\rt@nCnt}}}%
+ \rt@listIn=\expandafter{\rt@listInHold}}\ifrtdebug
+ \typeout{\string\r@nVToks: \the\rt@listIn}\fi
+ \expandafter\r@nToks\expandafter{\the\rt@listIn}}
\def\rt@inputVerb#1{\input{\jobname_#1.cut}}
\def\rt@PAR{\par}
\long\def\r@ndToks#1{\def\rt@rgi{#1}%
\ifx\rt@rgi\rt@PAR\def\rt@next{\r@ndToks}\else
- \advance\rt@nMax1\relax
+ \advance\rt@nMax\@ne
\global\@namedef{rtTok\the\rt@nMax\rt@BaseName}{#1}%
\def\rt@next{\@ifnextchar\rt@NIL
- {\rt@endToks\@gobble}{\r@ndToks}}%
- \fi\rt@next
-}
-\def\rt@endToks{%
- \global\rt@nameedef{nMax4\rt@BaseName}{\the\rt@nMax}%
- \rt@RandomizeList{\the\rt@nMax}%
- \rt@nCnt=0
- \let\\\assignRanToks
- \the\rt@listOut
- \endgroup
-}
-\def\assignRanToks#1{\advance\rt@nCnt1
- \global\rt@nameedef{rtRanTok\the\rt@nCnt\rt@BaseName}%
- {\noexpand\@nameuse{rtTok#1\rt@BaseName}}%
-}
-\newcommand{\nToksFor}[1]{\@nameuse{nMax4#1}}
-\newcommand{\rtTokByNum}[2][\rt@BaseName]{\@nameuse{rtTok#2#1}%
- \ignorespaces}
-\newcommand{\useRanTok}[2][\rt@BaseName]{\@nameuse{rtRanTok#2#1}}
-\newcommand{\displayListRandomly}[2][]{\rt@nCnt=0\relax
- \@whilenum\rt@nCnt<\nToksFor{#2}\advance\rt@nCnt1\relax
- \do{#1\useRanTok{\the\rt@nCnt}}%
+ {\rt@endToks\@gobble}{\r@ndToks}}\fi\rt@next}
+\def\rt@performRanDefns#1{%
+ \rt@RandomizeList{#1}\rt@nCnt\z@
+ \let\\\rt@ssign\the\rt@listOut}
+\def\rt@endToks{\global
+ \rt@nameedef{nMax4\rt@BaseName}{\the\rt@nMax}%
+ \rt@performRanDefns{\the\rt@nMax}\endgroup}
+\def\reorderRanToks#1{\begingroup\useRTName{#1}\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \rt@badTokName{#1}\else
+ \rt@performRanDefns{\@nameuse{nMax4#1}}\fi
+\endgroup}
+\newcommand\copyRanToks[2]{\begingroup\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \rt@badTokName{#1}%
+ \else\expandafter
+ \ifx\csname nMax4#2\endcsname\relax
+ \useRTName{#2}\global
+ \rt@nameedef{nMax4#2}{\@nameuse{nMax4#1}}%
+ \rt@nCnt=\csname nMax4#2\endcsname\relax
+ \@whilenum\rt@nCnt>\z@\do{\global
+ \rt@nameedef{rtTok\the\rt@nCnt#2}%
+ {\noexpand\@nameuse{rtTok\the\rt@nCnt#1}}%
+ \advance\rt@nCnt\m@ne}%
+ \rt@performRanDefns{\@nameuse{nMax4#2}}\else
+ \rt@warnTokName{#2}\fi
+ \fi
+\endgroup}
+\def\rt@ssign#1{\advance\rt@nCnt\@ne\global
+ \rt@nameedef{rtRanTok\the\rt@nCnt\rt@BaseName}{\noexpand
+ \@nameuse{rtTok#1\rt@BaseName}}}
+\newcommand{\nToksFor}[1]{\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \textbf{??}\rt@badTokName{#1}\else
+ \@nameuse{nMax4#1}\fi}
+\newcommand{\rtTokByNum}[2][\rt@BaseName]{\expandafter
+ \ifx\csname nMax4#1\endcsname\relax
+ \textbf{??}\rt@badTokName{#1}\else
+ \@nameuse{rtTok#2#1}\expandafter\ignorespaces\fi}
+\newcommand{\useRanTok}[2][\rt@BaseName]{\bgroup
+ \expandafter\ifx\csname nMax4#1\endcsname\relax
+ \rt@badTokName{#1}\else
+ \ifnum#2>\nToksFor{#1}\rt@modarith{#2}{\nToksFor{#1}}%
+ \rt@badIndex{#2}{#1}\@nameuse{rtRanTok\rt@mod#1}\else
+ \@nameuse{rtRanTok#2#1}\fi\fi\egroup}
+\newcommand{\displayListRandomly}[1][]{\bgroup\def\rt@prior{#1}%
+ \displ@yListRandomly}
+\newcommand{\displ@yListRandomly}[2][]{\rt@nCnt\z@
+ \expandafter\ifx\csname nMax4#2\endcsname\relax
+ \rt@rgi\space\textbf{??}\rt@badTokName{#2}#1%
+ \else
+ \def\rt@post{#1}\useRTName{#2}\let\i\rt@nCnt
+ \def\first{1}\edef\last{\@nameuse{nMax4#2}}%
+ \@tempcnta\last \advance\@tempcnta\m@ne
+ \edef\lessone{\the\@tempcnta}%
+ \@whilenum\rt@nCnt<\last\advance\rt@nCnt\@ne
+ \do{\rt@prior\useRanTok{\the\rt@nCnt}\rt@post}%
+ \fi\egroup
}
+\def\rt@gettonil#1\@nil{\def\to@nilarg{#1}}
+\def\rt@ifspc{\ifx\@let@token\@sptoken
+ \let\rt@next\rt@xifspc\else
+ \let\rt@next\rt@gettonil\fi\rt@next}
+\begingroup
+\def\:{\rt@xifspc}
+\expandafter\gdef\: {\futurelet\@let@token\rt@ifspc}
+\endgroup
+\def\rt@strpspcs{\futurelet\@let@token\rt@ifspc}
+\def\ProbDBWarningMsg#1{\filename@parse{#1}
+ \PackageWarning{ran_toks}
+ {The file \filename@area\filename@base.\ifx\filename@ext\relax
+ tex\else\filename@ext\fi\space cannot be found}}
+\def\useTheseDBs#1{\def\rt@dblist{#1}\ifx\rt@dblist\@empty\else
+ \let\rt@DB@List\@empty
+ \edef\temp@expand{\noexpand\@for\noexpand\@@tmp:=\rt@dblist}%
+ \temp@expand\do{\ifx\@@tmp\@empty\else
+ \expandafter\rt@strpspcs\@@tmp\@nil\edef\@@tmp{\to@nilarg}%
+ \edef\rt@nextDB{\noexpand
+ \InputIfFileExists{\@@tmp}{}{\noexpand
+ \ProbDBWarningMsg{\@@tmp}}}%
+ \toks\tw@=\expandafter{\rt@DB@List}%
+ \toks@=\expandafter{\rt@nextDB}%
+ \edef\rt@DB@List{\the\toks\tw@\space\the\toks@}\fi
+ }\expandafter\rt@DB@List\fi}
+\let\useProbDBs\useTheseDBs
\endinput
%%
%% End of file `ran_toks.sty'.
diff --git a/Master/tlpkg/libexec/ctan2tds b/Master/tlpkg/libexec/ctan2tds
index 623d0bde4eb..33f0f0d7855 100755
--- a/Master/tlpkg/libexec/ctan2tds
+++ b/Master/tlpkg/libexec/ctan2tds
@@ -2473,7 +2473,6 @@ my $core_latex = "$Master/texmf-dist/tex/latex";
'polski' => 'latex', # requires interaction
'psfragx' => 'latex', # requires interaction
'pxrubrica' => 'platex',
- 'ran_toks' => 'tex',
'schedule' => 'latex', # requires interaction
'silence' => 'latex -translate-file=empty.tcx', # no 8-bit
'skdoc' => 'tex',