diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex | 284 |
1 files changed, 184 insertions, 100 deletions
diff --git a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex index ffe4d67bd64..b36612f1590 100644 --- a/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex +++ b/Master/texmf-dist/doc/latex/ran_toks/doc/rantoks_man.tex @@ -2,12 +2,19 @@ \usepackage[fleqn]{amsmath} \usepackage[ web={centertitlepage,designv,forcolorpaper, - usesf,latextoc,pro}, %tight, + latextoc,pro}, %tight, eforms,aebxmp ]{aeb_pro} \usepackage{ran_toks} -\useThisSeed{1441984427} + +%\useThisSeed{1441984427} %\useLastAsSeed +\useThisSeed{2001383846} + +%2001383846 % initializing seed value +%1629639958 % last random number used + + %\rtdebugtrue %\ranToksOn %\ranToksOff @@ -25,11 +32,29 @@ \hskip2em\hbox{}\nobreak\hfill#1} \def\fitit{\eq@fititin{\exrtnlabelformat}} \@mparswitchfalse\reversemarginpar -%\def\meta#1{$\langle\textit{\texttt{#1}}\rangle$} +\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$} \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} -\makeatother -%\usepackage[active]{srcltx} \urlstyle{rm} @@ -43,7 +68,7 @@ email={dpstory@acrotex.net}, subject=Documentation for the ran\_toks package, talksite={\url{www.acrotex.net}}, - version={1.0}, + version={1.0e}, Keywords={LaTeX,PDF,random, tokens, JavaScript,Adobe Acrobat}, copyrightStatus=True, copyrightNotice={Copyright (C) \the\year, D. P. Story}, @@ -67,8 +92,7 @@ \def\exSrc{\makebox[0pt][r]{\large{\Pisymbol{webd}{157}}\enspace}} %\pagestyle{empty} -\parindent0pt -\parskip\medskipamount +%\parindent0pt\parskip\medskipamount \definePath\bgPath{"C:/Users/Public/Documents/% @@ -96,21 +120,31 @@ is long overdue; users of \textbf{AeB} and of \textsf{eqexam} have long asked fo randomize the order of the problems in a test or quiz, or anything for that matter. -\exSrc The example file for this package is \texttt{ran\_toks.tex} found in the -\texttt{examples} folder. The file reproduces the sample code of this -manual. +\newtopic\noindent\exSrc The \texttt{examples} folder contains three demonstration files: +\begin{enumerate} + \item \texttt{ran\_toks.tex} reproduces the sample code of this manual. + \item \texttt{random\_tst.tex} shows how to use \textsf{ran\_toks} to + randomize the \emph{questions} of an exam document created by the + \textsf{eqexam} package. + \item \texttt{random\_tst\_qz.tex} shows how to randomize choices of a + multiple choice field in a \texttt{quiz} environment of the + \textsf{exerquiz} package, when the choices contain verbatim text. +\end{enumerate} \section{The Preamble and Package Options} The preamble for this package is -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\usepackage{ran_toks}) +\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 +\texttt{random.tex} by Donald Arseneau \section{The main commands and environments}\label{rtmain} @@ -124,17 +158,20 @@ command}{\CMD{ranToks}} command} The \cs{ranToks} command was the original concept; declare a series of tokens to be randomized. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(!parbox(1.5in)(\ranToks{!meta(name)}{% - {!meta(token_1)} - {!meta(token_2)} +\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_n)} -})) + {!meta(token!SUB(n))} +} \end{Verbatim} -were \meta{token\_k} is any non-verbatim content;\footnote{Any token that +\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 -(\verb!{}!), this is required. The \meta{name} parameter is required, and +(\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 @@ -142,34 +179,37 @@ either in the preamble or in the body of the document. Multiple \emph{After} a \cs{ranToks} command has been executed, the number of tokens counted is accessible through the \cs{nToksFor} command, -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\nToksFor{!meta(name)}) +\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. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(!parbox(1.3in)(\useRTName{!meta(name)} -\useRanTok{1} -\useRanTok{2} -... -\useRanTok{n})) +\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 -\verb!\nToksFor{!\meta{name}\verb!}!, 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 (\verb~{}~), eg, -\verb!{\useRanTok{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! +\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=20pt,commandchars=!()] +\begin{Verbatim}[xleftmargin=\amtIndent] \ranToks{myPals}{% {Jim}{Richard}{Don} {Alex}{Tom}{J\"{u}rgen} @@ -183,13 +223,13 @@ 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=20pt,commandchars=!()] +\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, \verb!{useRanTok{5}}!, is +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 @@ -214,33 +254,38 @@ and verbatim environments. \texorpdfstring{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}} {\CMD{bRTVToks}/\CMD{eRTVToks}} pair of commands} -Sometimes the content to be randomized is quite large and contain verbatim +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}/\cs{eRTVToks} command pair. The syntax is -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(!parbox(1.6in)(\bRTVToks{!meta(name)} +\cs{bRTVToks}/\penalty0\cs{eRTVToks} command pair. The syntax is +\bVerb\takeMeasure{\string\bRTVToks\darg{\meta{name}}\quad}% +\edef\WIDTH{\the\wd\webtempboxi}% +\def\1{\rlap{\hspace*{\WIDTH}\texttt{\% End token listing}}}% +\takeMeasure{\string\bRTVToks\darg{\meta{name}}\quad\% <- Begin token listing}% +\begin{minipage}{\bxSize}\kern0pt +\begin{Verbatim}[frame=single,commandchars=!()] +\bRTVToks{!meta(name)}!quad% <- Begin token listing \begin{rtVW} - !meta(content) + !anglemeta(content!SUB(1)) \end{rtVW} ... ... \begin{rtVW} - !meta(content) + !anglemeta(content!SUB(n)) \end{rtVW} -\eRTVToks)) +!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 of each of these environments is written to the -disk 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. +environment and is ended by \cs{eRTVToks}. Between these two are a series of +\texttt{rtVW} (random toks verbatim write) environments. When the document is +compiled, the contents (\anglemeta{content\SUB{i}}) of each of these environments +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=20pt,commandchars=!()] +\begin{Verbatim}[xleftmargin=\amtIndent] \bRTVToks{myThoughts} \begin{rtVW} \begin{minipage}[t]{.67\linewidth} @@ -251,7 +296,7 @@ I've forgotten the rest, have you too? \begin{rtVW} \begin{minipage}[t]{.67\linewidth} I gave up saying bad things like -\verb!$#%%%^*%^&#$@#! when I was just a teenager +\verb!$#%%%^*%^&#$@#! when I was just a teenager. \end{minipage} \end{rtVW} \begin{rtVW} @@ -278,7 +323,7 @@ I've forgotten the rest, have you too? \begin{rtVW} \begin{minipage}[t]{.67\linewidth} I gave up saying bad things like -\verb!$#%%%^*%^&#$@#! when I was just a teenager +\verb!$#%%%^*%^&#$@#! when I was just a teenager. \end{minipage} \end{rtVW} \begin{rtVW} @@ -297,7 +342,7 @@ How did that other stuff get in there? \item \useRanTok{3} \end{enumerate} The verbatim listing of the example above is -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] +\begin{Verbatim}[xleftmargin=\amtIndent] \begin{enumerate} \item \useRanTok{1} \item \useRanTok{2} @@ -305,39 +350,69 @@ The verbatim listing of the example above is \end{enumerate} \end{Verbatim} +\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 \cs{displayListRandomly} has the syntax, +\bVerb\takeMeasure{\string\displayListRandomly[\anglemeta{prior}]\darg{\meta{name}}}% +\begin{minipage}{\bxSize}\kern0pt +\begin{Verbatim}[frame=single,commandchars=!()] +\displayListRandomly[!anglemeta(prior)]{!meta(name)} +\end{Verbatim} +\end{minipage} +\eVerb The action of \cs{displayListRandomly} is to expand all tokens that +are listed in the \meta{name} token list, each entry is displayed with +\anglemeta{prior}\cs{useRanTok\darg{i}}, where \texttt{i} goes from~1 to +\cs{nToksFor\darg{\meta{name}}}. In the example above, \meta{prior} is +\cs{item}, but normally, its default is empty. + + + \section{Additional arguments and commands}\label{AddCmds} The syntax given earlier for \cs{useRanTok} was not completely specified. It is -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\useRanTok[!meta(name)]{!meta(number)}) +\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; the \meta{number} is the number of the -token in the range of 1 and \verb!\nToksFor{!\meta{name}\verb!}!, +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. -To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{1} +\newtopic\noindent To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{1} -The verbatim listing is -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] +\newtopic\noindent The verbatim listing is +\begin{Verbatim}[xleftmargin=\amtIndent] To illustrate: \useRanTok[myPals]{1}, \useRanTok[myThoughts]{1} \end{Verbatim} -This is a rather bad illustration. Every time this document is compiled -there is a different page break on page~\pageref*{AddCmds}. This must be used -wisely. +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. -The original order of the list of tokens is not lost, you can retrieve +\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}, -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\rtTokByNum[!meta(name)]{!meta(number)}) +\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{number} place in the list. (Rather awkwardly written.) +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=20pt,commandchars=!()] +\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} @@ -345,30 +420,32 @@ 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}\}}. -The randomization may be turned off using \cs{ranToksOff} or turned back -on with \cs{ranToksOn}. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(!parbox(.9in)(\ranToksOff -\ranToksOn)) +\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=20pt,commandchars=!()] +\begin{Verbatim}[xleftmargin=\amtIndent] \ranToksOff \ranToks{integers}{ {1}{2}{3}{4} } -\ranToksOff +\ranToksOn \end{Verbatim} -This should make $\verb!\useRanTok{3}! = \verb!\rtTokByNum{3}! = 3 $; -executing this code, we get, \ranToksOff\ranToks{integers}{ {1}{2}{3}{4} }\ranToksOff -$\useRanTok{3} = \rtTokByNum{3} = 3 $? As anticipated. +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. The command \cs{ranToksOff} is probably best in the preamble to turn off all randomization while the rest of the document is being composed. -The \textsf{ran\_toks} package writes an auxiliary file named -\verb!\jobname\_rt.sav!, below represents two typical lines in this file. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] +\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} @@ -381,42 +458,48 @@ Normally, the pseudo-random number generator provided by you recompile again before another minute, you'll get the same initial seed value. -To obtain a new initial seed value each time you compile, place -\cs{useLastAsSeed} in the preamble. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\useLastAsSeed) +\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 \verb!\jobname\_rt.sav! file, as seen in the above example. +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. -\begin{Verbatim}[xleftmargin=20pt,commandchars=!()] -!fbox(\useThisSeed{!meta(init_seed_value)}) +\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 \verb!\jobname\_rt.sav! file. +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}/\cs{eRTVToks} 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: +\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 \verb!\useThisSeed{1604051353}! in the preamble. Compiling +\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 \verb!\useThisSeed{735794511}! in the preamble. +\item Place \cs{useThisSeed\darg{735794511}} in the preamble. \item Label each \begin{Verbatim} %\useThisSeed{1604051353} % 11:00 class @@ -426,12 +509,13 @@ 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=20pt,commandchars=!()] +\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. +\newtopic\noindent Now, I simply must get back to my retirement. \dps \end{document} |