summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx
blob: 091ba8a94f4a0a6dcbc87f4c88d58eaf5aadd4d1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
% \iffalse
% makeindex -s gglo.ist -o eq-pin2corr.gls eq-pin2corr.glo
% makeindex -s gind.ist -o eq-pin2corr.ind eq-pin2corr.idx
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% eq-pin2corr.sty package,                              %%
%% Copyright (C) 2021  D. P. Story                       %%
%%   dpstory@uakron.edu  dpstory@acrotex.net             %%
%%                                                       %%
%% This program can redistributed and/or modified under  %%
%% the terms of the LaTeX Project Public License         %%
%% Distributed from CTAN archives in directory           %%
%% macros/latex/base/lppl.txt; either version 1.2 of the %%
%% License, or (at your option) any later version.       %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{eq-pin2corr}
%<package> [2021/02/20 v1.0 Applies PIN security to quizzes]
%<*driver>
\documentclass{ltxdoc}
%\usepackage[colorlinks,hyperindex=false,linktocpage,bookmarksnumbered]{hyperref}
\usepackage[colorlinks,hyperindex=false]{hyperref}
\usepackage{fancyvrb}
\usepackage{calc}
%\usepackage{eq-pin2corr}
%\def\texorpdfstring#1#2{#1}
%\pdfstringdefDisableCommands{\let\\\textbackslash}
\OnlyDescription  % comment out for implementation details
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\gdef\brpr#1{\texttt{\char123\relax#1\char125\relax}}
\let\darg\brpr
\let\env\texttt
\let\opt\texttt
\let\app\textsf
\let\pkg\textsf
\let\uif\textsf
\def\EXCL{!}
\def\visispace{\symbol{32}}
\def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
\def\meta#1{\textsl{\texttt{#1}}}
\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
\def\CMD#1{\textbackslash#1}
\makeatletter
\renewcommand\theparagraph{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
\renewcommand\thesubparagraph{\texorpdfstring{\protect\P\protect\P\protect\ }{\textparagraph\textparagraph}}
\renewcommand{\section}
  {\renewcommand{\@seccntformat}[1]{\thesection\quad}%
  \@startsection {section}{1}{\z@}%
    {-3.5ex \@plus -1ex \@minus -.2ex}%
    {2.3ex \@plus.2ex}%
    {\normalfont\Large\bfseries}}
\renewcommand{\paragraph}
  {\renewcommand{\@seccntformat}[1]{\theparagraph\unskip\,}%
  \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\renewcommand{\subparagraph}
    {\renewcommand{\@seccntformat}[1]{\thesubparagraph\unskip\,}%
    \@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}{\bfseries}}
\edef\amtIndent{\the\parindent}
\newenvironment{aebQuote}
               {\list{}{\leftmargin\amtIndent}%
                \item\relax}
               {\endlist}
\makeatother
\InputIfFileExists{aebdocfmt.def}{\PackageWarning{eq-pin2corr}{Inputting aebdocfmt.def}}
    {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
     \PackageInfo{eq-pin2corr}{aebdocfmt.def cannot be found}}
\begin{document}
\addtolength{\marginparwidth}{3pt}
  \GetFileInfo{eq-pin2corr.sty}
  \title{The  \textsf{eq-pin2corr} Package}
  \author{D. P. Story\\
    Email: \texttt{dpstory@uakron.edu}}
  \date{processed \today}
  \maketitle
\setcounter{secnumdepth}{5}
\setcounter{tocdepth}{5}
\bgroup
\value{secnumdepth}=3
\value{tocdepth}=3
  \tableofcontents
\egroup
  \DocInput{eq-pin2corr.dtx}
\IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here. Execute
    \begin{quote}\texttt{makeindex -s gind.ist -o eq-pin2corr.ind eq-pin2corr.idx}\end{quote}
    on the command line and recompile
    \texttt{eq-pin2corr.dtx}.}
\IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here. Execute
    \begin{quote}
    \texttt{makeindex -s gglo.ist -o eq-pin2corr.gls eq-pin2corr.glo}
    \end{quote}
    on the command line and recompile \texttt{eq-pin2corr.dtx}.}
