ran_toks (19may17)

git-svn-id: svn://tug.org/texlive/trunk@44429 c570f23f-e606-0410-a88d-b1316a301751

9 files changed, 586 insertions, 60 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
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}