summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex')
-rw-r--r--macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex376
1 files changed, 357 insertions, 19 deletions
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