\end{document}
%</driver>
% \fi
% \MakeShortVerb{|}
% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
%    {\PackageInfo{web}{cannot find aebdonotindex.def}}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \section{Introduction}
%    This package is an add-on to the \env{quiz} environment of the \pkg{exerquiz} package. It uses
%    the \pkg{eq-save} package. To correct a quiz, the document consumer must press
%    the \uif{Correct} button of a quiz and successfully enter the correct PIN number.
%
%    \changes{v1.0}{2021/02/20}{Completed documentation, publish package for first time}
%
%    \paragraph*{Purpose.} This package adds PIN security to a quiz created by
%     the \env{quiz} environment. This package is designed for the educational
%     sector, for instructors who use the quizzes of \pkg{exerquiz} to assess their
%     students understanding of the course material.
%
%     \paragraph*{PDF Viewers.} Discussion of PDF viewers for document author and document consumer.
%     \begin{aebQuote}
%     \begin{description}
%     \item[Instructor] Any PDF viewer may be used as a PDF previewer, \app{sumatraPDF}, for instance,
%     can be used, but it has not functionality. To test the newly created document
%     to see if it is functioning correctly, must use \app{Adobe Reader DC} or \app{Acrobat DC}.\footnote
%     {We use DC here to refer to actually any Adobe AA/AR application. Earlier versions of these applications
%     will work.}
%     \item[Document consumers (students)] The \pkg{exerquiz} and \pkg{eq-pin2tocorr} extensively
%     use JavaScript to perform many background tasks. For the student to have any success in this
%     workflow, he/she must use \app{Adobe Reader}.
%     \end{description}
%     \end{aebQuote}
%     \paragraph*{Workflow.} The package is designed for the following workflow:
%     \begin{enumerate}
%         \item The instructor creates the quiz using the \pkg{exerquiz} and
%           \pkg{eq-pin2corr} packages.
%         \item The instructor delivers the ``PDF quiz'' to each student. (System drive or email)
%         \item The student takes the quiz. The student can press the \uif{Correct}
%           but, unless he/she knows the PIN, the quiz is not marked up.
%         \item The student saves the PDF quiz in \app{Adobe Reader DC}.
%         \item The student returns the PDF to the instructor. (System drive or email)
%         \item The instructor presses the \uif{Correct} button to mark up the quiz
%         and record the grade of the student. The instructor saves the quiz.
%         \item The instructor returns the PDF, at some point, to the student.
%         \item Both instructor and student happily go on with their lives.
%     \end{enumerate}
%     \section{Options and package requirements}
%    \begin{macrocode}
\newif\ifPINshowScore \PINshowScorefalse
\DeclareOption{showscore}{\PINshowScoretrue}
\DeclareOption{!showscore}{\PINshowScorefalse}
\ProcessOptions\relax
\RequirePackage{exerquiz}[2021/02/17]
\RequirePackage{eq-save}[2021/02/17]
%    \end{macrocode}
%     \section{Package commands}
%     Implement local versions\DescribeMacro{\showScoreOn}\DescribeMacro{\showScoreOff}{} of the package options \opt{showscore} and \opt{!showscore},
%     these are \cs{showScoreOn} and \cs{showScoreOff}.
%    \begin{macrocode}
\def\showScoreOn{\PINshowScoretrue}
\def\showScoreOff{\PINshowScorefalse}
%    \end{macrocode}
%    Define \DescribeMacro{\SaveAndSendMsg} a message that appears on the console when the PIN entered is not correct.
%    \begin{macrocode}
\flJSStr[noquotes]{\SaveAndSendMsg}{Success! %
Now save and send to the instructor}
%    \end{macrocode}
%     Make changes to the \uif{End Quiz} control and to the \uif{Correct} control.
%     Begin by modifying the \DescribeMacro{\postSubmitQuiz}\cs{postSubmitQuiz} command, which is a hook within the executing
%     code of the \uif{End Quiz} control.
%    \begin{macrocode}
\begin{defineJS*}[\makeesc\@\makecmt\%]{\postSubmitQuiz}
// Begin post submit quiz code%
@ifPINSecurity%
@ifPINshowScore@else
    var f = this.getField("ScoreField.@oField");
    if ( f!=null ) {
      f.textSize=0;
      f.value = "@SaveAndSendMsg";
    } else {
      var f = this.getField("PointsField.@oField");
      if (f!=null) {
        f.textSize=0;
        f.value = "Success! Now save and send to instructor";
      }
    }@fi@fi
    oRecordOfQuizData["ScoreData.@oField"]=%
[1*Score,1*NQuestions,1*ptScore,1*NPointTotal];
    oRecordOfQuizData["RightWrong.@oField"]=%
eval(RightWrong.toSource());
    oRecordOfQuizData["ProbDist.@oField"]=%
eval(ProbDist.toSource());
    cntCorrectResponses();
