From fbd608287095ad7a2238d29b48a70a959997299e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 20 Feb 2021 22:16:10 +0000 Subject: eq-pin2corr (20feb21) git-svn-id: svn://tug.org/texlive/trunk@57815 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/latex/eq-pin2corr/doc/eq-pin2corr.pdf | Bin 0 -> 256673 bytes .../doc/latex/eq-pin2corr/doc/eqpin2corrman.pdf | Bin 0 -> 245015 bytes .../doc/latex/eq-pin2corr/doc/eqpin2corrman.tex | 423 +++++++++++++++++++++ .../doc/latex/eq-pin2corr/doc/install_jsfiles.pdf | Bin 0 -> 237391 bytes .../doc/latex/eq-pin2corr/doc/install_jsfiles.tex | 312 +++++++++++++++ 5 files changed, 735 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/eq-pin2corr/doc/eq-pin2corr.pdf create mode 100644 Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.pdf create mode 100644 Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.tex create mode 100644 Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.pdf create mode 100644 Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.tex (limited to 'Master/texmf-dist/doc/latex/eq-pin2corr/doc') diff --git a/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eq-pin2corr.pdf b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eq-pin2corr.pdf new file mode 100644 index 00000000000..92c3cec32bd Binary files /dev/null and b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eq-pin2corr.pdf differ diff --git a/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.pdf b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.pdf new file mode 100644 index 00000000000..0103c028ca3 Binary files /dev/null and b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.pdf differ diff --git a/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.tex b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/eqpin2corrman.tex new file mode 100644 index 00000000000..aa2f13dbc93 --- /dev/null +++ b/Master/texmf-dist/doc/latex/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} diff --git a/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.pdf b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.pdf new file mode 100644 index 00000000000..7b2d3fab788 Binary files /dev/null and b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.pdf differ diff --git a/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.tex b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.tex new file mode 100644 index 00000000000..56393183354 --- /dev/null +++ b/Master/texmf-dist/doc/latex/eq-pin2corr/doc/install_jsfiles.tex @@ -0,0 +1,312 @@ +\documentclass{article} +\usepackage[fleqn]{amsmath} +% +% the driver line is not necessary if you +% have aebpro.cfg configured to your driver. +% +\usepackage[web]{aeb_pro} +\usepackage{eforms} +\usepackage[altbullet]{lucidbry} +\usepackage{pifont} + +\usepackage{fancyvrb} + +\makeatletter +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt} + {\normalfont\normalsize\bfseries}} +\renewcommand{\subparagraph} + {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}% + {\normalfont\normalsize\bfseries}} +\makeatother + +\mathindent\parindent + +\def\AEBP{\app{AeB Pro}} +\def\AEB{\app{AeB}} +\def\app#1{\textsf{#1}} +\def\amtIndent{\parindent} +\def\meta#1{$\langle\textit{\texttt{#1}}\rangle$} +\def\SC#1{{\small#1}} +\def\PDF{\SC{PDF}} +\let\opt\texttt + +\def\copyGetPath{\qquad\pushButton[\TU{Copy app.getPath to console} +\CA{getPath}\A{\JS{console.show();\r +console.println('\\napp.getPath("user");'); +}}]{cpyGtPth}{}{11bp}} + +\def\copyGetPathJS{\qquad\pushButton[\TU{Copy app.getPath to console} +\CA{getPath}\A{\JS{console.show();\r +console.println('\\napp.getPath("user", "javascript");'); +}}]{cpyGtPthJS}{}{11bp}} + +%\reversemarginpar +\def\jsSupInstr{How to install JavaScript support files} +\title{\jsSupInstr} +\author{D. P. Story} +\version{1.0} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="How to install JavaScript files"; +var manualfilename="Manual_BG_Print_jsfiles.pdf"; +var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown +var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate; +var doc; +var buildIt=true; +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 + +\section{Introduction} + +Because some of the \app{Acrobat} JavaScript methods have security +restrictions, they can be only executed in the console window, or as part +of a batch sequence, or from the JavaScript folder reserved by +\app{Acrobat} for that use. The developer (of {\LaTeX} packages or {\PDF} +form documents) may want to use these restricted JavaScript methods as +part of document assembly. To use the restricted methods, they must be +called from the user JavaScript folder. The scripts are contained in a +\SC{JS} file that \app{Acrobat} reads when it first starts up. + +In this article, we provide detailed steps for locating the user +JavaScript folder. For {\AEB} and {\AEBP}, the files \texttt{aeb.js} and +\texttt{aeb\_pro.js} are placed in the folder. Other JavaScript files may +be placed in the folder as well, for example, the \texttt{config.js} file +is one that is commonly used for general purposes. + +Before we get started, if you are using a version of \app{Acrobat} prior +to version~8.1, you need not read any further. The security restrictions +described below were not in effect for those versions. + +\section{Installing the JavaScript support files} + +The functionality of {\AEB} and {\AEBP} depends, to some extent, on the +proper installation of their JavaScript support files. +\begin{itemize} + \item \AEB: For authors using the $\app{dvips}+\app{Acrobat Distiller}$ + workflow, \texttt{aeb.js} is required; this file is not used by + \app{pdflatex} or \app{xelatex} users. + + \item \AEBP: For authors using the $\app{dvips}+\app{Acrobat + Distiller}$ workflow, \texttt{aeb\_pro.js} is required; for authors + that prefer \app{pdflatex}, \app{lualatex}, or \app{xelatex} as the + {\PDF} creator \emph{and who own} the \app{Acrobat} application, + the \texttt{aeb\_pro.js} is required with the \opt{useacrobat} + option of \AEBP. When using the \opt{nopro} option of \AEBP, the + JavaScript file \texttt{aeb\_pro.js} is not used. + +\end{itemize} +The placement of the JavaScript files has changed over the years and is a +function of the version number \meta{ver}. Start \app{Acrobat} and open the +console debugger window by pressing \texttt{Ctrl+J} (for \app{Windows OS}) +or \texttt{Cmd+J} (for \app{Mac OS}). Now execute the code +\texttt{app.getPath("user")} in the console window. To do this, press the +\textsf{getPath} button provided below, which copies the necessary code to +the console window. +\begin{equation} +\begin{minipage}{.8\linewidth} +\begin{Verbatim}[commandchars={!~@}] +app.getPath("user");!copyGetPath +\end{Verbatim} +\end{minipage}\label{display:getPath} +\end{equation} +Now, with the cursor on the line containing the script, press the +\texttt{Ctrl+Enter} (for \app{Windows OS}) or \texttt{Cmd+Enter} (for +\app{Mac~OS}) key. This will execute the JavaScript and return the `root' +path to the user's application data for \app{Acrobat}. + +The rest of the instructions depend on your operating system, +\app{Windows} or \app{Mac}. + +\subsection{For users of \app{Windows OS}} + +There are several cases, jump to the numbered paragraph that describes your +version (\meta{ver}) of \app{Acrobat}. + +%/C/Users/D. P. Story/AppData/Roaming/Adobe/Acrobat/11.0 +%/C/Users/D. P. Story/AppData/Roaming/Adobe/Acrobat/Privileged/11.0/JavaScripts + +\def\Stepi{\ding{182}\enspace} +\def\Stepii{\ding{183}\enspace} +\def\Stepiii{\ding{184}\enspace} + +\paragraph*{{\Stepi}For $\boldmath\text{\meta{ver}}$, $\boldmath 8.1 \le +\text{\meta{ver}} < 10.1.1$.} For the \app{Windows OS}, executing the script +in display~\eqref{display:getPath} returns a string of the +form:\footnote{This string is for \app{Windows OS} beyond \app{WinXP}.} +\begin{equation} +\begin{minipage}{.8\linewidth} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/Acrobat/!meta(ver) +\end{Verbatim} +\end{minipage}\label{display:path} +\end{equation} +Navigate to this folder location. The correct location for the \SC{JS} +files is in the \texttt{JavaScripts} subfolder. If the folder does not +exist, create it. The final path for the JavaScript support files is then +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/ + Acrobat/!meta(ver)/JavaScripts +\end{Verbatim} +Finally, copy \texttt{aeb.js} (and \texttt{aeb\_pro.js}, if applicable) +into this folder. Close \app{Acrobat}, the next time \app{Acrobat} +is started, it will read in the \SC{JS} files. + +\paragraph*{{\Stepii}For $\boldmath\text{\meta{ver}}$, $\boldmath10.1.1 \le +\text{\meta{ver}} < 12$.} For these versions of \app{Acrobat} security has +have tightened up even more; the \texttt{JavaScripts} folder is now a +subfolder of a special \texttt{Privileged} folder. Execute +\texttt{app.getPath("user")} in the console window, as in +display~\eqref{display:getPath}. The method brings back a string similar to +the one in display~\eqref{display:path}. The correct path is obtained by +simply inserting \texttt{Privileged} into the path in +display~\eqref{display:path}, between \texttt{Acrobat} and \meta{ver}, as +displayed below. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/ + Acrobat/!textbf(Privileged)/!meta(ver)/JavaScripts +\end{Verbatim} +But this is a mere description of the correct location, the path must +exist! The path must be created, if it does not already exist. + +Navigate to the folder, one folder above the path shown in +display~\eqref{display:path}, that is, navigate to, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/Acrobat/ +\end{Verbatim} +If a \texttt{Privileged} folder exists, enter into it; otherwise, create +it, then enter it. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/Acrobat/Privileged +\end{Verbatim} +Now create a folder named \meta{ver}, unless it already exists, and enter +it. The version is always the major release \texttt{8.0}, \texttt{9.0}, +\texttt{10.0}, or \texttt{11.0}. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/ + Acrobat/Privileged/!meta(ver) +\end{Verbatim} +Finally, create the \texttt{JavaScript} folder, unless it already exists, +to obtain the final path to the user folder JavaScripts: +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/ + Acrobat/Privileged/!meta(ver)/JavaScripts +\end{Verbatim} +Copy \texttt{aeb.js} (and \texttt{aeb\_pro.js}, if applicable) into this +folder. Close \textsf{Acrobat}, the next time \textsf{Acrobat} is started, +it will read in the \SC{JS} files. + +\paragraph*{{\Stepiii}For $\boldmath\text{\meta{ver}}$, $\boldmath +\text{\meta{ver}} > 12 $.} Beginning with the next major version following +version~11, Adobe changed its versioning scheme. There are now two tracks, +\emph{subscription} and \emph{classic} (also called \emph{perpetual}). For +subscription, the version, as I understand it, will always be \texttt{DC} +(Document Cloud), and for the classic, for which you've purchased a +\emph{perpetual license}, the \meta{ver} is a calendar year. The first +classic version is \texttt{2015}, the next one is most likely \texttt{2017}, +since major releases occur about every two years. + +Execute the code of display~\eqref{display:getPath} by pressing the button +provided to obtain a path of the form, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/Acrobat/DC +\end{Verbatim} +for the subscription license or, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/C/Users/!meta(username)/AppData/Roaming/Adobe/Acrobat/2015 +\end{Verbatim} +for the classic (or perpetual) license. Of course, this last path is for +the first classic version. + +Now, to obtain the path to the \texttt{JavaScripts} folder, follow the +instructions for numbered paragraph \ding{183}, but with \meta{ver} equal +to either \texttt{DC} or \texttt{2015} (a calendar year). + +%/C/Users/D. P. Story/AppData/Roaming/Adobe/Acrobat/Privileged/11.0/JavaScripts + +\subsection{For users of \app{Mac OS}} + +\app{Mac OS} does not have the security restrictions that \app{Windows OS} +does, as described in paragraphs \ding{183} and \ding{184}. + +Follow the instructions of paragraph \ding{182}, by first pressing the button +provided in display~\eqref{display:getPath}, then, in the console window, +execute this script as described in the paragraph following +display~\eqref{display:getPath}. After working through \ding{182}, one +obtains any of the following paths depending on the version (\meta{ver}) you +are using:\medskip + +\noindent +For $\text{\meta{ver}} = \texttt{8.0}, \texttt{9.0}, \texttt{10.0}, +\texttt{11.0}$: +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/Users/!meta(user)/Library/Application\ Support/Adobe/ + Acrobat/!meta(ver)/JavaScripts +\end{Verbatim} +\medskip + +\noindent +For $\text{\meta{ver}} > 12$, the path is, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/Users/!meta(user)/Library/Application\ Support/Adobe/ + Acrobat/DC/JavaScripts +\end{Verbatim} +for a subscription license, and, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/Users/!meta(user)/Library/Application\ Support/Adobe/ + Acrobat/2015/JavaScripts +\end{Verbatim} +or more generally, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +/Users/!meta(user)/Library/Application\ Support/Adobe/ + Acrobat/!meta(year)/JavaScripts +\end{Verbatim} +for the perpetual license. + +In all cases, if the \texttt{JavaScripts} folder does not exist, it must +be created. Copy any \SC{JS} support files into the \texttt{JavaScripts} +folder. The script files are read the next time \app{Acrobat} is started. + +\section{Testing the placement of the JavaScript support files} + +Assuming you have successfully followed the instructions and created the +\texttt{JavaScripts} folder, test the validity of what you have done by +closing \app{Acrobat} then opening it again. Open the console window +(\texttt{Ctrl+J} or \texttt{Cmd+J}, for \app{Mac OS}) and execute this +command in the console window: +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars={!~@}] +app.getPath("user","javascript");!quad!copyGetPathJS +\end{Verbatim} +If you have followed the instructions, the return string should read the +complete path to the \texttt{JavaScripts} folder. +\end{document} -- cgit v1.2.3