summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ran_toks/docs
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-01-26 03:01:06 +0000
committerNorbert Preining <norbert@preining.info>2021-01-26 03:01:06 +0000
commit94ac70b92400e4b95d43d570ad53a713c036118b (patch)
treef312a316fd2dc7070b7550ece5dbb3d25be5f480 /macros/latex/contrib/ran_toks/docs
parent31152d888efa58265aef8521042ad58c300f9576 (diff)
CTAN sync 202101260301
Diffstat (limited to 'macros/latex/contrib/ran_toks/docs')
-rw-r--r--macros/latex/contrib/ran_toks/docs/ran_toks.pdfbin106437 -> 284544 bytes
-rw-r--r--macros/latex/contrib/ran_toks/docs/rantoks_man.pdfbin226760 -> 255885 bytes
-rw-r--r--macros/latex/contrib/ran_toks/docs/rantoks_man.tex431
3 files changed, 351 insertions, 80 deletions
diff --git a/macros/latex/contrib/ran_toks/docs/ran_toks.pdf b/macros/latex/contrib/ran_toks/docs/ran_toks.pdf
index 8896ea676c..bfc8e7bc9b 100644
--- a/macros/latex/contrib/ran_toks/docs/ran_toks.pdf
+++ 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
index 8d7c1e06e9..62ee68da81 100644
--- a/macros/latex/contrib/ran_toks/docs/rantoks_man.pdf
+++ 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
index c17c9e9a7e..8f8b0c6246 100644
--- a/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
+++ b/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
@@ -1,8 +1,9 @@
+\RequirePackage[!use=preview,!use=efpmca,!use=usebw]{spdef}
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
web={centertitlepage,designv,forcolorpaper,
- latextoc,pro}, %tight,
+ latextoc,extended},
eforms,aebxmp
]{aeb_pro}
\usepackage{ran_toks}
@@ -16,6 +17,7 @@
\let\pkg\textsf
\let\env\texttt
+\let\opt\textsf
%\rtdebugtrue
%\ranToksOn
@@ -50,6 +52,19 @@
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
+\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{%
+ \raisebox{.5\baselineskip+#1}{%
+ \expandafter\parbox\expandafter[\parboxValign]%
+ {\marginparwidth}{\aebbkFmtMp#2}}}}
+\def\aebbkFmtMp{\kern0pt\itshape\small
+ \ifusebw\color{gray}\else\color{blue}\fi
+ \raggedleft\hspace{0pt}}\newcommand{\BlogArticle}{%
+ \makebox[0pt][l]{\hspace{-1pt}\color{blue}\Pisymbol{webd}{254}%
+ }\raisebox{.5pt}{\ifusebw\color{black}\else
+ \color{red}\fi\ding{045}}}
+\def\parboxValign{t}
+
+
\usepackage[active]{srcltx}
\let\amtIndent\leftmargini
@@ -72,8 +87,8 @@
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},
+ version={1.3.1, 2021/01/19},
+ Keywords={LaTeX, PDF, random, tokens, JavaScript, Adobe Acrobat},
copyrightStatus=True,
copyrightNotice={Copyright (C) \the\year, D. P. Story},
copyrightInfoURL={http://www.acrotex.net}
@@ -155,37 +170,65 @@ _path=_path.substring(0,pos)+"/"+manualfilename;
\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
+is long overdue; users of \textsf{\textbf{AeB}} and of \pkg{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:
+\newtopic\noindent\exSrc The \texttt{examples} folder contains nine 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
+ \item \texttt{ran-toks.tex} reproduces the sample code of this manual.
+ \item \texttt{rt-tst-eqe.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
+ \item \texttt{rt-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
+ \item \texttt{rt-cb.tex} is a demonstration of how to use the
+ \pkg{collectbox} package to place verbatim content into a token list
+ (see \cs{ranToks}, \hyperref[s:ranToks]{Section~\ref*{s:ranToks}}).
+\xdef\svEnumi{\the\value{enumi}}
+\end{enumerate}
+The next five files concern the DB application and require the \opt{usedbapp} option,
+they are discussed in \hyperref[s:DBApp]{Section~\ref*{s:DBApp}}.
+\begin{enumerate}\setcounter{enumi}{\svEnumi}
+ \item \texttt{mc-db.tex} is an \pkg{eqexam} file, 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.
+ to \hyperref[s:DBApp]{Section~\ref*{s:DBApp}} for a few more details.
+ \item \texttt{mc-dbu.tex} is an \pkg{eqexam} file that draws from the
+ database test file, 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. However, \texttt{mc-dbu.tex}
+ differs from \texttt{mc-db.tex} for it selects unique questions
+ cross the four versions of the document. Refer to
+ \hyperref[s:DBApp]{Section~\ref*{s:DBApp}} for a few more details.
+ \item \texttt{viewDB.tex} A demo file of how to view the DB files for
+ the purpose of reviewing the questions, modifying them, or adding
+ to them.
+ \item \texttt{mc-dbu-ctrld.tex} is a variation on \texttt{mc-dbu.tex},
+ it is not meant to be compiled directly, but by the file
+ \texttt{ctrl-build.tex}.
+ \item \texttt{ctrl-build.tex} is a simple TEX file that controls the
+ compilation of a targeted file (\texttt{mc-dbu-ctrld.tex} in this
+ example) over the various versions supported by the targeted file.
+ Try it, you'll like it. Uses the \pkg{shellesc} package to control
+ the process.
\end{enumerate}
\section{The Preamble and Package Options}
The preamble for this package is
-\bVerb\takeMeasure{\string\usepackage\darg{ran\_toks}}%
+\bVerb\takeMeasure{\string\usepackage[\ameta{options}]\darg{ran\_toks}}%
\begin{minipage}{\bxSize}\kern0pt
-\begin{Verbatim}[frame=single]
-\usepackage{ran_toks}
+\begin{Verbatim}[frame=single,commandchars=!()]
+\usepackage[!ameta(options)]{ran_toks}
\end{Verbatim}
\end{minipage}\eVerb
-The package itself has no options.
+The one option of \pkg{ran\_toks} is \opt{usedbapp}\FmtMP{\opt{usedbapp} option}, which brings in
+specialized code to support a database test application. This option is
+discussed in \hyperref[s:DBApp]{Section~\ref*{s:DBApp}}, beginning on page~\pageref*{s:DBApp}.
The requirements for \textsf{ran\_toks} are the \textsf{verbatim} package
(part of the standard {\LaTeX} distribution, and the macro file
@@ -198,52 +241,52 @@ 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}
+\subsection{The \texorpdfstring{\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.
-\bVerb\takeMeasure{\string\ranToks\darg{\meta{name}}\{\%\enspace}%
+\bVerb\takeMeasure{\string\ranToks\darg{\ameta{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))}
+\ranToks{!ameta(name)}{%
+!quad{!ameta(token!SUB(1))}
+!quad{!ameta(token!SUB(2))}
+!quad...
+!quad{!ameta(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
+were \ameta{token\SUB{k}} is any non-verbatim content;\footnote{However, for workarounds, see
+\texttt{rt-cb.tex} and \texttt{rt-tst-qz.tex.}} each token is enclosed in braces
+(\darg{}), this is required. The \ameta{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.
+\cs{ranToks} commands must have a different \ameta{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}}}%
+\bVerb\takeMeasure{\string\nToksFor\darg{\ameta{name}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\nToksFor{!meta(name)}
+\nToksFor{!ameta(name)}
\end{Verbatim}
\end{minipage}\eVerb
-The one argument is \meta{name}, and will expand to the total number
+The one argument is \ameta{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}}}%
+\bVerb\takeMeasure{\string\useRTName\darg{\ameta{name}}}%
\begin{minipage}{\bxSize}
\begin{Verbatim}[frame=single,commandchars=!()]
-\useRanTok{!meta(num)}
-\useRTName{!meta(name)}
+\useRanTok{!ameta(num)}
+\useRTName{!ameta(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{nToksFor\darg{\ameta{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
@@ -285,10 +328,10 @@ arguments.\footnote{{\ttfamily\string\ranToks\darg{myPals}\darg{\darg{Jim}\darg{
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}}}%
+\bVerb\takeMeasure{\string\reorderRanToks\darg{\ameta{name}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\reorderRanToks{!meta(name)}
+\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
@@ -297,7 +340,7 @@ An alternative to re-executing \cs{ranToks} is to use the \cs{reorderRanToks} co
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
+The \cs{reorderRanToks\darg{\ameta{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
@@ -327,36 +370,55 @@ and verbatim environments.
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}}}%
+\bVerb\takeMeasure{\string\bRTVToks\darg{\ameta{name}}}%
+%\edef\WIDTH{\the\wd\webtempboxi}%
+\def\1{\rlap{\hspace*{\linewidth}\texttt{\%{\sffamily{ \raisebox{1pt}{<--}Begin token listing}}}}}%
+\def\2{\rlap{\hspace*{\linewidth}\texttt{\%{\sffamily{ \raisebox{1pt}{<--}End token listing}}}}}%
+%\takeMeasure{\string\bRTVToks\darg{\ameta{name}}\quad\%{\sffamily{ <-Begin token listing}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\bRTVToks{!meta(name)}!quad% <-!sffamily( Begin token listing)
+!1\bRTVToks{!ameta(name)}
\begin{rtVW}
-!qquad!ameta(content!SUB(1))
+!quad!ameta(content!SUB(1))
\end{rtVW}
...
...
\begin{rtVW}
-!qquad!ameta(content!SUB(n))
+!quad!ameta(content!SUB(n))
\end{rtVW}
-!1\eRTVToks
+!2\eRTVToks
\end{Verbatim}
\end{minipage}\eVerb
-The \cs{bRTVToks}\texttt{\{\meta{name}\}} command begins the (pseudo)
+%\bVerb\takeMeasure{\string\bRTVToks\darg{\ameta{name}}\quad}%
+%\edef\WIDTH{\the\wd\webtempboxi}%
+%\def\1{\rlap{\hspace*{\WIDTH}\texttt{\% <-{\sffamily{ End token listing}}}}}%
+%\takeMeasure{\string\bRTVToks\darg{\ameta{name}}\quad\% <-{\sffamily{ Begin token listing}}}%
+%\begin{minipage}{\bxSize}\kern0pt
+%\begin{Verbatim}[frame=single,commandchars=!()]
+%\bRTVToks{!ameta(name)}!quad% <-!sffamily( Begin token listing)
+%\begin{rtVW}
+%!quad!ameta(content!SUB(1))
+%\end{rtVW}
+%...
+%...
+%\begin{rtVW}
+%!quad!ameta(content!SUB(n))
+%\end{rtVW}
+%!1\eRTVToks
+%\end{Verbatim}
+%\end{minipage}\eVerb
+The \cs{bRTVToks}\texttt{\darg{\ameta{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}
+(based on the parameter \ameta{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
+The \env{rtVW} 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
+the file. Its initial value is \cs{relax}. It can be redefined with
+\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
@@ -436,7 +498,7 @@ The command \cs{copyRanToks} works for list created by
\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
+explicitly listed as \cs{item \cs{useRanTok\darg{1}}} and so on; an
alternate approach is to use the command \cs{displayListRandomly}, like so,
\begin{Verbatim}[xleftmargin=\amtIndent]
\begin{enumerate}
@@ -444,17 +506,17 @@ alternate approach is to use the command \cs{displayListRandomly}, like so,
\end{enumerate}
\end{Verbatim}
The full syntax for \cs{displayListRandomly} is displayed next.
-\bVerb\takeMeasure{\string\displayListRandomly[\ameta{prior}][\ameta{post}]\darg{\meta{name}}}%
+\bVerb\takeMeasure{\string\displayListRandomly[\ameta{prior}][\ameta{post}]\darg{\ameta{name}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\displayListRandomly[!ameta(prior)][!ameta(post)]{!meta(name)}
+\displayListRandomly[!ameta(prior)][!ameta(post)]{!ameta(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
+are listed in the \ameta{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
+goes from~1 to \cs{nToksFor\darg{\ameta{name}}}. In the example above,
+\ameta{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,
@@ -492,16 +554,16 @@ 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}}}%
+It is,
+\bVerb\takeMeasure{\string\useRanTok[\ameta{name}]\darg{\ameta{num}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\useRanTok[!meta(name)]{!meta(num)}
+\useRanTok[!ameta(name)]{!ameta(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}}},
+The optional first parameter specifies the \ameta{name} of the list from
+which to draw a random token; \ameta{num} is the number of the
+token in the range of 1 and \cs{nToksFor\darg{\ameta{name}}},
inclusive. The optional argument is useful in special circumstances when
you want to mix two random lists together.
@@ -517,23 +579,23 @@ 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}}}%
+\bVerb\takeMeasure{\string\rtTokByNum[\ameta{name}]\darg{\ameta{num}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\rtTokByNum[!meta(name)]{!meta(num)}
+\rtTokByNum[!ameta(name)]{!ameta(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.)
+This command expands to the token declared in the list named \ameta{name}
+that appears at the \ameta{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}\}}.
+In some sense, \cs{rtTokByNum[\ameta{name}]} acts like a simple array, the
+length of which is \cs{nToksFor\{\ameta{name}\}}, and whose $k^{\text{th}}$
+element is \cs{rtTokByNum[\ameta{name}]\{\ameta{k}\}}.
\paragraph*{Turning off randomization.} The randomization may be turned off
using \cs{ranToksOff} or turned back on with \cs{ranToksOn}.
@@ -596,7 +658,7 @@ Normally, the pseudo-random number generator provided by
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
+\paragraph*{Controlling the initial seed value.}\label{para:ControlSeed} 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
@@ -612,14 +674,14 @@ exist, the generator will be initialized by its usual method, using the time and
The command \cs{useThisSeed} allows you to reproduce a previous
pseudo-random sequence.
-\bVerb\takeMeasure{\string\useThisSeed\darg{\meta{init\_seed\_value}}}%
+\bVerb\takeMeasure{\string\useThisSeed\darg{\ameta{init\_seed\_value}}}%
\begin{minipage}{\bxSize}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
-\useThisSeed{!meta(init_seed_value)}
+\useThisSeed{!ameta(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
+\ameta{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
@@ -653,17 +715,47 @@ 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}
+\section{Commands to support a DB application}\label{s:DBApp}
+
+The commands described in this section are only available with the \opt{usedbapp} option,
+\begin{Verbatim}
+\usepackage[usedbapp]{ran_toks}
+\end{Verbatim}
+This option was designed for an \pkg{eqexam} document.
+
+\subsection{Basic functionality}\label{s:basicFunc}
+
+The premise here is that you have an \pkg{eqexam} document (a test) and you have a series
+of standard questions you ask students. Over the years, you have accumulated questions of a similar type
+that you like to pose to your students. The questions of a similar type are placed in a DB test file. For example,
+you have a file named \texttt{db1.tex} containing questions on a certain narrow topic. The format for this file
+is,
+\begin{Verbatim}[commandchars=!()]
+%
+% !textsf(Questions on some narrow topic)
+%
+\bRTVToks{DB1} %<-!textsf(DB !ameta(name))
+\begin{rtVW}
+% !textsf(an !pkg(eqexam) question is contained in this rtVW environment)
+\end{rtVW}
+\begin{rtVW}
+% !textsf(an !pkg(eqexam) question is contained in this rtVW environment)
+\end{rtVW}
+...
+\eRTVToks
+\end{Verbatim}
+Refer to the file \texttt{db1.tex}, \texttt{db2.tex},\dots, \texttt{db4.tex} for more specific
+examples. The DB \ameta{name} must be unique among all the DB test files used.
-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}:
+The next step is to input your DB files. To do this, execute either of the commands
+\cs{useTheseDBs} or \cs{useProbDBs} prior to the opening of an \env{exam} environment (\pkg{eqexam}),
+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}}}}%
-\begin{minipage}{\bxSize}\kern0pt
+\setlength\eflength{\bxSize}%
+\begin{minipage}{\bxSize}\kern0pt\def\1{\rlap{\sffamily\hskip\eflength(An alias for \cs{useTheseDBs})}}\relax
\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))}
+!1\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
@@ -678,11 +770,190 @@ emitted if one or more of the files are not found. The default extension is
\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.
+Once the database files have been input, in the body of the document you can extract
+questions using \cs{useRanTok}; for example, \cs{useRanTok[DB1]\darg{1}} extracts the question
+with an index of 1 from the database file DB1;\footnote{It is assumed that DB1 is the \ameta{name}
+is the required argument of \cs{bRTVToks}, which is declared in the \texttt{db1.tex} file.} \cs{useRanTok[DB2]\darg{2}} extracts the question
+with an index of 2 from the database file DB2, and so on.
Refer to the demonstration file \texttt{mc-db.tex} for an example.
+\subsection{Striving for uniqueness of choices}
+
+By default, when you expand \cs{useRanTok\darg{1}} and later you expand
+\cs{useRanTok\darg{1}} again you get the exact same result;\footnote{Here, we
+are assuming the \ameta{name} of the token list is the same for both
+expansions of \cs{useRanTok\darg{1}}.} this is the normal behavior. However,
+in the context of posing questions from a database of questions, repeating
+the questions is not what is wanted necessarily. In the next two subsections,
+we speak to the problem, first within a single-version document, and
+secondly, within a multi-version document.
+
+
+\subsubsection{For documents with a single version}
+
+The issue of not wanting to repeat a question from a database comes up when
+you want to pose several questions from a given database file. We illustrate
+using the demo file \texttt{mc-db.tex} found in the \texttt{examples} folder.
+In that file, the exam has two parts, as shown in
+\hyperref[fig:2prts]{Figure~\ref*{fig:2prts}}.\footnote{The verbatim listing
+here has been simplified.}
+\begin{figure}[htb]\centering
+\settowidth{\eflength}{\ttfamily\string\useRanTok[DB1]\darg{1}}%
+\edef\x{\the\eflength}%
+\setlength\eflength{\x+\widthof{\textsf{\quad\%An alternate approach}\texttt{ }}}%
+\def\0{\rlap{\hskip\x\relax\quad\% \textsf{An alternate approach}}}%
+\def\1{\rlap{\hskip\x\relax\quad\% \cs{begin\darg{Part2}}}}%
+\def\2{\rlap{\hskip\x\relax\quad\% \cs{useRanTok[DB1]\darg{3}}}}%
+\def\3{\rlap{\hskip\x\relax\quad\% \cs{useRanTok[DB1]\darg{4}}}}%
+\def\4{\rlap{\hskip\x\relax\quad\% \cs{end\darg{Part2}}}}%
+\fboxsep0pt
+\begin{minipage}{\eflength}
+\begin{Verbatim}[commandchars=!()]
+\begin{Part1}
+\useRanTok[DB1]{1}
+\useRanTok[DB1]{2}
+\end{Part1}
+
+!0% !textsf( First approach)
+!1\begin{Part2}
+!2\useRanTok[DB1]{1}
+!3\useRanTok[DB1]{2}
+!4\end{Part2}
+\end{Verbatim}
+\end{minipage}
+\caption{Simplified two-part exam}\label{fig:2prts}
+\end{figure}
+For \textsf{Part1}, we take two problems (at random) from \textsf{DB1}. In
+\textsf{Part2}, we take two problems again from \textsf{DB1}; these two will
+be the \emph{same} as the ones chosen from \textsf{Part1}. To get two
+\emph{different} questions the natural approach is to write
+\cs{useRanTok[DB1]\darg{3}} and \cs{useRanTok[DB1]\darg{4}}, as shown on the
+right in \hyperref[fig:2prts]{Figure~\ref*{fig:2prts}}. Now, returning to the \textsf{First approach}, there is a way of forcing
+\pkg{ran\_toks} to choose two different question even though the indexes used are the same.
+
+To have different questions appear when you specify \verb~\useRanTok[DB1]{1}~
+and \verb~\useRanTok[DB1]{2}~, first expand the command
+\cs{uniqueXDBChoicesOn}, perhaps between parts or in the preamble. When
+\cs{uniqueXDBChoicesOn} is expanded, \cs{useRanTok} tries to find an
+``unused'' choice.
+\begin{Verbatim}[xleftmargin=\parindent,commandchars=!()]
+\uniqueXDBChoicesOn
+\begin{document}
+...
+\begin{Part1}
+\useRanTok[DB1]{1}
+\useRanTok[DB1]{2}
+\end{Part1}
+
+%\uniqueXDBChoicesOn
+
+\begin{Part2}
+\useRanTok[DB1]{1}
+\useRanTok[DB1]{2}
+\end{Part2}
+\end{Verbatim}
+The command \cs{uniqueXDBChoicesOff} turns off the feature of striving to
+find ``unused'' choices. Additional discussion on \cs{uniqueXDBChoicesOn} is
+found in the next section; the command \cs{InputUsedIDs}, discussed in the
+next section, is not needed when the \pkg{eqexam} document \emph{does not
+have} multiple versions. You can experiment with striving to find unused
+questions in the demo file \texttt{mc-db.tex}.
+
+\subsubsection{For documents with multiple versions}
+
+The scheme outlined in \hyperref[s:basicFunc]{Section~\ref*{s:basicFunc}} works well for an
+\pkg{eqexam} document that only has one version in the source file. The way
+\pkg{ran\_toks} works, it will not repeat random choices --- unless you
+sample from a same DB file more times than there are problems in that file;
+for example, suppose \texttt{db1.tex} has two questions in it, if you execute
+\cs{useRanTok[DB1]\darg{1}}, \cs{useRanTok[DB1]\darg{2}}, and
+\cs{useRanTok[DB1]\darg{3}}, then the problem selected by
+\cs{useRanTok[DB1]\darg{3}} is the same as \cs{useRanTok[DB1]\darg{1}}. This
+latter situation is not likely, is it?
+
+One of the very powerful features of \pkg{eqexam} is that a single source
+file can have multiple versions in it.
+\begin{Verbatim}[xleftmargin=\parindent,commandchars=!()]
+\examNum{1}
+\numVersions{4}
+\forVersion{a} %!textsf( a, b, c, d)
+\vA{\useThisSeed{54356}}
+\vB{\useThisSeed{577867}}
+\vC{\useThisSeed{6746788}}
+\vD{\useThisSeed{856785}}
+\end{Verbatim}
+The above shows how to set up a multi-version \pkg{eqexam} document, see the
+\pkg{eqexam} documentation for more details. Here, as in the demo file
+\texttt{mc-dbu.tex}, we declare 4 versions (a, b, c, and d).
+\cs{forVersion\darg{a}} declares the next compile is for version a (or A,
+either one). List also is a method of passing an initial seed to the
+pseudo-random number generator, for each version. (These can be arbitrarily
+typed in, or obtained by the methods discussed in
+\textbf{\nameref{para:ControlSeed}} on page~\pageref*{para:ControlSeed}.)
+
+\paragraph*{The problem.} For a multi-version \pkg{eqexam} document, where
+each version samples from the same set of DB Test files, later versions of the exam
+may have questions that are repeats of the ones posed in earlier versions of
+the same source file. This may or may not be a problem if the different
+versions are given to different classes at approximately the same time where
+there is no opportunity for the details of the test to ``leak out'' from one
+class to another.
+
+\paragraph*{The solution.} The solution to this problem requires the introduction of several
+new commands.
+\bVerb\takeMeasure{\string\uniqueXDBChoicesOn}%
+\setlength\eflength{\bxSize}%
+\begin{minipage}{\bxSize}\kern0pt\def\1{\rlap{\sffamily\hskip\eflength\%\textsf{ to view the IDs of problems used}}}\relax
+\def\2{\rlap{\sffamily\hskip\eflength\%\textsf{ preamble only (required)}}}\relax
+\def\3{\rlap{\sffamily\hskip\eflength\%\textsf{ there is also \cs{uniqueXDBChoicesOff} (the default)}}}\relax
+\begin{Verbatim}[frame=single,commandchars=!()]
+!3\uniqueXDBChoicesOn
+!2\InputUsedIDs
+!1%\viewIDstrue
+\end{Verbatim}
+\end{minipage}\eVerb The \cs{uniqueXDBChoicesOn} command
+brings some special code into the \cs{useRanTok} command; this special code
+tries to select problems that have not already been selected by earlier
+versions of the source document. Key to this selection process is that the
+special code needs to know which questions were earlier selected; that is the
+role of the \cs{InputUsedIDs}. This latter command uses the value declared in
+\cs{numVersions}, so it must appear \emph{after} the declaration of the
+number of versions.
+
+When \cs{uniqueXDBChoicesOn} is expanded, as the source document is compiled,
+an auxiliary file named \cs{jobname-ver\ameta{Ltr}.cut} is written. This
+file keeps a record of the problem ID of the problems selected, believe it or
+not. \cs{InputUsedIDs} inputs the appropriate CUT files:
+\begingroup\tightsettings
+\begin{itemize}
+\item for version B, \cs{jobname-verA.cut} is input;
+\item for version C, \cs{jobname-verA.cut}, \cs{jobname-verB.cut} are input;
+\item for version D, \cs{jobname-verA.cut}, \cs{jobname-verB.cut}, \cs{jobname-verC.cut} are input;
+\item and so on.
+\end{itemize}
+\endgroup\noindent
+In this way, when you compile version \ameta{Ltr}, the document inputs all
+the information it needs about previous versions to make in informed choice.
+
+\paragraph*{Workflow.} When compiling a multi-version \pkg{eqexam} document, do the following:
+\begin{enumerate}
+ \item Build each version in \emph{alphabetical order}, that is, compile with \cs{forVersion\darg{a}},
+ then \cs{forVersion\darg{b}}, and so on.
+ \item Rename PDF produced to reflect the version \ameta{Ltr}; eg, \verb~\jobname-verA.pdf~ or
+ \verb!\jobname-sec02.pdf!, or whatever.\footnote{The demo file \texttt{ctrl-build.tex} shows
+ how to build all versions and rename the final PDF files all from one controlling file.}
+\end{enumerate}
+
+%\paragraph*{Final comments.} \cs{uniqueXDBChoicesOn} does several things, it causes \cs{useRanTok}
+%to use some special code to ensure cross-version uniqueness of choices, but
+%it also initiates writing of the choice history to the auxiliary CUT files
+%\cs{jobname-ver\ameta{Ltr}.cut}. By placing \cs{uniqueXDBChoicesOff} in
+%the body of the document (outside a group, perhaps) that turns off the
+%execution of the special code as well and writing to the CUT files. I believe
+%you can later in the document turn this back on with \cs{uniqueXDBChoicesOn},
+%though I have not done a lot of testing of this.
+
\newtopic\noindent
Now, I simply must get back to my retirement. \dps