summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ran_toks/docs
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-12-31 03:00:32 +0000
committerNorbert Preining <norbert@preining.info>2019-12-31 03:00:32 +0000
commit1f9ab71f8ea4751f440072e9e4da3314edbbcf2e (patch)
tree1ac9f67dd95b7e3072b7951e6cb1590fda73ffb9 /macros/latex/contrib/ran_toks/docs
parent0af8a1a375250bdab8576ca414baae91122ea6a3 (diff)
CTAN sync 201912310300
Diffstat (limited to 'macros/latex/contrib/ran_toks/docs')
-rw-r--r--macros/latex/contrib/ran_toks/docs/ran_toks.pdfbin0 -> 106437 bytes
-rw-r--r--macros/latex/contrib/ran_toks/docs/rantoks_man.pdfbin0 -> 226760 bytes
-rw-r--r--macros/latex/contrib/ran_toks/docs/rantoks_man.tex689
3 files changed, 689 insertions, 0 deletions
diff --git a/macros/latex/contrib/ran_toks/docs/ran_toks.pdf b/macros/latex/contrib/ran_toks/docs/ran_toks.pdf
new file mode 100644
index 0000000000..8896ea676c
--- /dev/null
+++ b/macros/latex/contrib/ran_toks/docs/ran_toks.pdf
Binary files differ
diff --git a/macros/latex/contrib/ran_toks/docs/rantoks_man.pdf b/macros/latex/contrib/ran_toks/docs/rantoks_man.pdf
new file mode 100644
index 0000000000..8d7c1e06e9
--- /dev/null
+++ b/macros/latex/contrib/ran_toks/docs/rantoks_man.pdf
Binary files differ
diff --git a/macros/latex/contrib/ran_toks/docs/rantoks_man.tex b/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
new file mode 100644
index 0000000000..c17c9e9a7e
--- /dev/null
+++ b/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
@@ -0,0 +1,689 @@
+\documentclass{article}
+\usepackage[fleqn]{amsmath}
+\usepackage[
+ web={centertitlepage,designv,forcolorpaper,
+ latextoc,pro}, %tight,
+ eforms,aebxmp
+]{aeb_pro}
+\usepackage{ran_toks}
+
+\useThisSeed{1441984427}
+%\useLastAsSeed
+%\useThisSeed{2001383846}
+
+%2001383846 % initializing seed value
+%1629639958 % last random number used
+
+\let\pkg\textsf
+\let\env\texttt
+
+%\rtdebugtrue
+%\ranToksOn
+%\ranToksOff
+
+
+%\usepackage{myriadpro}
+\usepackage[altbullet]{lucidbry}
+
+%\usepackage{makeidx}
+%\makeindex
+\usepackage{acroman}
+
+\makeatletter
+\def\eq@fititin#1{\noindent\unskip\nobreak\hfill\penalty50
+ \hskip2em\hbox{}\nobreak\hfill#1}
+\def\fitit{\eq@fititin{\exrtnlabelformat}}
+\@mparswitchfalse\reversemarginpar
+\renewcommand{\paragraph}
+ {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
+ {\normalfont\normalsize\bfseries}}
+\renewcommand{\subparagraph}
+ {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}%
+ {\normalfont\normalsize\bfseries}}
+\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
+\def\SUB#1{${}_{\text{#1}}$}
+
+\newdimen\aebdimen \aebdimen\topsep
+\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}%
+\def\eVerb{\vskip\aebdimen\endgroup\noindent}
+
+
+\urlstyle{rm}
+
+\DeclareDocInfo
+{
+ university={\AcroTeX.Net},
+ title={\texorpdfstring{The \textsf{ran\_toks}}{The manual for the ran\_toks}
+ Package\texorpdfstring{\\[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.2, 2019/12/28},
+ Keywords={LaTeX,PDF,random, tokens, JavaScript,Adobe Acrobat},
+ copyrightStatus=True,
+ copyrightNotice={Copyright (C) \the\year, D. P. Story},
+ copyrightInfoURL={http://www.acrotex.net}
+}
+\DeclareInitView{windowoptions={showtitle}}
+
+
+\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
+ \kern-.6em \hbox{$\mathcal S$}}$}
+
+\universityLayout{fontsize=Large}
+\titleLayout{fontsize=LARGE}
+\authorLayout{fontsize=Large}
+\tocLayout{fontsize=Large,color=aeb}
+\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
+\subsectionLayout{indent=-31.25pt,color=aeb}
+\subsubsectionLayout{indent=0pt,color=aeb}
+\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}
+
+\def\exSrc{\makebox[0pt][r]{\large{\Pisymbol{webd}{157}}\enspace}}
+
+%\pagestyle{empty}
+%\parindent0pt\parskip\medskipamount
+
+\chngDocObjectTo{\newDO}{doc}
+\begin{docassembly}
+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
+
+\selectColors{linkColor=black}
+\tableofcontents
+\selectColors{linkColor=webgreen}
+
+\section{Introduction}
+
+This is a short package for randomizing the order of tokens. The package
+is long overdue; users of \textbf{AeB} and of \textsf{eqexam} have long asked for a way to
+randomize the order of the problems in a test or quiz, or anything for
+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 \pkg{ran\_toks} to
+ randomize the \emph{questions} of an exam document created by the
+ \pkg{eqexam} package.
+ \item \texttt{random\_tst\_qz.tex} shows how to randomize choices of a
+ 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}
+
+The preamble for this package is
+\bVerb\takeMeasure{\string\usepackage\darg{ran\_toks}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single]
+\usepackage{ran_toks}
+\end{Verbatim}
+\end{minipage}\eVerb
+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.
+
+
+\section{The main commands and environments}\label{rtmain}
+
+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}
+
+The \cs{ranToks} command was the original concept; declare a series of
+tokens to be randomized.
+\bVerb\takeMeasure{\string\ranToks\darg{\meta{name}}\{\%\enspace}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\ranToks{!meta(name)}{%
+ {!meta(token!SUB(1))}
+ {!meta(token!SUB(2))}
+ ...
+ {!meta(token!SUB(n))}
+}
+\end{Verbatim}
+\end{minipage}\eVerb
+were \meta{token\SUB{k}} is any non-verbatim content;\footnote{Any token that
+can be in the argument of a command.} each token is enclosed in braces
+(\darg{}), this is required. The \meta{name} parameter is required, and
+must be unique for the document; it is used to build the names of internal
+macros. Of course several such \cs{ranToks} can be used in the document,
+either in the preamble or in the body of the document. Multiple
+\cs{ranToks} commands must have a different \meta{name} parameter.
+
+\emph{After} a \cs{ranToks} command has been executed, the number of tokens
+counted is accessible through the \cs{nToksFor} command,
+\bVerb\takeMeasure{\string\nToksFor\darg{\meta{name}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\nToksFor{!meta(name)}
+\end{Verbatim}
+\end{minipage}\eVerb
+The one argument is \meta{name}, and will expand to the total number
+of tokens listing as argument in the \cs{ranToks} command by the same
+name.
+
+The \cs{ranToks} command does not display the randomized tokens, for that
+the command \cs{useRanTok} is used.
+\bVerb\takeMeasure{\string\useRTName\darg{\meta{name}}}%
+\begin{minipage}{\bxSize}
+\begin{Verbatim}[frame=single,commandchars=!()]
+\useRanTok{!meta(num)}
+\useRTName{!meta(name)}
+\end{Verbatim}
+\end{minipage}\eVerb
+The argument of \cs{useRanTok} is a positive integer between 1 and
+\cs{nToksFor\darg{\meta{name}}}, the number of tokens declared by
+\cs{ranToks}, inclusive. There is no space created following the
+\cs{useRanTok} command, so if these are to be used ``inline'', enclose them
+in braces (\darg{}), for example, \darg{\cs{useRanTok\darg{1}}}. The use of
+\cs{useRTName} is optional unless the listing of the \cs{useRanTok} commands
+is separated from the \cs{ranToks} command that defined them by another
+\cs{ranToks} command of a different name. That should be clear!
+
+Consider this example.
+
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\ranToks{myPals}{%
+ {Jim}{Richard}{Don}
+ {Alex}{Tom}{J\"{u}rgen}
+}
+\end{Verbatim}
+\ranToks{myPals}{%
+ {Jim}{Richard}{Don}
+ {Alex}{Tom}{J\"{u}rgen}
+}
+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.)
+The verbatim listing is,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+I have {\nToksFor{myPals}} pals, they are \useRanTok{1},
+\useRanTok{2}, \useRanTok{3}, \useRanTok{4}, {\useRanTok{5}}
+and \useRanTok{6}.
+\end{Verbatim}
+Notice that \cs{useRanToks} are not enclosed in braces for 1--4 because
+they are each followed by a comma; the fifth token, \texttt{\darg{\cs{useRanTok\darg{5}}}}, is
+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}'', 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?
+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
+of \cs{ranToks} can pretty much be anything that is allowed to be an
+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}}
+ {\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{\% <-{\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% <-!sffamily( Begin token listing)
+\begin{rtVW}
+!qquad!ameta(content!SUB(1))
+\end{rtVW}
+...
+...
+\begin{rtVW}
+!qquad!ameta(content!SUB(n))
+\end{rtVW}
+!1\eRTVToks
+\end{Verbatim}
+\end{minipage}\eVerb
+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 (\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.
+
+The \env{rtWVW} environment also writes the command
+\cs{RTVWHook}\marginpar{\small\itshape\flushright\cs{RTVWHook}} to the top of
+the file. Its initial value is \cs{relax}. It can be redefined using the convenience
+command \cs{rtVWHook\darg{\ameta{arg}}}, which expands to
+\verb|\def\RTVWHook{|\ameta{arg}\verb|}|.
+
+The use of \cs{useRTName} and \cs{useRanTok} were explained and illustrated
+in the previous section. Let's go to the examples,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\bRTVToks{myThoughts}
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+Roses are red and violets are blue,
+I've forgotten the rest, have you too?
+\end{minipage}
+\end{rtVW}
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+I gave up saying bad things like
+\verb!$#%%%^*%^&#$@#! when I was just a teenager.
+\end{minipage}
+\end{rtVW}
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+I am a good guy, pass it on! The code for this last sentence is,
+\begin{verbatim}
+%#$% I am a good guy, pass it on! ^&*&^*
+\end{verbatim}
+How did that other stuff get in there?
+\end{minipage}
+\end{rtVW}
+\eRTVToks
+\end{Verbatim}
+OK, now, let's display these three in random order. Here we place them in
+an \texttt{enumerate} environment.
+
+\bRTVToks{myThoughts}%
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+Roses are red and violets are blue,
+I've forgotten the rest, have you too?
+\end{minipage}
+\end{rtVW}
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+I gave up saying bad things like
+\verb!$#%%%^*%^&#$@#! when I was just a teenager.
+\end{minipage}
+\end{rtVW}
+\begin{rtVW}
+\begin{minipage}[t]{.67\linewidth}
+I am a good guy, pass it on! The code for this last sentence is,
+\begin{verbatim}
+%#$% I am a good guy, pass it on! ^&*&^*
+\end{verbatim}
+How did that other stuff get in there?
+\end{minipage}
+\end{rtVW}
+\eRTVToks
+\begin{enumerate}
+ \item \useRanTok{1}
+ \item \useRanTok{2}
+ \item \useRanTok{3}
+\end{enumerate}
+The verbatim listing of the example above is
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\begin{enumerate}
+ \item \useRanTok{1}
+ \item \useRanTok{2}
+ \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
+explicitly listed as \cs{item \cs{useRanTok\darg{1}}} and so one; an
+alternate approach is to use the command \cs{displayListRandomly}, like so,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\begin{enumerate}
+ \displayListRandomly[\item]{myThoughts}
+\end{enumerate}
+\end{Verbatim}
+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[!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 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}.
+
+
+
+\section{Additional arguments and commands}\label{AddCmds}
+
+The syntax given earlier for \cs{useRanTok} was not completely specified.
+It is
+\bVerb\takeMeasure{\string\useRanTok[\meta{name}]\darg{\meta{num}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\useRanTok[!meta(name)]{!meta(num)}
+\end{Verbatim}
+\end{minipage}\eVerb
+The optional first parameter specifies the \meta{name} of the list from
+which to draw a random token; \meta{num} is the number of the
+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]{2}
+
+\newtopic\noindent The verbatim listing is
+\begin{Verbatim}[xleftmargin=\amtIndent]
+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}}.
+Without the \texttt{minipage}, the text would wrap around normally.
+
+\paragraph*{Accessing the original order.} The original order of the list of tokens is not lost, you can retrieve
+them using the command \cs{rtTokByNum},
+\bVerb\takeMeasure{\string\rtTokByNum[\meta{name}]\darg{\meta{num}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\rtTokByNum[!meta(name)]{!meta(num)}
+\end{Verbatim}
+\end{minipage}\eVerb
+This command expands to the token declared in the list named \meta{name}
+that appears at the \meta{num} place in the list. (Rather awkwardly written.)
+For example, my really best pals are {\rtTokByNum[myPals]{3}} and
+\rtTokByNum[myPals]{4}, but don't tell them. The listing is,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+For example, my really best pals are {\rtTokByNum[myPals]{3}}
+and \rtTokByNum[myPals]{4}, but don't tell them.
+\end{Verbatim}
+In some sense, \cs{rtTokByNum[\meta{name}]} acts like a simple array, the
+length of which is \cs{nToksFor\{\meta{name}\}}, and whose $k^{\text{th}}$
+element is \cs{rtTokByNum[\meta{name}]\{\meta{k}\}}.
+
+\paragraph*{Turning off randomization.} The randomization may be turned off
+using \cs{ranToksOff} or turned back on with \cs{ranToksOn}.
+\bVerb\takeMeasure{\string\ranToksOff\quad\string\ranToksOn}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\ranToksOff!quad\ranToksOn
+\end{Verbatim}
+\end{minipage}\eVerb
+This can be done globally in the preamble for the whole of the document,
+or in the body of the document just prior to either \cs{ranToks} or
+\cs{bRTVToks}. For example,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\ranToksOff
+\ranToks{integers}{ {1}{2}{3}{4} }
+\ranToksOn
+\end{Verbatim}
+As a check, executing `$\cs{useRanTok\darg{3}} = \cs{rtTokByNum\darg{3}} = 3 $' yields
+`\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.
+
+\paragraph*{The \textsf{ran\_toks} auxiliary file.} The package writes to a file named
+\cs{jobname\_rt.sav}, below represents two typical lines in this file.
+\begin{Verbatim}[xleftmargin=\amtIndent]
+1604051353 % initializing seed value
+5747283528 % last random number used
+\end{Verbatim}
+The first line is the initializing seed value used for the last
+compilation of the document; the second line is the last value of the
+pseudo-random number generator used in the document.
+
+Normally, the pseudo-random number generator provided by
+\texttt{random.tex} produces a new initial seed value every minute. So if
+you recompile again before another minute, you'll get the same initial
+seed value.
+
+\paragraph*{Controlling the initial seed value.} To obtain a new initial seed
+value each time you compile, place \cs{useLastAsSeed} in the preamble.
+\bVerb\takeMeasure{\string\useLastAsSeed}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single]
+\useLastAsSeed
+\end{Verbatim}
+\end{minipage}\eVerb
+When the document is compiled, the initial seed value taken as the second
+line in the \cs{jobname\_rt.sav} file, as seen in the above example.
+With this command in the preamble, a new set of random numbers is
+generated on each compile. If the file \cs{jobname\_rt.sav} does not
+exist, the generator will be initialized by its usual method, using the time and date.
+
+The command \cs{useThisSeed} allows you to reproduce a previous
+pseudo-random sequence.
+\bVerb\takeMeasure{\string\useThisSeed\darg{\meta{init\_seed\_value}}}%
+\begin{minipage}{\bxSize}\kern0pt
+\begin{Verbatim}[frame=single,commandchars=!()]
+\useThisSeed{!meta(init_seed_value)}
+\end{Verbatim}
+\end{minipage}\eVerb
+This command needs to be placed in the preamble. The value of
+\meta{init\_seed\_value} is an integer, normally taken from the
+first line of the \cs{jobname\_rt.sav} file.
+
+When creating tests (possibly using \textsf{eqexam}), the problems, or
+contiguous collections of problems, can be randomly ordered using the
+\cs{bRTVToks}/\penalty0\cs{eRTVToks} command pair paradigm. For example,
+suppose there are two classes and you want a random order (some of) the
+problems for each of the two classes. Proceed as follows:
+\begin{enumerate}
+\item Compile the document, open \cs{jobname\_rt.sav}, and copy the
+ first line (in the above example, that would be
+ \texttt{1604051353}).
+\item Place \cs{useThisSeed\darg{1604051353}} in the preamble. Compiling
+ will bring back the same pseudo-random sequence very time.
+\item Comment this line out, and repeat the process (use
+ \cs{useLastAsSeed} to generate new random sequences at each
+ compile) until you get another distinct randomization, open
+ \cs{jobname\_rt.sav}, and copy the first line again, say its \texttt{735794511}.
+\item Place \cs{useThisSeed\darg{735794511}} in the preamble.
+\item Label each
+\begin{Verbatim}
+%\useThisSeed{1604051353} % 11:00 class
+%\useThisSeed{735794511} % 12:30 class
+\end{Verbatim}
+To reproduce the random sequence for the class, just uncomment the random
+seed used for that class.
+\end{enumerate}
+If you are using \textsf{eqexam}, the process can be automated as follows:
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+\vA{\useThisSeed{1604051353}} % 11:00 class
+\vB{\useThisSeed{735794511}} % 12:30 class
+\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
+
+\end{document}