From ba67b1374de6f77b6df9d6f07e94a3854539010c Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 30 Dec 2019 22:17:36 +0000 Subject: ran_toks (30dec19) git-svn-id: svn://tug.org/texlive/trunk@53271 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/ran_toks/README.md | 5 +- .../doc/latex/ran_toks/doc/rantoks_man.pdf | Bin 224675 -> 0 bytes .../doc/latex/ran_toks/doc/rantoks_man.tex | 683 -------------------- .../doc/latex/ran_toks/docs/ran_toks.pdf | Bin 0 -> 106437 bytes .../doc/latex/ran_toks/docs/rantoks_man.pdf | Bin 0 -> 226760 bytes .../doc/latex/ran_toks/docs/rantoks_man.tex | 689 +++++++++++++++++++++ .../doc/latex/ran_toks/examples/mc-db.tex | 2 +- 7 files changed, 694 insertions(+), 685 deletions(-) delete mode 100644 Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf delete mode 100644 Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex create mode 100644 Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf create mode 100644 Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf create mode 100644 Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.tex (limited to 'Master/texmf-dist/doc/latex/ran_toks') diff --git a/Master/texmf-dist/doc/latex/ran_toks/README.md b/Master/texmf-dist/doc/latex/ran_toks/README.md index 6e47bf5109b..c4c67686b7a 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: 2017/05/04 +Dated: 2019-12-28 This short package, with minimal requirements, defines macros for randomizing a list of tokens. There are two approaches: @@ -40,6 +40,9 @@ 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 (2019-12-28 ) Defined \rtVWHook to insert at the top of the +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. 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 deleted file mode 100644 index 66c8f3cbfd0..00000000000 Binary files a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex deleted file mode 100644 index 2776e3863db..00000000000 --- a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex +++ /dev/null @@ -1,683 +0,0 @@ -\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.1}, - 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 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} 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 new file mode 100644 index 00000000000..8896ea676cb Binary files /dev/null and b/Master/texmf-dist/doc/latex/ran_toks/docs/ran_toks.pdf differ 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 new file mode 100644 index 00000000000..8d7c1e06e9e Binary files /dev/null and b/Master/texmf-dist/doc/latex/ran_toks/docs/rantoks_man.pdf differ 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 new file mode 100644 index 00000000000..c17c9e9a7e4 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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} 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 index 0e8ceab7b7d..1eb2ce548a5 100644 --- a/Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex +++ b/Master/texmf-dist/doc/latex/ran_toks/examples/mc-db.tex @@ -34,7 +34,7 @@ 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 +This part demonstrates how to not only randomly pull problems (two from each of the DB files), but to randomize the order they are listed in the exam. \end{instructions} -- cgit v1.2.3