From 4338972cc175be565a3441c4ae8a6aa0dfcbe9f9 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sun, 6 Jun 2021 03:02:43 +0000 Subject: CTAN sync 202106060302 --- .../latex/contrib/eq-pin2corr/doc/eq-pin2corr.pdf | Bin 256673 -> 101085 bytes .../contrib/eq-pin2corr/doc/eqpin2corrman.pdf | Bin 245015 -> 426168 bytes .../contrib/eq-pin2corr/doc/eqpin2corrman.tex | 376 +++++++++++++++++++-- 3 files changed, 357 insertions(+), 19 deletions(-) (limited to 'macros/latex/contrib/eq-pin2corr/doc') diff --git a/macros/latex/contrib/eq-pin2corr/doc/eq-pin2corr.pdf b/macros/latex/contrib/eq-pin2corr/doc/eq-pin2corr.pdf index 92c3cec32b..bd008ba7f1 100644 Binary files a/macros/latex/contrib/eq-pin2corr/doc/eq-pin2corr.pdf and b/macros/latex/contrib/eq-pin2corr/doc/eq-pin2corr.pdf differ diff --git a/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.pdf b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.pdf index 0103c028ca..55e7438520 100644 Binary files a/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.pdf and b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.pdf differ diff --git a/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex index aa2f13dbc9..a660f2c3bb 100644 --- a/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex +++ b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex @@ -6,16 +6,27 @@ \documentclass[10pt]{article} \usepackage[fleqn]{amsmath} %\usepackage{hyperref} -\usepackage[ - web={centertitlepage,designv,forcolorpaper,latextoc,pro}, +\usepackage[% + web={centertitlepage, + designv, + forcolorpaper, + latextoc, +% uselatexparts, + extended + }, exerquiz, % linktoattachments, aebxmp ]{aeb_pro} +\usepackage{aeb_mlink} \usepackage[!showscore]{eq-pin2corr} %\previewOn\pmpvOn +%\tocPartTitle{\protect\makebox[0pt][r]{\thepart\hspace{.5em}}#1} +\tocPartTitle{\tops{\protect\makebox[0pt][r]{\thepart\hspace{.5em}}}{\thepart\space}#1} + + \useBeginQuizButton[\CA{Begin}] \useEndQuizButton[\CA{End}] \useMCCircles @@ -115,8 +126,8 @@ email={dpstory@acrotex.net}, subject={Documentation for the eq-pin2corr package from AcroTeX: Apply PIN security to quizzes}, talksite={\url{www.acrotex.net}}, - version={0.5, 2021/15/06}, - Keywords={AcroTeX, mini-toc}, + version={2.0, 2021/05/29}, + Keywords={AcroTeX, PIN security}, copyrightStatus=True, copyrightNotice={Copyright (C) \the\year, D. P. Story}, copyrightInfoURL={http://www.acrotex.net} @@ -146,7 +157,7 @@ if (resp != null) { var f=this.getField("txt"); f.value=Collab.hashString(resp); - } + } \end{defineJS} @@ -204,6 +215,13 @@ _path=_path.substring(0,pos)+"/"+manualfilename; \hypersetup{linktocpage} +\part{Version 1.0}\label{prt:One} + +In this part of the manual, we document the features of the \pkg{eq-pin2corr} package +as they originally appeared. In addition to the features documented here, version~2.0 +adds a number of features, some of which were suggested by Tahir Y. These additional features +are documented in \hyperref[prt:Two]{Part~\ref*{prt:Two}} on page~\pageref{prt:Two} of this manual. + \section{Introduction} This package is an add-on to the \env{quiz} environment of the \pkg{exerquiz} @@ -297,7 +315,7 @@ The minimal preamble for documents that use the \pkg{eq-pin2corr} package. \begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] !1\documentclass{article} !2\usepackage[!ameta(options)]{web} -\usepackage[!ameta(options)]{exerquiz}!textbf([2021/02/17]) +\usepackage[!ameta(options)]{exerquiz}!textbf([2021/04/27]) \usepackage[!ameta(options)]{eq-pin2corr} ... \declPINId{!ameta(pin-num)}{!ameta(hash-string)} @@ -305,14 +323,14 @@ The minimal preamble for documents that use the \pkg{eq-pin2corr} package. ... \begin{document} \end{Verbatim} -\eVerb A recent version of \pkg{exerquiz} (2021/02/17 or later) is required; -\pkg{eq-pin2corr} brings in the \pkg{eq-save} package (2021/02/17 or later). +\eVerb A recent version of \pkg{exerquiz} (2021/05/29 or later) is required; +\pkg{eq-pin2corr} brings in the \pkg{eq-save} package (2021/04/27 or later). \section{Package options} There are two options for this package: \opt{showscore} and \opt{!showscore}. If you took the test on page~3, you will have noticed that when \uif{End -Quiz} control is pressed the phase \textsf{"Success! Now save and send to the +Quiz} control is pressed the phrase \textsf{"Success! Now save and send to the instructor"} appears in the \cs{ScoreField} or the \cs{PointsField}, this is the default behavior. Passing \FmtMP{\opt{showscore}}\opt{showscore} in the optional argument list of \pkg{eq-key2corr} causes the actual score to appear @@ -330,24 +348,32 @@ Refer to the \texttt{eformsman.pdf} for a discussion of \cs{flJSStr}. \paragraph*{Local controls.} The two options can be turned off and on locally with \FmtMP{\cs{showScoreOff}}\cs{showScoreOff} and \FmtMP{\cs{showScoreOn}}\cs{showScoreOn} commands. -\section{Setting the pin-hash values} +\section{Setting the pin-hash values}\label{s:pin-hash} In the preamble, as indicated above, are two commands, the first is required, the second is optional. \bVerb\takeMeasure{\string\declPINId\darg{\ameta{pin-num}}\darg{\ameta{hash-string}}}% %\setlength{\dimen0}{\wd\webtempboxi+2\fboxsep+2\fboxrule}% -\def\1{\rlap{\sffamily\hskip\linewidth(optional)}} +%\def\1{\rlap{\sffamily\hskip\linewidth(\cs{numPINId} expands to \ameta{pin-num})}} +\def\2{\rlap{\sffamily\hskip\linewidth(optional)}} \begin{dCmd}[commandchars=!()]{\bxSize} \declPINId{!ameta(pin-num)}{!ameta(hash-string)} -!1\classPINVar{!ameta(class-pin-var)} +\numPINId +!2\classPINVar{!ameta(class-pin-var)} \end{dCmd} -\eVerb It is through the \cs{declPINId} command that the PIN security is set up. - -\paragraph*{\cs{declPINId\darg{\ameta{pin-num}}\darg{\ameta{hash-string}}}} The \ameta{pin-num} is a number, perhaps four digits, -that is used to pass through the security of the \uif{Correct} button.\footnote{The \ameta{pin-num} does not have to be a number, -it can be any password (passcode) that is easy to remember. I prefer a four digit number.} Once you decide on the -PIN number, you need to generate the corresponding \emph{hash-string}. The hash-string is obtained from the demo file -\texttt{get-hash-string.pdf}, the contents of that files is reproduced below. +\eVerb It is through the \cs{declPINId} command that the PIN security is set +up. The command \cs{numPINId} expands to \ameta{pin-num} is not normally +typeset into the document, but is used for documentation or demonstration +purposes, such as in this document. + +\paragraph*{\cs{declPINId\darg{\ameta{pin-num}}\darg{\ameta{hash-string}}}} +The \ameta{pin-num} is a number, perhaps four digits, that is used to pass +through the security of the \uif{Correct} button.\footnote{The +\ameta{pin-num} does not have to be a number, it can be any password +(passcode) that is easy to remember. I prefer a four digit number.} Once you +decide on the PIN number, you need to generate the corresponding +\emph{hash-string}. The hash-string is obtained from the demo file +\texttt{get-hash-string.pdf}, the contents of that file is reproduced below. \begin{aebQuote} \pushButton[\CA{Push}\AAmouseup{\btnAct}]{btn}{}{11bp}\olBdry \textField[\textSize{8}]{txt}{2in}{11bp}\olBdry @@ -416,6 +442,318 @@ commands. \eVerb These can placed anywhere outside a \env{quiz} environment. The commands take effect beginning at the next quiz in the document. +\part{Version 2.0}\label{prt:Two} + +\section{Introduction} + +Version~2 of this package provides additional security options for the +document author (instructor or professor). + +\newtopic\noindent The source files (TEX) for the working examples in this +part of the manual may be found on the {\AcroTeX} Blog web site: +\begin{itemize} + \item \href{http://www.acrotex.net/blog/?p=1516}{\pkg{eq-pin2corr}: PIN security with warning and freezing}\footnote + {\url{http://www.acrotex.net/blog/?p=1516}} + \item \href{http://www.acrotex.net/blog/?p=1519}{\protect\pkg{eq-pin2corr}: + PIN security on \protect\uif{Begin Quiz} and tracking retakes of a quiz}\footnote + {\url{http://www.acrotex.net/blog/?p=1519}} +\end{itemize} + +\section{Security with warn and freeze on \tops{\protect\uif}{}{End Quiz}} + +When the student presses the \uif{End Quiz} control, an alert dialog box +opens which warns\FmtMP{warn and freeze} the user that quiz will be `frozen' +which means active form fields are made readonly, except for the \uif{Ans} +button. The user has a choice of responding \uif{Yes} or \uif{No}, in the +later case, the student can continue with the quiz. If the student presses +\uif{Yes}, the quiz is frozen, all the student can do is to save the file and +to send it to the instructor. +\bVerb\takeMeasure{\uif{Click 'Yes' to end the quiz or 'No' to continue working on the quiz.}\}}% +\settowidth{\eflength}{\cs{useWarnEndQuiz}} +\def\1{\leavevmode\rlap{\hspace{\eflength} \%\sffamily{ use with \cs{usePINCorrBtn}}}}% +\def\2{\leavevmode\rlap{\sffamily\hskip\linewidth(Turn off PIN security)}}% +\begin{dCmd}[commandchars=!()]{\bxSize} +!1\useWarnEndQuiz +\restoreEndQuiz +\flJSStr{\EndQuizG@te@Msg}{!uif(Warning:) +!uif(Are you sure you want to end this quiz?)\r\r +!uif(The quiz will be frozen and no more changes will be allowed.) +!uif(Click 'Yes' to end the quiz or 'No' to continue working on the quiz.)} +\end{dCmd} +\eVerb Expand \cs{useWarnEndQuiz} prior to the quiz for which the `warn and +freeze' security is to be employed. After the quiz, optionally expand +\cs{restoreEndQuiz} to its original definition. + +\useWarnEndQuiz + +\newtopic\noindent +Prior to the following quiz, \cs{usePINCorrBtn}\cs{useWarnEndQuiz} are +expanded. +\begin{quiz*}{qz2} +Solve each, passing is 100\%. +\begin{questions} + \item The sum of 1 and 1 is \dots +\begin{answers}{8} +\bChoices + \Ans0 0\eAns + \Ans0 1\eAns + \Ans1 2\eAns + \Ans0 3\eAns + \Ans0 4\eAns +\eChoices +\end{answers} + \item $ \cos(\pi) = \RespBoxMath{-1}{1}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{-1} $ + +\item $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}{4}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{cos(x)} $ +\end{questions} +\end{quiz*}\quad\ScoreField[\rectW{2.25in}]\currQuiz\olBdry\CorrButton{\currQuiz} (PIN: \numPINId) + +\noindent +Answers: \AnswerField\currQuiz + +\section{PIN security with freeze on \tops{\protect\uif}{}{Correct}} + +In the previous section, the quiz is made readonly (frozen) when the student +presses the \uif{End Quiz} control. We can also freeze the quiz when the +\uif{Correct} control is pressed. + +This strategy allows the student to take and retake the quiz if the score is +not to his liking; assuming the \texttt{showscore} option is in effect. +Freezing the quiz on the \uif{Correct} control allows the quiz to be marked +up and returned to the student, without fear the student will later modify +his answers and complain to the teacher that the score is incorrect. + +\newtopic\noindent To freeze the quiz when the \uif{Correct} control is pressed, +expand \cs{FreezeThisQuiz}. +\bVerb\takeMeasure{\string\FreezeThisQuizNot}% +\def\1{\rlap{\sffamily\hskip\linewidth(use with \cs{usePINCorrBtn})}} +\begin{dCmd}[commandchars=!()]{\bxSize} +!1\FreezeThisQuiz +\FreezeThisQuizNot +\end{dCmd} +\eVerb There are two methods of expanding \cs{FreezeThisQuiz}: (1) expand +prior to the quiz (and expand \cs{FreezeThisQuizNot} following the quiz); or +(2) pass \cs{FreezeThisQuiz} through the optional argument of the +\cs{CorrButton} (the \uif{Correct} control) using the syntax +\verb|\CorrButton[\cmd{\FreezeThisQuiz}]{\currQuiz}|. The latter method make +the change local, hence \cs{FreezeThisQuizNot} is not needed following the +quiz. + +\showScoreOn +\restoreEndQuiz + +\newtopic\noindent +The following quiz uses \verb|\CorrButton[\cmd{\FreezeThisQuiz}]{\currQuiz}| +at the end of the quiz. Prior to this quiz, \cs{showScoreOn} and +\cs{restoreEndQuiz} are expanded, the later to recover from `warn and freeze' +of the previous quiz. +\begin{quiz*}{qz3} +Solve each, passing is 100\%. +\begin{questions} + \item The sum of 1 and 1 is \dots +\begin{answers}{8} +\bChoices + \Ans0 0\eAns + \Ans0 1\eAns + \Ans1 2\eAns + \Ans0 3\eAns + \Ans0 4\eAns +\eChoices +\end{answers} + \item $ \cos(\pi) = \RespBoxMath{-1}{1}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{-1} $ + +\item $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}{4}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{cos(x)} $ +\end{questions} +\end{quiz*}\quad\ScoreField[\rectW{2.25in}]\currQuiz\olBdry\CorrButton[\cmd{\FreezeThisQuiz}]{\currQuiz} (PIN: \numPINId) + +\noindent +Answers: \AnswerField\currQuiz + +\section{Tallying the number of retakes of a quiz} + +One problem with digital PDF quizzes (\`a la Acro\negthinspace\TeX) is a +student takes and retakes a quiz until a desired score of 100\% is attained, +assuming no PIN security is on the \uif{Correct} control. This problem is +partially mitigated by the PIN security on the \uif{Correct} control, but +still, teachers, when administering an exam for credit, do not like to see +student retaking the quiz multiple times. The \pkg{eq-pin2corr} package now offers +the following commands: +\bVerb\takeMeasure{\string\qzResetTally[\ameta{options}]}% +\def\1{\rlap{\sffamily\hskip\linewidth(optionally, use with \cs{usePINCorrBtn})}} +\begin{dCmd}[commandchars=!()]{\bxSize} +!1\useBeginQuizCnt +\restorBeginQuiz +\qzResetTally[!ameta(options)] +\end{dCmd} +\eVerb Expanding \cs{useBeginQuizCnt} modifies the action of the \uif{Begin +Quiz} control to count the number of times the student as retaken the same +quiz. The count show up in the readonly text field created by +\cs{qzResetTally}. Restore the original action of the \uif{Begin Quiz} control +by expanding \cs{restorBeginQuiz}. + +This next quiz has PIN security with freeze on the \uif{Correct} control. The +\uif{Begin Quiz} controls tracks the number of times the student +\emph{re-takes the quiz}. Prior to the quiz we expand +\cs{showScoreOn}\cs{useBeginQuizPIN}\cs{useBeginQuizCnt}. The +\cs{qzResetTally} field is place to the right of the \cs{CorrButton} command. +Speaking of the \cs{CorrButton}, \verb|\cmd{\FreezeThisQuiz}| is passed to +this command through its optional argument so that the quiz is frozen when +the instructor presses the \uif{Correct} control and successfully enters the +PIN. + +\showScoreOn +\useBeginQuizPIN +\useBeginQuizCnt +%\restorBeginQuiz + +\begin{quiz*}{qz4} +\textbf{Instructions:} Take and retake this quiz until you obtain 100\%. +\begin{questions} + \item The sum of 1 and 1 is \dots +\begin{answers}{8} +\bChoices + \Ans0 0\eAns + \Ans0 1\eAns + \Ans1 2\eAns + \Ans0 3\eAns + \Ans0 4\eAns +\eChoices +\end{answers} + \item $ \cos(\pi) = \RespBoxMath{-1}{1}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{-1} $ + +\item $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}{4}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{cos(x)} $ +\end{questions} +\end{quiz*}\quad\ScoreField[\rectW{2.25in}]\currQuiz\olBdry\CorrButton[\cmd{\FreezeThisQuiz}]{\currQuiz} (PIN: \numPINId)\hfill\qzResetTally + +\noindent +Answers: \AnswerField\currQuiz + +\section{Setting the maximum number of retakes} + +This quiz has PIN security on the \uif{Correct} control. The \uif{Begin Quiz} controls +tracks the number of times the student \emph{re-takes the quiz}. It also sets the maximum +number of times the student retake the quiz. +\bVerb\takeMeasure{\string\setMaxRetakes\darg{\ameta{qz-name}\darg{\ameta{num}}}}% +\def\1{\rlap{\sffamily\hskip\linewidth(use with \cs{usePINCorrBtn})}} +\begin{dCmd}[commandchars=!()]{\bxSize} +\setMaxRetakes{!ameta(qz-name)}{!ameta(num)} +\nMaxRetakes{!ameta(qz-name)} +\end{dCmd} +\eVerb When declared prior to the quiz whose name is \ameta{qz-name}, +\cs{setMaxRetakes} sets the maximum of times a student can \emph{retake the same +quiz} to \ameta{num}, where \ameta{num} is a nonnegative integer. Declaring +\cs{setMaxRetakes\darg{\ameta{qz-name}}\darg{0}} means the student may only +take the quiz once (no retakes allowed); \cs{setMaxRetakes\darg{\ameta{qz-name}}\darg{2}} means he +can retake the quiz twice (for a total of three times). + +The command \cs{nMaxRetakes\darg{\ameta{qz-name}}} is a way of typesetting +the number \ameta{num} into the document as part of the instructions for the +quiz, for example. + +\showScoreOn +\useBeginQuizCnt +\setMaxRetakes{qz5}{2} + +\newtopic\noindent The following quiz has PIN security with freeze under the \uif{Correct} control and it +allows the student to retake the quiz at most \nMaxRetakes{qz5}~times. + +\begin{quiz*}{qz5} +Solve each, passing is 100\%. Be aware that you will be allowed to +\emph{retake} this quiz at most \nMaxRetakes{qz5}~times. +\begin{questions} + \item The sum of 1 and 1 is \dots +\begin{answers}{8} +\bChoices + \Ans0 0\eAns + \Ans0 1\eAns + \Ans1 2\eAns + \Ans0 3\eAns + \Ans0 4\eAns +\eChoices +\end{answers} + \item $ \cos(\pi) = \RespBoxMath{-1}{1}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{-1} $ + +\item $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}{4}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{cos(x)} $ +\end{questions} +\end{quiz*}\quad\ScoreField[\rectW{2.25in}]\currQuiz\olBdry\CorrButton[\cmd{\FreezeThisQuiz}]{\currQuiz} (PIN: \numPINId)\hfill\qzResetTally + +\noindent +Answers: \AnswerField\currQuiz + +\section{PIN Security for \tops{\protect\uif}{}{Begin Quiz} and \tops{\protect\uif}{}{Correct}} + +For this final example, the student can see his quiz score (which can be +optionally changed by expanding \cs{showScoreOff}); however, to retake the +quiz a PIN must be entered when the \uif{Begin Quiz} button is pressed. The +PIN under the \uif{Begin Quiz} control is (usually) different from the PIN +under the \uif{Correct} button. +\bVerb\takeMeasure{\string\flJSStr\darg{\string\BeginQuizG@te@Msgii}\{\uif{Press the Begin Quiz}}% +%\def\1{\rlap{\sffamily\hskip\linewidth(\cs{numRePINId} expands to \ameta{pin-num})}} +\begin{dCmd}[commandchars=!()]{\bxSize} +\declRePINId{!ameta(pin-num)}{!ameta(hash-string)} +\numRePINId +\flJSStr{\BeginQuizG@te@Msgi}{!uif(Enter the PIN number) +!uif(to retake this quiz)} +\flJSStr{\BeginQuizG@te@Msgii}{!uif(Press the Begin Quiz) +!uif(control to begin the quiz again)} +\end{dCmd} +\eVerb \cs{declRePINId} is used to declare the PIN number for retaking the +quiz, as well as the corresponding hash string. Refer to \cs{declPINId} above +(\hyperref[s:pin-hash]{Section~\ref{s:pin-hash}}) for information of how to +acquire the hash string for the PIN. + +The command \cs{numREPINId} expands to \ameta{pin-num} is not normally +typeset into the document, but is used for documentation or demonstration +purposes, such as in this document. + +The final two, \cs{BeginQuizG@te@Msgi} and \cs{BeginQuizG@te@Msgii} expand to +the messages the respondent reads. These may be redefined as desired. + +\newtopic\noindent +The PIN for the \uif{Begin Quiz} button is \numRePINId. The \uif{Begin Quiz} +button does not need a PIN for the first time it is pressed. It requires a +PIN after the first press. + +\showScoreOn +\useBeginQuizPIN + +\begin{quiz*}{qz6} +Solve each, passing is 100\%. +\begin{questions} + \item The sum of 1 and 1 is \dots +\begin{answers}{8} +\bChoices + \Ans0 0\eAns + \Ans0 1\eAns + \Ans1 2\eAns + \Ans0 3\eAns + \Ans0 4\eAns +\eChoices +\end{answers} + \item $ \cos(\pi) = \RespBoxMath{-1}{1}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{-1} $ + +\item $\displaystyle\frac{d}{dx}{\sin(x)}=\RespBoxMath{cos(x)}{4}{.0001}{[0,1]}\cgBdry[1bp] +\CorrAnsButton{cos(x)} $ +\end{questions} +\end{quiz*}\quad\ScoreField[\rectW{2.25in}]\currQuiz\olBdry\CorrButton{\currQuiz} (PIN: \numPINId)\hfill\qzResetTally + +\noindent +Answers: \AnswerField\currQuiz\vcgBdry[6pt] + +This kind of security is best when the students are taking a quiz in a +computer lab with a proctor in the room. The student can ask the proctor to +reset the quiz. Note that we keep a tally on the number of requests as the +proctor may not write it down or remember. + \medbreak\noindent Now, I really must get back to retirement.\enspace\dps -- cgit v1.2.3