ran_toks (7jun21)

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

5 files changed, 303 insertions, 24 deletions

diff --git a/Master/texmf-dist/doc/latex/ran_toks/README.md b/Master/texmf-dist/doc/latex/ran_toks/README.md
index 8c3b618c71c..d2de6b319cf 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/README.md
+++ b/Master/texmf-dist/doc/latex/ran_toks/README.md
@@ -1,6 +1,6 @@
 The ran_toks Package
 Author: D. P. Story
-Dated: 2021-01-19 
+Dated: 2021-06-06
 
 This short package, with minimal requirements, defines macros for
 randomizing a list of tokens.  There are two approaches:
@@ -40,20 +40,22 @@ tokens in the myList list.
 For users of AeB or eqexam, the latter structure can be used to randomize
 the order of the questions on a quiz or exam.
 
-What's New (2021-01-19) A new option, usedbapp, was added to 
-support a DB application. Extensive work was done on the DB 
-application. Added \uniqueXDBChoicesOn, which if expanded, tries 
-to choose a random token that has not already been chosen, 
-across versions of a multi-version eqexam document. Changes are 
-discussed in the documentation and in the new examples in the 
-distribution. 
+What's New (2021-06-06) Added support for nested \bRTVToks/\eRTVToks command 
+  pairs. Demo files: ran_toks.tex and nested-matching.tex. 
+
+What's New (2021-01-19) A new option, usedbapp, was added to support a DB 
+  application. Extensive work was done on the DB application. Added 
+  \uniqueXDBChoicesOn, which if expanded, tries to choose a random token that 
+  has not already been chosen, across versions of a multi-version eqexam 
+  document. Changes are discussed in the documentation and in the new 
+  examples in the distribution. 
 
 What's New (2019-12-28) Defined \rtVWHook to insert at the top of the
-rtVW environment. Also created an alternate package name of ran-toks.
+  rtVW environment. Also created an alternate package name of ran-toks. 
 
-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.
+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!
 
diff --git a/Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf b/Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf
index bfc8e7bc9b2..815095a955f 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf
+++ b/Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf
diff --git a/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf b/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf
index 62ee68da81c..16146c1f6f7 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf
+++ b/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf
diff --git a/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.tex b/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.tex
index 8f8b0c6246b..232c1980ca9 100644
--- a/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.tex
+++ b/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.tex
@@ -8,7 +8,8 @@
 ]{aeb_pro}
 \usepackage{ran_toks}
 
-\useThisSeed{1441984427}
+\useThisSeed{227819015}
+%\useThisSeed{1441984427}
 %\useLastAsSeed
 %\useThisSeed{2001383846}
 
@@ -30,6 +31,7 @@
 %\usepackage{makeidx}
 %\makeindex
 \usepackage{acroman}
+\usepackage[active]{srcltx}
 
 \makeatletter
 \def\eq@fititin#1{\noindent\unskip\nobreak\hfill\penalty50
@@ -77,17 +79,19 @@
 
 \urlstyle{rm}
 
+\let\tops\texorpdfstring
+
 \DeclareDocInfo
 {
     university={\AcroTeX.Net},
-    title={\texorpdfstring{The \textsf{ran\_toks}}{The manual for the ran\_toks}
-        Package\texorpdfstring{\\[6pt]\large}{: }
+    title={\tops{The \textsf{ran\_toks}}{The manual for the ran\_toks}
+        Package\tops{\\[6pt]\large}{: }
         Randomizing the order of tokens},
     author={D. P. Story},
     email={dpstory@acrotex.net},
     subject=Documentation for the ran\_toks package,
     talksite={\url{www.acrotex.net}},
-    version={1.3.1, 2021/01/19},
+    version={1.4, 2021/06/06},
     Keywords={LaTeX, PDF, random, tokens, JavaScript, Adobe Acrobat},
     copyrightStatus=True,
     copyrightNotice={Copyright (C) \the\year, D. P. Story},
@@ -106,7 +110,7 @@
 \sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
 \subsectionLayout{indent=-31.25pt,color=aeb}
 \subsubsectionLayout{indent=0pt,color=aeb}
-\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}
+\subsubDefaultDing{\tops{$\bullet$}{\textrm\textbullet}}
 
 \def\exSrc{\makebox[0pt][r]{\large{\Pisymbol{webd}{157}}\enspace}}
 
@@ -241,7 +245,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}}{\CMD{ranToks}} command}\label{s:ranToks}
+\subsection{The \tops{\protect\cs{ranToks}}{\CMD{ranToks}} command}\label{s:ranToks}
 
 The \cs{ranToks} command was the original concept; declare a series of
 tokens to be randomized.
