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.tex423
1 files changed, 423 insertions, 0 deletions
diff --git a/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex
new file mode 100644
index 0000000000..aa2f13dbc9
--- /dev/null
+++ b/macros/latex/contrib/eq-pin2corr/doc/eqpin2corrman.tex
@@ -0,0 +1,423 @@
+%
+% Need some discussion on workflow
+%
+% makeindex < aebpro_man.idx > aebpro_man.ind
+\RequirePackage[!use=preview,!use=usebw]{spdef}
+\documentclass[10pt]{article}
+\usepackage[fleqn]{amsmath}
+%\usepackage{hyperref}
+\usepackage[
+ web={centertitlepage,designv,forcolorpaper,latextoc,pro},
+ exerquiz,
+% linktoattachments,
+ aebxmp
+]{aeb_pro}
+\usepackage[!showscore]{eq-pin2corr}
+
+%\previewOn\pmpvOn
+
+\useBeginQuizButton[\CA{Begin}]
+\useEndQuizButton[\CA{End}]
+\useMCCircles
+
+\declPINId{5243}{02JRVZdRgYgCA-Rtje8VkD} % PIN number, hash string
+%\classPINVar{_PinCode1}
+
+
+%\usepackage{booktabs}
+%\usepackage{aeb_mlink}
+%\usepackage{eq-pin2corr}
+%\usepackage{graphicx,array}
+%\usepackage{ifthen}
+%\usepackage{myriadpro}
+%\usepackage{calibri}
+
+\usepackage[altbullet]{lucidbry}
+
+%\usepackage{xbmks}
+%\DeclareInitView{layoutmag={navitab:UseOutlines}}
+
+%\xbmksetup{colors={int=red},styles={intbf}}
+
+\addtolength{\marginparwidth}{20pt}
+
+%\previewtrue
+%\usepackage{makeidx}
+%\makeindex
+\usepackage{acroman}
+\usepackage[active]{srcltx}
+
+\setcounter{secnumdepth}{5}
+\setcounter{tocdepth}{5}
+\makeatletter
+\renewcommand*{\thesubsubsection}{\texorpdfstring{$\bullet$}{\textbullet}}
+\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P}{\textparagraph}}
+\renewcommand*{\thesubparagraph}{\texorpdfstring{\protect\P\protect\P}{\textparagraph\textparagraph}}
+\renewcommand{\paragraph}
+ {\renewcommand{\@seccntformat}[1]{\theparagraph\space}%
+ \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
+\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}
+\renewcommand{\subparagraph}
+ {\renewcommand{\@seccntformat}[1]{\thesubparagraph\space}%
+ \@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}{\bfseries}}
+\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
+ \kern-.6em \hbox{$\mathcal S$}}$}
+
+\newenvironment{aebQuote}
+ {\list{}{\leftmargin\amtIndent}%
+ \item\relax}{\endlist}
+\def\parboxValign{t}
+\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{%
+ \raisebox{.5\baselineskip+#1}{%
+ \expandafter\parbox\expandafter[\parboxValign]%
+ {\marginparwidth}{\aebbkFmtMp#2}}}}
+\def\aebbkFmtMp{\kern0pt\itshape\small
+ \ifusebw\color{gray}\else\color{blue}\fi
+ \raggedleft\hspace{0pt}}\newcommand{\BlogArticle}{%
+ \makebox[0pt][l]{\hspace{-1pt}\color{blue}\Pisymbol{webd}{254}%
+ }\raisebox{.5pt}{\ifusebw\color{black}\else
+ \color{red}\fi\ding{045}}}
+\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
+ \kern-.6em \hbox{$\mathcal S$}}$}
+
+\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
+\def\echgCurrLblName#1{\edef\@currentlabelname{#1}}
+\let\db\@gobble
+
+%\newenvironment{aebQuote}
+% {\list{}{\leftmargin\amtIndent}%
+% \item\relax}
+% {\endlist}
+
+\makeatother
+
+%\getDimsFromGraphic{graphics/dpsweb}{\dpswebW}{\dpswebH}
+
+
+%\urlstyle{rm}
+\urlstyle{sf}
+\let\uif\textsf
+\let\app\textsf
+\def\psf#1{\textbf{\textsf{#1}}}
+%\let\amtIndent\leftmargini
+\edef\amtIndent{\the\parindent}
+
+\renewcommand*\descriptionlabel[1]{\hspace\labelsep
+ \normalfont #1}
+
+\let\tops\texorpdfstring
+
+\DeclareDocInfo
+{
+ university={Acro\negthinspace\TeX.Net},
+ title={The \textsf{eq-pin2corr} package\tops{\\}{: } Apply PIN security to quizzes},
+ author={D. P. Story},
+ 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},
+ copyrightStatus=True,
+ copyrightNotice={Copyright (C) \the\year, D. P. Story},
+ copyrightInfoURL={http://www.acrotex.net}
+}
+
+\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
+ \kern-.6em \hbox{$\mathcal S$}}$}
+
+\universityLayout{fontsize=Large}
+\titleLayout{fontsize=LARGE}
+\authorLayout{fontsize=Large}
+\tocLayout{fontsize=Large,color=aeb}
+\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
+\subsectionLayout{indent=-31.25pt,color=aeb}
+\subsubsectionLayout{indent=0pt,color=aeb}
+\subsubDefaultDing{\tops{$\bullet$}{\textbullet}}
+
+\widestNumber{0.00.}
+%\pagestyle{empty}
+%\parindent0pt\parskip\medskipamount
+
+\begin{defineJS}{\btnAct}
+ var resp=app.response({
+ cQuestion: "Enter a PIN number",
+ cTitle: "Get Hash String"
+ });
+ if (resp != null) {
+ var f=this.getField("txt");
+ f.value=Collab.hashString(resp);
+ }
+\end{defineJS}
+
+
+\frenchspacing
+
+\chngDocObjectTo{\newDO}{doc}
+\begin{docassembly}
+var titleOfManual="The eq-pin2corr package MANUAL";
+var manualfilename="Manual_BG_Print_pin2corr.pdf";
+var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
+var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
+var doc;
+var buildIt=false;
+if ( buildIt ) {
+ console.println("Creating new " + manualfilename + " file.");
+ doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
+ var _path=this.path;
+ var pos=_path.lastIndexOf("/");
+ _path=_path.substring(0,pos)+"/"+manualfilename;
+ \docSaveAs\newDO ({ cPath: _path });
+ doc.closeDoc();
+ doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
+ f=doc.getField("ManualTitle");
+ f.value=titleOfManual;
+ doc.flattenPages();
+ \docSaveAs\newDO({ cPath: manualfilename });
+ doc.closeDoc();
+} else {
+ console.println("Using the current "+manualfilename+" file.");
+}
+var _path=this.path;
+var pos=_path.lastIndexOf("/");
+_path=_path.substring(0,pos)+"/"+manualfilename;
+\addWatermarkFromFile({
+ bOnTop:false,
+ bOnPrint:false,
+ cDIPath:_path
+});
+\executeSave();
+\end{docassembly}
+
+\begin{document}
+
+\maketitle
+
+
+\selectColors{linkColor=black}
+\tableofcontents
+\selectColors{linkColor=webgreen}
+
+\def\AcroT{Acro\!\TeX}\def\cAcroT{\textcolor{blue}{\AcroT}}
+\def\AcroEB{\AcroT{} eDucation Bundle}\def\cAcroEB{\textcolor{blue}{\AcroEB}}
+\def\AcroB{\AcroT{} Bundle}\def\cAcroB{\textcolor{blue}{\AcroB}}
+\def\bUrl{http://www.math.uakron.edu/~dpstory}
+
+\hypersetup{linktocpage}
+
+\section{Introduction}
+
+This package is an add-on to the \env{quiz} environment of the \pkg{exerquiz}
+package.
+
+\paragraph*{Purpose.} This package adds PIN security to a quiz created by
+ the \env{quiz} environment. To correct a quiz, the document consumer must
+press the \uif{Correct} button of a quiz and successfully enter the correct
+PIN number. For example,
+
+\usePINCorrBtn
+
+\begin{quiz*}{qz1}
+Solve each, passing is 100\%.\hfill\llap{\smash{\parbox[t]{145pt}{\leavevmode\llap{\color{red}\ding{042}\enspace}Take the quiz, when finished, press the \uif{Correct} button and enter the PIN number
+to correct the quiz.}}}
+\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)\vcgBdry[6pt]
+
+Answers: \AnswerField\currQuiz\vcgBdry[6pt]
+
+ This package is designed for the educational sector, for instructors who use
+ the quizzes from the \pkg{exerquiz} package to assess the
+ understanding their students of the course material.
+
+ \paragraph*{PDF Viewers.} Discussion of PDF viewers for the document author and the document consumer.
+ \begin{aebQuote}
+ \begin{description}
+ \item[\textbf{Instructor:}] Any PDF viewer may be used as a PDF
+ \emph{previewer}, \app{sumatraPDF}, for instance. To verify the newly
+ created quiz is functioning correctly, \app{Adobe Reader DC}
+ (\FmtMP{\app{AR}}\app{AR}) or \app{Acrobat DC}
+ (\FmtMP{\app{AA}}\app{AA}) \emph{must be used}.
+ \item[\textbf{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 DC}(\FmtMP{\app{AR}}\app{AR}).
+ \end{description}
+ \end{aebQuote}
+ \paragraph*{Workflow.} The package is designed for the following workflow:\begingroup\tightsettings
+ \begin{enumerate}
+ \item The instructor creates\FmtMP{create quiz} the quiz using the
+ \pkg{exerquiz} and \pkg{eq-pin2corr} packages.
+ \item The instructor delivers\FmtMP{deliver quiz} the ``PDF quiz'' to
+ each student. (System drive or email)
+ \item The student takes\FmtMP{take quiz} the quiz. The student can
+ press the \uif{Correct} but, unless s/he knows the PIN, the quiz
+ is not marked up.
+ \item The student saves\FmtMP{save quiz} the PDF quiz in \app{Adobe
+ Reader DC}.
+ \item The student returns\FmtMP{return quiz} the PDF to the
+ instructor. (System drive or email)
+ \item The instructor opens the returned PDF quiz in AA/AR and
+ presses\FmtMP{correct quiz} the \uif{Correct} button to mark up
+ the quiz. The instructor \emph{saves the quiz}. The instructor
+ records the grade of the student.
+ \item The instructor returns\FmtMP{returns quiz} the PDF, at some
+ point, to the student.
+ \item Both instructor and student happily\FmtMP{happy people} go on
+ with their lives.
+ \end{enumerate}
+ The implementation details are left to the instructor.
+\endgroup
+
+\paragraph*{Document creation.} Any of the PDF creators current to the
+{\LaTeX} world can be used: (1) \app{pdflatex}, (2) \app{lualatex}, (3)
+\app{xelatex}, and my old friend, (4) \app{dvips}/\app{Distiller} (or
+\app{dvips}/\app{ps2pdf}). In the latter case (4), \app{Acrobat} is required
+to import Document JavaScripts.
+
+\section{The preamble}
+
+The minimal preamble for documents that use the \pkg{eq-pin2corr} package.
+\bVerb\def\1{\rlap{\hskip150pt\%\textsf{ or some other class}}}%
+\def\2{\rlap{\hskip150pt\%\textsf{ recommended but not required}}}%
+\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)]{eq-pin2corr}
+...
+\declPINId{!ameta(pin-num)}{!ameta(hash-string)}
+\classPINVar{!ameta(class-pin-var)}
+...
+\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).
+
+\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
+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
+in the same box (eg, \texttt{Score: 2 out of 3}), which is historically what
+always appears in these boxes. The other option \FmtMP{\opt{!showscore}}\opt{!showscore} is a
+convenience option to aid in switching from one option to the other without
+too much cut and paste. The default definition of the text string that
+appears is,
+\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
+\flJSStr[noquotes]{\SaveAndSendMsg}{Success! %
+Now save and send to the instructor}
+\end{Verbatim}
+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}
+
+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)}}
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\declPINId{!ameta(pin-num)}{!ameta(hash-string)}
+!1\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.
+\begin{aebQuote}
+\pushButton[\CA{Push}\AAmouseup{\btnAct}]{btn}{}{11bp}\olBdry
+\textField[\textSize{8}]{txt}{2in}{11bp}\olBdry
+\pushButton[\CA{Reset}\AAmouseup{this.resetForm();}]{reset}{}{11bp}
+\end{aebQuote}
+Press the button labeled \uif{Push} and enter your PIN number into the dialog
+box (enter, for example, \texttt{\numPINId}), then press \uif{OK}, the
+corresponding hash-string appears in the text field, \texttt{\hashPINId}.
+Copy the PIN number (\texttt{\numPINId}) into the first argument of
+\cs{declPINId} and copy the hash-string (\texttt{\hashPINId}) from the text
+field into the second argument, like so,
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+\declPINId{!numPINId}{!hashPINId}
+\end{Verbatim}
+The above is placed in the preamble of the document.
+
+When the user enters a PIN number (right or wrong), it is converted to a
+hash-string and compared with the hash string of the correct PIN number; if
+they match, then the quiz is corrected. It is important to note that the PIN
+number \emph{does not appear anywhere} in the document, so it cannot be
+discovered. Knowledge of the correct hash-string does not help. Of course
+both PIN number and hash string appear in the source file of the document.
+
+\paragraph*{\cs{classPINVar\darg{\ameta{class-pin-var}}}} From the
+instructor's viewpoint, it takes a lot of effort to enter the PIN number for
+every quiz that is submitted (it may be in the hundreds). There is a way of
+avoiding the requirement of entering the PIN number, and that is through the
+use of the \cs{classPINVar} command. This method will work if you have
+\app{Adobe Acrobat} or if you only have \app{Adobe Reader DC}. The steps for
+doing this are as follows:
+\begin{enumerate}
+ \item Decide on a class PIN variable name, it can be a generic one, or one specialize to your class,
+ for example, \cs{classPINVar\darg{Calc2Sprg21}}, then declare it in the preamble:
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\classPINVar{Calc2Spr21}
+\end{Verbatim}
+The value of the argument must be a valid JavaScript name.
+ \item Go to the user config.js file of AA/AR and edit that file by
+ including the following line in it,
+\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
+var Calc2Spr21 = "!hashPINId";
+\end{Verbatim}
+where the hash string used here is the same one corresponding to the PIN
+number for the document (\texttt{\numPINId} in our example).
+\end{enumerate}
+\app{AA/AR} only reads \texttt{config.js} one time when it opens, so
+\texttt{Calc2Spr21} will not be known until the next time \app{AA/AR} is opened.
+The location of the \texttt{config.js} file is described in general in the
+file \texttt{\href{install_jsfiles.pdf}{install\_jsfiles.pdf}}, found in the \texttt{doc} folder of this
+distribution.
+
+Once the above line is placed in the \texttt{config.js} file, the instructor does not
+enter the PIN number, pressing \uif{Correct} immediately corrects the quiz.
+
+\section{Turning the PIN security feature on and off}
+
+The security PIN feature can be turned on and off through the following two
+commands.
+\bVerb\takeMeasure{\string\restoreCorrBtn}%
+\def\1{\leavevmode\rlap{\sffamily\hskip\linewidth(Turn on PIN security)}}%
+\def\2{\leavevmode\rlap{\sffamily\hskip\linewidth(Turn off PIN security)}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+!1\usePINCorrBtn
+!2\restoreCorrBtn
+\end{dCmd}
+\eVerb These can placed anywhere outside a \env{quiz} environment. The
+commands take effect beginning at the next quiz in the document.
+
+\medbreak\noindent
+Now, I really must get back to retirement.\enspace\dps
+
+
+\end{document}