summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/ran_toks/docs/rantoks_man.tex')
-rw-r--r--macros/latex/contrib/ran_toks/docs/rantoks_man.tex151
1 files changed, 139 insertions, 12 deletions
diff --git a/macros/latex/contrib/ran_toks/docs/rantoks_man.tex b/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
index 8f8b0c6246..232c1980ca 100644
--- a/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
+++ b/macros/latex/contrib/ran_toks/docs/rantoks_man.tex
@@ -8,7 +8,8 @@
]{aeb_pro}
\usepackage{ran_toks}
-\useThisSeed{1441984427}
+\useThisSeed{227819015}
+%\useThisSeed{1441984427}
%\useLastAsSeed
%\useThisSeed{2001383846}
@@ -30,6 +31,7 @@
%\usepackage{makeidx}
%\makeindex
\usepackage{acroman}
+\usepackage[active]{srcltx}
\makeatletter
\def\eq@fititin#1{\noindent\unskip\nobreak\hfill\penalty50
@@ -77,17 +79,19 @@
\urlstyle{rm}
+\let\tops\texorpdfstring
+
\DeclareDocInfo
{
university={\AcroTeX.Net},
- title={\texorpdfstring{The \textsf{ran\_toks}}{The manual for the ran\_toks}
- Package\texorpdfstring{\\[6pt]\large}{: }
+ title={\tops{The \textsf{ran\_toks}}{The manual for the ran\_toks}
+ Package\tops{\\[6pt]\large}{: }
Randomizing the order of tokens},
author={D. P. Story},
email={dpstory@acrotex.net},
subject=Documentation for the ran\_toks package,
talksite={\url{www.acrotex.net}},
- version={1.3.1, 2021/01/19},
+ version={1.4, 2021/06/06},
Keywords={LaTeX, PDF, random, tokens, JavaScript, Adobe Acrobat},
copyrightStatus=True,
copyrightNotice={Copyright (C) \the\year, D. P. Story},
@@ -106,7 +110,7 @@
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
-\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}
+\subsubDefaultDing{\tops{$\bullet$}{\textrm\textbullet}}
\def\exSrc{\makebox[0pt][r]{\large{\Pisymbol{webd}{157}}\enspace}}
@@ -241,7 +245,7 @@ There are two styles for defining a series of tokens to be randomized,
using either the \cs{ranToks} command or the \cs{bRTVToks}/\cs{eRTVToks}
pair. Each of these is discussed in the next two subsections.
-\subsection{The \texorpdfstring{\protect\cs{ranToks}}{\CMD{ranToks}} command}\label{s:ranToks}
+\subsection{The \tops{\protect\cs{ranToks}}{\CMD{ranToks}} command}\label{s:ranToks}
The \cs{ranToks} command was the original concept; declare a series of
tokens to be randomized.
@@ -334,13 +338,13 @@ An alternative to re-executing \cs{ranToks} is to use the \cs{reorderRanToks} co
\reorderRanToks{!ameta(name)}
\end{Verbatim}
\end{minipage}\eVerb Now, executing \verb~\reorderRanToks{myPals}~ and compiling the sentence again yields,
-``I have {\nToksFor{myPals}} pals, they are
+``I~have {\nToksFor{myPals}} pals, they are
\useRanTok{1}, \useRanTok{2}, \useRanTok{3}, \useRanTok{4},
{\useRanTok{5}} and \useRanTok{6}.'' For most applications, re-randomizing
the same token list in the same document is not very likely something you
need to do.
-The \cs{reorderRanToks\darg{\ameta{name}}} rearranges the list of tokens
+The \cs{reorderRanToks\darg{\ameta{name}}} command rearranges the list of tokens
associated with \ameta{name}, which may not be what you want; the
\cs{copyRanToks} command, on the other hand, makes a (randomized) copy of its
first required argument \ameta{name\SUB1} and saves it as \ameta{name\SUB2}, without
@@ -364,7 +368,7 @@ argument of a macro; this would exclude verbatim text created by \cs{verb}
and verbatim environments.
\subsection{The
-\texorpdfstring{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
+\tops{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
{\CMD{bRTVToks}/\CMD{eRTVToks}} pair of commands}\label{ss:RTVToks}
Sometimes the content to be randomized is quite large or contains verbatim
@@ -495,7 +499,6 @@ If we say \cs{reorderRanToks\darg{myThoughts}} and reissue the above list, we ob
The command \cs{copyRanToks} works for list created by
\cs{bRTVToks}/\penalty0\cs{bRTVToks} as well.
-
\paragraph*{On the \cs{displayListRandomly} command.}\label{para:DLR}
In the enumerate example immediately above, the items in the list are
explicitly listed as \cs{item \cs{useRanTok\darg{1}}} and so on; an
@@ -549,7 +552,131 @@ you modify the optional argument to get the same listing without the Oxford
comma? (\displayListRandomly[\ifnum\i=\last and \fi][\ifnum\i=\last.\else\ifnum\i=\lessone\relax\space\else, \fi\fi]{myPals})
Hint: a solution involves the other command \cs{lessone}.
+\subsubsection{Nested
+\tops{\protect\cs{bRTVToks}/\protect\cs{eRTVToks}}
+ {\CMD{bRTVToks}/\CMD{eRTVToks}} command pairs}\label{ss:NestedRTVToks}
+
+These is at least one example of using nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks}. When nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks} command pairs, use the \env{rtVWi}
+environment instead of the \env{rtVW} environment. The nested
+\cs{bRTVToks}/\allowbreak\cs{eRTVToks} pair is placed\FmtMP{placement} within
+a \env{rtWV} environment; in this way the contents of that \env{rtWV}
+environment, itself can be randomized. The \cs{displayListRandomly} (or
+\cs{useRanTok}) command is used to list out the nested items. See the next
+page for an example.
+
+\newpage
+
+\bRTVToks{Depth0}
+ \begin{rtVW}
+ Depth0: Item 1
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 2:
+ \bRTVToks{Depth1}
+ \begin{rtVWi}
+ Depth1: Item 1
+\end{rtVWi}
+ \begin{rtVWi}
+ Depth1: Item 2
+ \bRTVToks{Depth2}
+ \begin{rtVWii}
+ Depth2: Item 1
+\end{rtVWii}
+ \begin{rtVWii}
+ Depth2: Item 2
+\end{rtVWii}
+ \begin{rtVWii}
+ Depth2: Item 3
+\end{rtVWii}
+ \eRTVToks
+\begin{itemize}
+ \displayListRandomly[\item]{Depth2}
+\end{itemize}
+\end{rtVWi}
+ \begin{rtVWi}
+ Depth1: Item 3
+\end{rtVWi}
+\eRTVToks
+\begin{itemize}
+\displayListRandomly[\item]{Depth1}
+\end{itemize}
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 3
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 4
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 5
+\end{rtVW}
+\eRTVToks
+ \begin{enumerate}\small
+\displayListRandomly[\item]{Depth0}
+\end{enumerate}
+The verbatim listing for this example follows.
+\begin{Verbatim}[commandchars=!(),fontsize=\small]
+\bRTVToks{Depth0}
+ \begin{rtVW}
+ Depth0: Item 1
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 2:
+ \bRTVToks{Depth1} % !textsf(begin Depth2 within an rtVW env.)
+ \begin{rtVWi}
+ Depth1: Item 1
+\end{rtVWi}
+ \begin{rtVWi}
+ Depth1: Item 2
+ \bRTVToks{Depth2} % !textsf(begin Depth1 within an rtVWi env.)
+ \begin{rtVWii}
+ Depth2: Item 1
+\end{rtVWii}
+ \begin{rtVWii}
+ Depth2: Item 2
+\end{rtVWii}
+ \begin{rtVWii}
+ Depth2: Item 3
+\end{rtVWii}
+ \eRTVToks
+\begin{itemize}
+ \displayListRandomly[\item]{Depth2} % !textsf(display Depth2 toks)
+\end{itemize}
+\end{rtVWi}
+ \begin{rtVWi}
+ Depth1: Item 3
+\end{rtVWi}
+\eRTVToks
+\begin{itemize}
+\displayListRandomly[\item]{Depth1} % !textsf(display Depth1 toks)
+\end{itemize}
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 3
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 4
+\end{rtVW}
+ \begin{rtVW}
+ Depth0: Item 5
+\end{rtVW}
+\eRTVToks
+\begin{enumerate}
+\displayListRandomly[\item]{Depth0} % !textsf(display Depth0 toks)
+\end{enumerate}
+\end{Verbatim}
+Oops. Did I forget to mention that \pkg{ran\_toks} supports nested to a depth of two.
+
+Some authors like to indent nested things, but to avoid spurious spaces
+appearing, \cs{end\darg{rtVW}} (and \cs{end\darg{rtVWi}}) should be placed in
+the far left margin, as shown above. Recall the \env{rtVW} is a verbatim
+environment.
+The above example is reproduced in the \texttt{ran\_toks.tex} sample file found in the
+\texttt{examples} folder. Also found in that folder is \texttt{nested-matching.tex}, a \pkg{exerquiz}
+quiz that motivated creating nested \cs{bRTVToks}/\allowbreak\cs{eRTVToks} command pairs.
\section{Additional arguments and commands}\label{AddCmds}
@@ -633,7 +760,7 @@ The original list for \texttt{myPals} remains unchanged:
\displayListRandomly[\ifnum\i=\last\space and \fi(\the\i)~][\ifnum\i=\last.\else,\fi\space]{myPals}
The \cs{useRanTok} command---whether it operates on a randomized token list
-or not---behaves similarly to an array. Thus, if we wanted the extract
+or not---behaves similarly to an array. Thus, if we wanted to extract
the third entry of the non-randomized token list (array)
\texttt{myOriginalPals}, we do so by expanding the command
\verb!\useRanTok[myOriginalPals]{3}! to produce
@@ -752,7 +879,7 @@ The next step is to input your DB files. To do this, execute either of the comma
or perhaps in the preamble. The syntax is,
\bVerb\takeMeasure{\string\useTheseDBs\darg{\ameta{db\SUB{1}},\ameta{db\SUB{2}},...,\ameta{db\SUB{n}}}}%
\setlength\eflength{\bxSize}%
-\begin{minipage}{\bxSize}\kern0pt\def\1{\rlap{\sffamily\hskip\eflength(An alias for \cs{useTheseDBs})}}\relax
+\begin{minipage}{\bxSize}\def\1{\rlap{\sffamily\hskip\eflength(An alias for \cs{useTheseDBs})}}\kern0pt
\begin{Verbatim}[frame=single,commandchars=!()]
\useTheseDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}
!1\useProbDBs{!ameta(db!SUB(1)),!ameta(db!SUB(2)),...,!ameta(db!SUB(n))}