@@ -334,13 +338,13 @@ An alternative to re-executing \cs{ranToks} is to use the \cs{reorderRanToks} co
 \reorderRanToks{!ameta(name)}
 \end{Verbatim}
 \end{minipage}\eVerb Now, executing \verb~\reorderRanToks{myPals}~ and compiling the sentence again yields,
-``I have {\nToksFor{myPals}} pals, they are
+``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{\ameta{name}}} rearranges the list of tokens
+The \cs{reorderRanToks\darg{\ameta{name}}} command 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
@@ -364,7 +368,7 @@ argument of a macro; this would exclude verbatim text created by \cs{verb}
 and verbatim environments.
 
 \subsection{The
-\texorpdfstring{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
+\tops{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
     {\CMD{bRTVToks}/\CMD{eRTVToks}} pair of commands}\label{ss:RTVToks}
 
 Sometimes the content to be randomized is quite large or contains verbatim
@@ -495,7 +499,6 @@ If we say \cs{reorderRanToks\darg{myThoughts}} and reissue the above list, we ob
 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
 explicitly listed as \cs{item \cs{useRanTok\darg{1}}} and so on; an
@@ -549,7 +552,131 @@ 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}.
 
+\subsubsection{Nested
+\tops{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
+    {\CMD{bRTVToks}/\CMD{eRTVToks}} command pairs}\label{ss:NestedRTVToks}
+
+These is at least one example of using nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks}. When nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks} command pairs, use the \env{rtVWi}
+environment instead of the \env{rtVW} environment. The nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks} pair is placed\FmtMP{placement} within
+a \env{rtWV} environment; in this way the contents of that \env{rtWV}
+environment, itself can be randomized. The \cs{displayListRandomly} (or
+\cs{useRanTok}) command is used to list out the nested items. See the next
+page for an example.
+
+\newpage
+
+\bRTVToks{Depth0}
+  \begin{rtVW}
+    Depth0: Item 1
+\end{rtVW}
+  \begin{rtVW}
+    Depth0: Item 2:
+    \bRTVToks{Depth1}
+      \begin{rtVWi}
+        Depth1: Item 1
+\end{rtVWi}
+      \begin{rtVWi}
+        Depth1: Item 2
+        \bRTVToks{Depth2}
+          \begin{rtVWii}
+              Depth2: Item 1
+\end{rtVWii}
+          \begin{rtVWii}
+              Depth2: Item 2
+\end{rtVWii}
+          \begin{rtVWii}
+              Depth2: Item 3
+\end{rtVWii}
+        \eRTVToks
+\begin{itemize}
+        \displayListRandomly[\item]{Depth2}
+\end{itemize}
+\end{rtVWi}
+      \begin{rtVWi}
+        Depth1: Item 3
+\end{rtVWi}
+\eRTVToks
+\begin{itemize}
+\displayListRandomly[\item]{Depth1}
+\end{itemize}
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 3
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 4
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 5
+\end{rtVW}
+\eRTVToks
+   \begin{enumerate}\small
+\displayListRandomly[\item]{Depth0}
+\end{enumerate}
+The verbatim listing for this example follows.
+\begin{Verbatim}[commandchars=!(),fontsize=\small]
+\bRTVToks{Depth0}
+  \begin{rtVW}
+    Depth0: Item 1
+\end{rtVW}
+  \begin{rtVW}
+    Depth0: Item 2:
+    \bRTVToks{Depth1} % !textsf(begin Depth2 within an rtVW env.)
+      \begin{rtVWi}
+        Depth1: Item 1
+\end{rtVWi}
+      \begin{rtVWi}
+        Depth1: Item 2
+        \bRTVToks{Depth2} % !textsf(begin Depth1 within an rtVWi env.)
+          \begin{rtVWii}
+              Depth2: Item 1
+\end{rtVWii}
+          \begin{rtVWii}
+              Depth2: Item 2
+\end{rtVWii}
+          \begin{rtVWii}
+              Depth2: Item 3
+\end{rtVWii}
+        \eRTVToks
+\begin{itemize}
+        \displayListRandomly[\item]{Depth2} % !textsf(display Depth2 toks)
+\end{itemize}
+\end{rtVWi}
+      \begin{rtVWi}
+        Depth1: Item 3
+\end{rtVWi}
+\eRTVToks
+\begin{itemize}
+\displayListRandomly[\item]{Depth1} % !textsf(display Depth1 toks)
+\end{itemize}
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 3
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 4
+\end{rtVW}
+  \begin{rtVW}
+      Depth0: Item 5
+\end{rtVW}
+\eRTVToks
+\begin{enumerate}
+\displayListRandomly[\item]{Depth0} % !textsf(display Depth0 toks)
+\end{enumerate}
+\end{Verbatim}
+Oops. Did I forget to mention that \pkg{ran\_toks} supports nested to a depth of two.
+
+Some authors like to indent nested things, but to avoid spurious spaces
+appearing, \cs{end\darg{rtVW}} (and \cs{end\darg{rtVWi}}) should be placed in
+the far left margin, as shown above. Recall the \env{rtVW} is a verbatim
+environment.
 
