summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx')
-rw-r--r--macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx281
1 files changed, 281 insertions, 0 deletions
diff --git a/macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx b/macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx
new file mode 100644
index 0000000000..091ba8a94f
--- /dev/null
+++ b/macros/latex/contrib/eq-pin2corr/eq-pin2corr.dtx
@@ -0,0 +1,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