\end{defineJS*}
%    \end{macrocode}
%    The command name for the action of the \uif{End Quiz} control is
%    \DescribeMacro{\eQzBtnActns}\cs{eQzBtnActns}.
%    We save this and pre-pend a single code line, as needed.
%    \begin{macrocode}
\let\eQzBtnActnsSave\eQzBtnActns
\def\eQzBtnActns{\ifPINshowScore\else
  var bDisplaySilent=true;\r\fi
  \eQzBtnActnsSave
}
%    \end{macrocode}
%    The command name for the action of the \uif{Correct} control is \cs{CorrBtnActionsJS}
%    we save this and later modify it.
%    \begin{macrocode}
\let\CorrBtnActionsJSSave\CorrBtnActionsJS
%    \end{macrocode}
%    We can turn on and off the PIN feature by expanding \DescribeMacro{\usePINCorrBtn}
%    \cs{usePINCorrBtn} and \DescribeMacro{\restoreCorrBtn}\cs{restoreCorrBtn}.
%    \begin{macrocode}
\newif\ifPINSecurity \PINSecurityfalse
\def\usePINCorrBtn{\PINSecuritytrue
  \let\CorrBtnActionsJS\CorrBtnActionsPwdJS}
\def\restoreCorrBtn{\PINshowScoretrue\PINSecurityfalse
  \let\CorrBtnActionsJS\CorrBtnActionsJSSave}
%    \end{macrocode}
%    The instructor can tediously press the \uif{Correction} button, or place
%    an entry,
%\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small,
%commandchars={!()},codes={\catcode`\%=9}]
%var _PinCode1 = "02JRVZdRgYgCA-Rtje8VkD";
%\end{Verbatim}
%in the file \texttt{config.js}. If such a variable exists and its value
%matches the PIN hash string, the instructor clicks the \uif{Correction} button
%to get the quiz markup. Conceivably, the instructor might want different PIN names
%and string hash values. The \DescribeMacro\classPINVar\cs{classPINVar} is a convenient
%way of declaring the PIN variable name; eg, if |\classPINVar{_PinCode1}| is declared
%prior to the \env{quiz} environment, the instructor need not manually enter the PIN.
%    \begin{macrocode}
\def\classPINVar#1{\def\PINclassPV{#1}}
\let\PINclassPV\@empty
%    \end{macrocode}
%    The modified action for the \uif{Correct} button.
%    we save this and later modify it.
%    \begin{macrocode}
\begin{defineJS*}[\makeesc\!\makecmt\%]{\CorrBtnActionsPwdJS}
!ifx!PINclassPV!@empty%
var userPIN = "";!else%
var userPIN = "!PINclassPV";!fi
if (userPIN == "" ) userPIN = undefined;
try {
  if ( typeof eval(userPIN) == "undefined") userPIN = undefined;
} catch(e) { userPIN = undefined; }
if (typeof userPIN == "undefined") {
  var resp=app.response({
    cQuestion: "Enter the PIN number",
    cTitle: "View Answers",
    bPassword: true
  });
  var _resp=Collab.hashString(resp);
  var _bQzResults = ( _resp ==_PinCode );
} else var _bQzResults = ( eval(userPIN) ==_PinCode );
if (_bQzResults) {
  RightWrong=eval("RightWrong.!currQuiz");
  ProbDist=eval("ProbDist.!currQuiz");
  correctQuiz("!currQuiz",3);
  DisplayQuizResults("!currQuiz",3,3);
  if (typeof correctSumryTbl == "function")
    correctSumryTbl("!currQuiz",3);
} else {
  console.println("Something went wrong, \\
you entered an incorrect PIN Id, \\
or the class PIN Id (\\\\classPINVar) was incorrect or undefined");
  console.show();
}
\end{defineJS*}
%    \end{macrocode}
%    \DescribeMacro\declPINId\hskip-\marginparsep\texttt{\darg{\ameta{PIN-Id}}\darg{\ameta{hash-str}}}
%    Set the basic parameters of this PIN security scheme: the pin-id and its corresponding hash-string.
%    \begin{macrocode}
\def\declPINId#1#2{\def\numPINId{#1}\def\hashPINId{#2}}
\@onlypreamble\declPINId
\declPINId{5243}{02JRVZdRgYgCA-Rtje8VkD} % PIN Id, hash-str
\begin{insDLJS}{pin}{Pin Code}
var _PinCode = "\hashPINId";
\end{insDLJS}
%    \end{macrocode}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%\Finale