+The above example is reproduced in the \texttt{ran\_toks.tex} sample file found in the
+\texttt{examples} folder. Also found in that folder is \texttt{nested-matching.tex}, a \pkg{exerquiz}
+quiz that motivated creating nested \cs{bRTVToks}/\allowbreak\cs{eRTVToks} command pairs.
 
 \section{Additional arguments and commands}\label{AddCmds}
 
@@ -633,7 +760,7 @@ 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
+or not---behaves similarly to an array. Thus, if we wanted to 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
@@ -752,7 +879,7 @@ The next step is to input your DB files. To do this, execute either of the comma
 or perhaps in the preamble. The syntax is,
 \bVerb\takeMeasure{\string\useTheseDBs\darg{\ameta{db\SUB{1}},\ameta{db\SUB{2}},...,\ameta{db\SUB{n}}}}%
 \setlength\eflength{\bxSize}%
-\begin{minipage}{\bxSize}\kern0pt\def\1{\rlap{\sffamily\hskip\eflength(An alias for \cs{useTheseDBs})}}\relax
+\begin{minipage}{\bxSize}\def\1{\rlap{\sffamily\hskip\eflength(An alias for \cs{useTheseDBs})}}\kern0pt
 \begin{Verbatim}[frame=single,commandchars=!()]
 \useTheseDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}
 !1\useProbDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}
diff --git a/Master/texmf-dist/doc/latex/ran_toks/examples/nested-matching.tex b/Master/texmf-dist/doc/latex/ran_toks/examples/nested-matching.tex
new file mode 100644
index 00000000000..c6886e2def1
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ran_toks/examples/nested-matching.tex
@@ -0,0 +1,150 @@
+\documentclass{article}
+\usepackage{amstext}
+\usepackage[forcolorpaper]{web}
+\usepackage[usesumrytbls,allowrandomize]{exerquiz}[2021/05/29]
+\usepackage{ran_toks}[2021/05/29]
+\usepackage{multicol}
+
+\DeclareQuiz{Qz1}
+
+\useRandomSeed{1294278923}
+%\useLastAsSeed
+
+\hypersetup{pdfpagemode=UseNone} % don't need to see bookmarks
+\hypersetup{pdfpagelayout=OneColumn}
+\reversemarginpar
+\showCreditMarkup
+
+%\previewOn\pmpvOn
+
+\useBeginQuizButton[\CA{Begin}]
+\useEndQuizButton[\CA{End}]
+\PTsHook{($\eqPTs^{\text{pts}}$)}
+\useMCCircles
+
+\newcommand{\presetMatch}{\Q{1}\AddAAKeystroke{event.change=event.change.toUpperCase();}\rectW{\widthof{AA}}}
+
+\begin{document}
+
+\bRTVToks{\currQuiz}
+
+\begin{quiz*}{\currQuiz}
+Solve each of these problems, passing is 100\%.
+\begin{questions}
+    \begin{rtVW}
+        \item\PTs{2} $9+8=\RespBoxMath{17}*{1}{.0001}{[0,1]}\cgBdry[1bp]
+      \CorrAnsButton{17}$
+        \begin{solution}
+            Blimey! Everyone knows that $ 9 + 8 = 17$, why don't you ? BTW, $17$ is my formerly favorite number.
+\end{solution}
+\end{rtVW}
+
+    \begin{rtVW}
+        \item\PTs{3} Which of the following are numbers?
+        \begin{manswers}*{6}
+            \bChoices[random=true]
+            \Ans[-1]{0}D\eAns
+            \Ans[1]{1}17\eAns
+            \Ans[-1]{0}P\eAns
+            \Ans[1]{1}88\eAns
+            \Ans[-1]{0}S\eAns
+            \Ans[1]{1}105\eAns
+            \eChoices
+        \end{manswers}
+        \begin{solution}
+         Which are  numbers? 17, 88, and 105, silly
+\end{solution}
+\end{rtVW}
+
+    \begin{rtVW}
+  \item\PTs{3} $ \cos(\pi) = \RespBoxMath{-1}*{1}{.0001}{[0,1]}\cgBdry[1bp]
+      \CorrAnsButton{-1} $
+\begin{solution}
+$ \cos(\pi) = -1 $
+\end{solution}
+\end{rtVW}
+
+    \begin{rtVW}
+\item\PTs{4} $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}*{4}{.0001}{[0,1]}\cgBdry[1bp]
+      \CorrAnsButton{cos(x)} $
+\begin{solution}
+ $\displaystyle\frac{d}{dx}{\sin(x)}= \cos(x) $
+\end{solution}
+\end{rtVW}
+
+    \begin{rtVW}
+\hideCreditMarkup
+        \item\PTs{3} Match the last name of the U.S. President with his first
+        name in the right most two columns. Each problem is worth 1 point.
+
+\bRTVToks{RandomQzQuesB}
+\begin{rtVWi}
+   \PTs*{1}\RespBoxTxt[\presets{\presetMatch}\rectW{5mm}\MaxLen{1}]{0}{0}*{1}{\txtRef{willy}} Brandt
+   \begin{solution}
+       \underbar{Willy} Brandt
+\end{solution}
+\end{rtVWi}
+\begin{rtVWi}
+   \PTs*{1}\RespBoxTxt[\presets{\presetMatch}\rectW{5mm}\MaxLen{1}]{0}{0}*{1}{\txtRef{roman}} Herzog
+   \begin{solution}
+       \underbar{Roman} Herzog
+\end{solution}
+\end{rtVWi}
+\begin{rtVWi}
+   \PTs*{1}\RespBoxTxt[\presets{\presetMatch}\rectW{5mm}\MaxLen{1}]{0}{0}*{1}{\txtRef{konrad}} Adenauer
+   \begin{solution}
+       \underbar{Konrad} Adenauer
+\end{solution}
+\end{rtVWi}
+\eRTVToks
+\bRTVToks{RandomQzAltsB}
+\begin{rtVWi}
+   Gustav
+\end{rtVWi}
+\begin{rtVWi}
+   \label{konrad} Konrad
+\end{rtVWi}
+\begin{rtVWi}
+   \label{willy} Willy
+\end{rtVWi}
+\begin{rtVWi}
+   \label{roman} Roman
+\end{rtVWi}
+\begin{rtVWi}
+   Ludwig
+\end{rtVWi}
+\begin{rtVWi}
+   Hermann
+\end{rtVWi}
+\begin{rtVWi}
+   Karl
+\end{rtVWi}
+\begin{rtVWi}
+   J\"{u}rgen
+\end{rtVWi}
+\eRTVToks
+    \begin{multicols}{4}
+       \begin{questions}[labelwidthTo={\textbf{A}}]
+           \hideCreditMarkup
+           \renewcommand{\theeqquestionnoii}{\Alph{eqquestionnoii}}
+           \displayListRandomly[\item]{RandomQzAltsB}
+           \showCreditMarkup
+       \end{questions}
+    \end{multicols}
+    \begin{questions}
+       \showCreditMarkup
+       \displayListRandomly[\item]{RandomQzQuesB}
+    \end{questions}
+\end{rtVW}
+  \eRTVToks
+  \displayListRandomly{\thisQuiz}
+\end{questions}
+%\writeProListAux
+\end{quiz*}\cgBdry[1em]\ScoreField{\currQuiz}\olBdry\CorrButton{\currQuiz}\vcgBdry[6pt]
+
+Answers: \AnswerField\currQuiz
+
+\begin{center}
+\displaySumryTbl[showmarkup]{\currQuiz}
+\end{center}
+\end{document}