diff options
Diffstat (limited to 'texmf-dist/doc/latex/dps/dpstheman.tex')
-rw-r--r-- | texmf-dist/doc/latex/dps/dpstheman.tex | 1823 |
1 files changed, 1823 insertions, 0 deletions
diff --git a/texmf-dist/doc/latex/dps/dpstheman.tex b/texmf-dist/doc/latex/dps/dpstheman.tex new file mode 100644 index 00000000..606a85b8 --- /dev/null +++ b/texmf-dist/doc/latex/dps/dpstheman.tex @@ -0,0 +1,1823 @@ +\documentclass{article} +\usepackage[% + web={designv,forcolorpaper,latextoc,extended}, + eforms={execJS} +]{aeb_pro} +%\usepackage[designv,nodirectory,forcolorpaper,latextoc]{web} +%\usepackage[execJS]{eforms} +\usepackage{graphicx} +\reversemarginpar + +%\usepackage{myriadpro} +\usepackage[altbullet]{lucidbry} +\usepackage{aeb_mlink} +\usepackage{acroman} + +\usepackage[active]{srcltx} + +\def\darg#1{\texttt{\{#1\}}} +\let\key\texttt + +%\setlength{\marginparsep}{0pt} +\addtolength{\marginparwidth}{15pt} + +\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}} + +%\margins{.25in}{.25in}{24pt}{.25in} % left,right,top, bottom +%\screensize{6.5in}{5in} % height, width + +\university{\AcroTeX.Net} +\title{dps Package\texorpdfstring{\\[1em]}{: }Das Puzzle Spiel} +\author{D. P. Story} +\email{dpstory@acrotex.net} +\subject{Documentation of the dps package} +\keywords{Adobe Acrobat, games, matching} + +\versionLabel{Dated:} +\version{2020/06/03} +\copyrightyears{2006-\the\year} +\nocopyright +\prepared{2020/06/03} %2020/06/03 v1.7 +\revisionLabel{Distribution Dated:} + +\DesignTitlePageTrailer +{% + ul=Copyright \copyright\ \webcopyrightyears, + ur=\thewebemail, + lr=\url{http://www.acrotex.net}, + raise=-25pt +} + + +\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% + \kern-.6em \hbox{$\mathcal S$}}$} + +\let\tops\texorpdfstring +\makeatletter +\let\web@copyright=\@gobble +\def\changelinkcolorto#1{\def\@linkcolor{#1}} +\newdimen\totaltextwidth +\totaltextwidth=\fullscreenwidth +\advance\totaltextwidth\oddsidemargin +\renewcommand{\@oddhead}{\hspace{-\oddsidemargin}% + \hbox to\totaltextwidth{\normalfont\footnotesize + \web@headerhook\web@lhead\hfil\web@chead\hfil + \web@rightheader}\hss}% +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt} + {\normalfont\normalsize\bfseries}} +\renewcommand{\subparagraph} + {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}% + {\normalfont\normalsize\bfseries}} +\makeatother + +\def\AcroTeX{Acro\negthinspace\TeX} +%\newenvironment{sverbatim} +%{\par\footnotesize\verbatim}{\endverbatim} + +%\newcommand\redpoint{\par\removelastskip +%\vskip\medskipamount +%\noindent +% \makebox[0pt][r]{\large\color{red}$\blacktriangleright$\enspace}} +%\newcommand\handpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi +%\vskip\medskipamount\noindent +% \makebox[\parindent][l]{\large\color{blue}\ding{042}}} +%\newcommand\newtopic{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi +%\vskip\medskipamount\noindent} +%\newcommand{\cs}[1]{\texttt{\char`\\#1}} + +\makeatletter +\newcommand{\linkSave}[2][]{\def\argi{#1}\ifx\argi\@empty\def\argi{#2}\fi + \setLinkText[\Border{0 0 0}\A{\JS{this.exportDataObject({cName: "\argi", nLaunch: 0})}}] + {\textcolor{webgreen}{#2}}} +\makeatother + +\def\FmtMP#1{\marginpar{\slshape\raggedleft\small#1}} + +\optionalPageMatter{% +\par\minimumskip\vspace{\stretch{1}} + \noindent\begin{minipage}{\linewidth} + \begin{center} + \fcolorbox{blue}{webyellow}{% + \begin{minipage}{.67\linewidth}\parskip3pt + \textcolor{red}{Abstract: }\textcolor{blue}{Das Puzzle Spiel} is a {\LaTeX} package for + creating a puzzle, a message actually, and a series of + questions and answers. The document consumer matches the + questions with the answers. With each match, another letter + appears in the puzzle. Upon completion of all questions, the + message hidden in the puzzle is revealed. The game has an application + as a classroom learning device. + \end{minipage}}% +% \par\bigskip +% \fcolorbox{blue}{webyellow}{% +% \begin{minipage}{.67\linewidth}\parskip3pt \tightsettings +% \textcolor{red}{Distribution: } Click on the link below, and +% save \texttt{dps.txt} to your hard drive.\footnote{If the link does not work for you, +% save \texttt{dps.txt} using the Adobe Reader user interface.} +% \begin{itemize} +% \item[] \texttt{\linkSave{dps.txt}} +% \end{itemize} +% Rename \texttt{dps.txt} to \texttt{dps.zip}. Unzip +% \texttt{dps.zip} somewhere in your {\LaTeX} search path. Unzipping +% will create a folder named \texttt{dps}. If using a {\TeX} system +% requires it, refresh your file name database. +% +% Brief descriptions of +% these files are given on +% \hyperref[distribution]{page~\pageref*{distribution}}. +%\par\smallskip +% \end{minipage}} + \end{center} + \end{minipage} +} + +\makeatletter +\renewcommand{\section}{% + \renewcommand{\@seccntformat}[1]{\csname the##1\endcsname.\enspace}% + \@startsection{section}{1}{-62.5pt}% + {-3ex\@plus -1ex \@minus-.2ex}% + {1ex\@plus .2ex}% 6pt + {\noindent\normalfont\large\bfseries\color{blue}}}% +\renewcommand\subsection{% + \renewcommand{\@seccntformat}[1]{\csname the##1\endcsname.\enspace}% + \@startsection{subsection}{2}{-42.5pt}% + {-2.5ex\@plus -1ex \@minus -.2ex}% + {1ex \@plus .2ex}% + {\noindent\normalfont\normalsize\bfseries\color{blue}}} +\makeatother + +%\parindent0pt +%\parskip\medskipamount + +% +% Attach the document target.pdf to this document +% +%\begin{execJS}{execjs} +%console.println("Importing data object"); +%var myPath = /.*\//i.exec(this.path); +%var thisPath = this.path.replace(/\.pdf$/, ".tex"); +%aebTrustedFunctions(this, aebImportDataObject, {cName:"dps.txt", cDIPath: myPath+"dps.txt" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"dps.dtx", cDIPath: myPath+"dps.dtx" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"dps.ins", cDIPath: myPath+"dps.ins" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"dps_demo.tex", cDIPath: myPath+"dps_demo.tex" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"pmg_d1.tex", cDIPath: myPath+"pmg_d1.tex" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"pmg_d1_p.tex", cDIPath: myPath+"pmg_d1_p.tex" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"pmg_d2.tex", cDIPath: myPath+"pmg_d2.tex" }) +%%aebTrustedFunctions(this, aebImportDataObject, {cName:"pmg_d3.tex", cDIPath: myPath+"pmg_d3.tex" }) +%\end{execJS} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The DPS Package"; +var manualfilename="Manual_BG_Print_dps.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} + + +\begingroup + +\linewidth=\fullscreenwidth\relax +%\advance\linewidth\oddsidemargin +%\setlength{\oddsidemargin}{0pt} +\maketitle + +\endgroup + +\changelinkcolorto{black} + +\tableofcontents + +\changelinkcolorto{webgreen} + + +\section{Introduction} + +The work on this package was inspired by one of my son's worksheets +in pre-algebra. The worksheet consisted of a series of simple +algebraic expressions the student was to simplify. The simplified +form was listed somewhere in the answers column. The answer had a +letter associated with it which the student then placed in a puzzle. +Upon completion of the worksheet, the puzzle (message) is completely +filled in; if the message makes sense, the student can determine +that he/she did the worksheet correctly. + +I set out to duplicate this worksheet for electronic media, but +also to have an option for paper as well. +\begin{figure}[htb]\centering\fboxsep0pt +\fbox{\includegraphics[width=.45\linewidth]{graphics/normal}}\hfil +\fbox{\includegraphics[width=.45\linewidth]{graphics/normal-partial}} +\caption{\texttt{dps\_demo.pdf}: Initial layout (left) and partially worked (right)} +\end{figure} +\section{Requirements} + +The following packages are required for \textsf{dps} beyond that of +the standard {\LaTeX} distribution: +\begin{itemize} + \item \pkg{AeB}:\footnote{\url{https://ctan.org/pkg/acrotex}} The + \pkg{web} and \pkg{eforms} components of the + Acro\negthinspace\TeX{} eDucation Bundle are used. + \item + \texttt{\href{https://ctan.org/pkg/random}{random.tex}}:\footnote{\url{https://ctan.org/pkg/random}} + A \TeX/\LaTeX{} macro file to generate random numbers, the package + was written by Donald Arseneau. + \item If the \opt{usebtnappr} option is taken, the \pkg{icon-appr} + package, dated 2020/06/05 or later, is + required.\footnote{\url{https://ctan.org/pkg/icon-appr}} +\end{itemize} +The package should work for users of \app{dvips\,->\,distiller}, \app{pdflatex}, +\app{lualatex}, and \app{xelatex}. A document author who owns the +\app{Acrobat} application and plans to use either the \opt{usebtnappr} or +\opt{uselayers} option should have the \pkg{aeb\_pro} package (completely) installed. + + +\section{Comments on the demo files}\label{distribution} + +The distribution comes with the following demonstration files. + +\begin{itemize} + \item \texttt{examples/basic/dps\_demo.tex}\FmtMP{\texttt{basic} folder}: A demo file that you can use to + try the package with different options. Build the source file for + screen or for paper. Two column format for questions, and half the + answers on the left, and half on the right. + + This demo file has more answers than questions. + + \item \texttt{examples/basic/dps\_d1.tex}\\ The original file constructing during + the development of this package. This puzzle has the famous + u-umlaut. Can be compiled with the + \opt{forpaper}/\allowbreak\opt{forcolorpaper} option of web. The layout + is designated as ``design 1'' (d1): questions in center in two column format + and answer on the left and right. + + This demo file illustrates the special name of \texttt{cr}, as well as \texttt{space} and \texttt{punc}. + + \item \texttt{examples/basic/dps\_d1\_p.tex}\\Same as \texttt{dps\_d1.tex}, but set up + as a paper document (using the \opt{forcolorpaper} option). The font size is + enlarged to make it easier for filling the puzzle out using a + pencil. + + \item \texttt{examples/basic/dps\_d2.tex}\\ Same puzzle/questions as + \texttt{dps\_d1.tex}, but uses the layout designated as + ``design~2'' (d2): Questions and answer in column format on left + and right, puzzle in the center. This leaves a lot of white space + in the middle, perhaps for a graphic. This example also manually + inserts the answer key command \cs{AnswerKey}, which manifests + itself when the \opt{showletters} option is taken. + + \item \texttt{examples/basic/dps\_d3.tex}\\ Same puzzle/questions as + \texttt{dps\_d1.tex}, but uses the layout designated as + ``design~3'' (d3): Puzzle and questions vertically aligned + (questions in two column format), answer in single column. This + file uses many of the formatting commands mentioned in the + documentation. + \item \texttt{examples/basic/dps\_signin.tex}\\ Demonstrates how to require + the player to enter his/her name, useful when puzzle is to be handed + in for extra credit. + \item \texttt{examples/basic/dps\_demo.tex}\\ Indicates how to change the appearance + of some of the form elements of the puzzle. + \item \texttt{examples/basic/stat\_match1.tex}\\ + An example of a puzzle with extended length questions. Demo can be + used as a paper assignment or a digital assignment. + \item\texttt{examples/basic/stat\_match1-print.tex}\\ + A layout with long questions designed for paper. +\end{itemize} +There are several ``advanced examples'' that demonstrate two methods +of posing \emph{extended length questions}; these two methods correspond to the two +options \opt{usebtnappr} and \opt{uselayers}. +%use the full power of +%\app{Adobe Acrobat} and its \app{Adobe Distiller} companion. The four +%examples are found in the \texttt{examples/aeb\_pro} folder. They are compiled +%with a \app{dvips \texttt{->} distiller} workflow. +\begin{itemize} +\item \texttt{examples/advanced/usebtnappr/basic/stat\_match1.tex}\FmtMP{\texttt{usebtnappr} folder}\\ + Uses the \opt{usebtnappr} to create icon pushbutton appearances of the + extended length questions. This example works for all common workflows: + \app{pdflatex}, \app{lualatex}, \app{xelatex}, and + \app{dvips\,->\,distiller}. + +\item \texttt{examples/advanced/usebtnappr/sideshow/first\_date.tex}\\ + A file developed from by cyber buddy, who I've never met, + to offer advice for going on a date \textsl{mit eine + Fr\"{a}lein}. This example works for all common workflows: + \app{pdflatex}, \app{lualatex}, \app{xelatex}, and + \app{dvips\,->\,distiller}. Uses a graphical sideshow. + +\item \texttt{examples/advanced/uselayers/basic/stat\_math1-tb.tex}\FmtMP{\texttt{uselayers} folder}\\ + Uses the \opt{uselayers} option and the \pkg{textpos} package. + + An extra credit assignment given to my statistics class in 2006. The + questions are placed in separate layers and appear when a question + checkbox is selected; this allows for more wordy questions without + taking up a lot of space in the question part of the puzzle. + +\item \texttt{examples/advanced/uselayers/basic/stat\_math1-ep.tex}\\ + Same as puzzle as \texttt{stat\_math1-tb.tex} but uses the + \pkg{eso-pic} package. + +\item \texttt{examples/advanced/uselayers/basic/stat\_math1\_g.tex}\\ Same as a + \texttt{stat\_math1-tb.tex}, but more graphical. If memory serves, this + version was developed my good cyber friend J\"{u}rgen. + +\item \texttt{examples/advanced/uselayers/sideshow/first\_data.tex}\\ A file developed + from by cyber buddy, who I've never met, to offer advice for going on a + date \textsl{mit eine Fr\"{a}lein}. Uses a graphical sideshow. + +\item \texttt{examples/advanced/uselayers/sideshow/first\_data\_g.tex}\\ + More graphical version of \texttt{first\_data.tex}, but with different + design and graphical sideshow. +\end{itemize} + +\section{Package Options}\label{packopts} + +Here we list the options of package \textsf{dps}. + +\begin{description} +\item[\normalfont{\opt{nonrandomized}}:] The default behavior is to + randomize the questions and to randomize the answers. With this + option, the questions and answer are listed in the order that they + appear in the \env{Composing} environment. This makes it easy for + the document author to quickly solve the puzzle and to see if the + check marks and letters appear as they should. + +\item[\normalfont{\opt{!nonrandomized}}:] (Convenience option) Cancels the effects of + \opt{nonrandomized}; in this case, the answers are randomized (the + default). + +\item[\normalfont{\opt{viewmode}}:] Useful when using a dvi previewer or a + PDF previewer. Here you can see the placement of the puzzle (with the + letters to the puzzle filled in) and the boxes were the checkboxes go. + Useful in the designing the layout of your game phase. + +%\end{description} +\begin{figure}[htb]\centering\fboxsep0pt +\fbox{\includegraphics[width=.67\linewidth]{graphics/view-mode}} +\caption{Compiled with \opt{viewmode} option} +\end{figure} +%\begin{description} + +\item[\normalfont{\opt{!viewmode}}:] (Convenience option) Cancels the effects of +\opt{viewmode}, this same as not specifying \opt{viewmode}. + +\item[\normalfont{\opt{showletters}}:] Sets up a visual relation + between the questions, the answers and the puzzle elements. Useful + in design phase, can be used with \texttt{viewmode}. Refer to \hyperref[fig:shwltrs]{Figure~\ref*{fig:shwltrs}}. + + When \opt{showletters}, the command \cs{AnswerKey} is populated with + the answer key to the puzzle. \cs{AnswerKey}\FmtMP{\cs{AnswerKey}} is automatically inserted + into the running footer when the \opt{showanswerkey} option is taken; + otherwise, it can be manually inserted into the document by expanding + \cs{AnswerKey} in a location somewhere \emph{after} the building of the + puzzle, the questions and the answers. + +\begin{figure}[htb]\centering\fboxsep0pt +\fbox{\includegraphics[width=.67\linewidth]{graphics/show-letters}} +\caption{Compiled with \opt{showletters} option}\label{fig:shwltrs} +\end{figure} + +\item[\normalfont{\opt{!showletters}}:] (Convenience option) Cancels the effects of +\opt{showletters}; in this case, the letters are not shown (the default). + +\item[\normalfont{\opt{showanswerkey}}:] Shows the answer key in the + footer of the document. If the \textsf{graphicx} package is loaded, + the answer key is rotated $180^\circ$. This option is meant to be + used when the \texttt{forpaper} option is taken in the \textsf{web} + package. Refer to \hyperref[fig:ansky]{Figure~\ref*{fig:ansky}}. + +\begin{figure}[htb]\centering\fboxsep0pt +\fbox{\includegraphics[width=.67\linewidth]{graphics/answer-key}} +\caption{Compiled with \opt{showanswerkey} option}\label{fig:ansky} +\end{figure} + + + The positioning of the running footer may be adjust using the + convenience command + \cs{setdpsfootskip\darg{\ameta{skip}}}\FmtMP{\cs{setdpsfootskip}}. + When there is no paper option for \pkg{web} (neither \opt{forpaper} or + \opt{forcolorpaper}), \ameta{skip} is the distance up from the bottom + edge of the screen page. The default is + \cs{setdpsfootskip\darg{.25in}}. When there is a paper option, this + command does nothing; location of the running footer is determined by + the {\LaTeX} \cs{footskip} register. + +\item[\normalfont{\opt{!showanswerkey}}:] (Convenience option) Turns off + the \opt{showanswerkey} option. + +\item[\normalfont{\opt{savedata}}:]\label{item:savedata} Saves three pieces of information to + the local hard drive : (1) the seed value used by the \texttt{random} + package to randomize the questions and answers; (2) the value of the + last number generated; and (3) the answer key. This information is + saved to the file \cs{jobname\_data.sav}. + \begin{itemize} + \item The seed value can be used to reproduce the exact + randomization at a later time. Open the file + \cs{jobname\_data.sav} in your editor, it might look like this: +\begin{Verbatim}[fontsize=\small] +\randomi=482053344 % Initial seed: +\dpsLastSeed{271256117} +% Answer Key: 1--e; 2--s; 3--i; 4--u; 5--l; 6--d; 7--a; 8--z; 9--p; +\end{Verbatim} + Copy the number indicated as the \textsf{Initial seed} and paste it + into the argument \cs{useRandomSeed\darg{482053344}}. Place this + command in the preamble, below the \verb!\usepackage{dps}! line. + This should reproduce the same randomization. + + \item The second line is use when the \cs{useLastSeed} command + appears in the preamble. This is the last number generated by the + current compile. + + \item The third line in the above verbatim listing is the answer key, + for the randomization initiated by the seed on the first line. + You can copy and paste this second line into the {\TeX/\LaTeX} + document and publish the solution in a separate document, at a + later time. This is useful when publishing for paper. + \end{itemize} +\item[\normalfont{!\opt{savedata}}:] (Convenience option) Turns + off the \opt{savedata} option. + + +\item[\normalfont\opt{usebtnappr}] Use this option to provide support for + longer questions without taking up anymore space on the digital page. + The option uses icon appearances of a push button. + Refer to Section~\ref{s:usebtnappr}. + + +\item[\normalfont\opt{uselayers}] Use this option to provide support for + longer questions without taking up anymore space on the digital page. + The option places the long question in separate layers (OCGs). Refer to + Section~\ref{s:uselayers}. + +%\item[\normalfont\opt{wrtcontent}] An option that is only effective with the +%\opt{usebtnappr} option. Refer to Section~\ref{s:usebtnappr} for more information. +%\item[\normalfont\opt{!wrtcontent}] (Convenience option) Turns off the +%\opt{usebtnappr} option. + +\item[\normalfont{\opt{lang=english|german|custom}}:] Currently, there + are only two language options. The value of \opt{custom} allows you to + create your own language strings. + + To use the \texttt{lang=custom} + option, you must create the file \texttt{dps\_str\_cus.def}. Do this by + taking the file \texttt{dps\_str\_us.def} (or \texttt{dps\_str\_de.def}, + if you prefer), copying the file and changing its name to + \texttt{dps\_str\_cus.def}. Open \texttt{dps\_str\_cus.def} in your + favorite editor and change the text strings to a language of your + choice, or change the strings that tickle your funny bone more than the + ones provided.\footnote{Or tickle your funny bone \emph{less}, if you + are a crusty one.} To represent accented characters, use the octal + encoding defined in \texttt{pd1enc.def}, as distributed with + the \pkg{hyperref} bundle. The u-umlaut, for example, should appear + in the file as \verb!\string\374! and not as \verb!\"{u}!. + + \textbf{\textcolor{red}{Change notification:}} If you have already written + your own \texttt{dps\_str\_cus.def} for an earlier version of \pkg{dps}; + there is a change your should attend to: In the definition of + \cs{regretPleased} change \texttt{(\,nMissed\,>\,n\,)} to read \texttt{(\,nMissed\,>\,nPassing\,)}. + +\newtopic\noindent\makebox[0pt][r]{\large\color{red}$\blacktriangleright$\enspace}\ignorespaces +For your convenience, the \Nameref{appendix} contains a +listing of the octal codes for accented letters. +Here is an important option of \textsf{web} package. + +\item[\normalfont{\opt{forpaper/forcolorpaper}}:] These are options +of the \textsf{web} package, not the \textsf{dps} package. Then this +option is taken, the puzzle created is meant for paper publication. +No \app{Acrobat} forms will be created, the \texttt{showletters} option of +\textsf{dps} is automatically taken. If you originally designed the +game for the screen, you may have to rework the sizing and design of +the game to fit everything into the constraint of a piece of paper. +Landscape is an option to think about, depending on your design and +the number of questions and answers. +\end{description} + + +\section{Designing your Puzzle} + +There are several test files that you can use as basis of +constructing your own puzzle.\footnote{My apologies, this game is +more properly described as a matching game with message, but my +friend insisted that I call it a puzzle so that the package could be +named Das Puzzle Spiel, or dps, which are my initials. \dps} The +files themselves illustrate adequately the structure of the puzzle, +but a few remarks are in order. + +\subsection{\texorpdfstring{\protect\cs{DeclarePuzzle}}{\textbackslash DeclarePuzzle}}\label{s:DP} + +The first step is to have a message, either funny, serious, or +whatever. For the purpose of illustration, suppose your message is +``Hello, J\"{u}rgen!'' This message has all the elements that need +to be discussed, letters, punctuation, spaces, capitalized letters, +and accented letters. + +\newtopic\noindent{\normalfont\cs{DeclarePuzzle\darg{\ameta{puzzle-args}}}:} The +\ameta{puzzle-args} consists of a series of \textit{paired parameters}:\setlength{\leftmargini}{\parindent} +\begin{quote}\ttfamily + \string\nPuzzleCols\{\ameta{nCols}\}\quad\% \textsf{optional}\\ + \string\DeclarePuzzle\{\%\\ + \null\qquad\darg{\ameta{letter\SUB1}}\darg{\ameta{name\SUB1}}\\ + \null\qquad\darg{\ameta{letter\SUB2}}\darg{\ameta{name\SUB2}}\\ + \null\qquad\dots\\ + \null\qquad\dots\\ + \null\qquad\darg{\ameta{letter\SUB{n}}}\darg{\ameta{name\SUB{n}}}\\ + \} +\end{quote} +\cs{nPuzzleCols\darg{\ameta{nCols}}} is a convenience command for setting +the number of columns in the puzzle; \ameta{nCols} is passed to +\cs{insertPuzzle\darg{\ameta{nCols}}}, which appears in the body of the document. + +\newtopic\textbf{Parameter description for \cs{DeclarePuzzle}.} + The argument \ameta{letter} represents a letter in the puzzle; + \ameta{letter} plays two roles: (1) it is used to typeset the letters into + the document when certain options, such as \opt{viewmode}, are used; (2) it + is used as the default value of a text fields that is created (when the + puzzle is built to be interactive). This creates a problem for special + characters, such as \"{u}; it is a typeset letter, and is \verb~\string\374~ + when placed into a text field (\cs{341}) is the (octal) PDFDocEncoding of + u-umlaut. The way around this conundrum is to use \cs{texorpdfstring}: use + \ameta{letter} to be, + \begin{Verbatim}[xleftmargin=\amtIndent,commandchars={!()}] + \texorpdfstring{\protect\"{u}}{\ifxetex! !"(u)\else\string\374\fi} + \end{Verbatim} + Notice the use of \cs{protect} to protect this moving argument. Also + included above is a special case for \app{xelatex}, which does not support + the octal notation; in this case, using the capabilities of your editor, + simply type in an u-umlaut. The above complex expression is normally not + needed. Here, we try to provide guidance for all PDF creators. If you stick + to one, the \cs{ifxetex} conditional is not needed. + + The second argument pair is \ameta{name}, this is a unique name that is used + in the construction of the underlying text field name: the field name + becomes \texttt{puzzle.\ameta{name}}. As a result, \ameta{name} needs to be + a JavaScript identifier (or, basically consist of letters and numbers). In + the case of special characters such as our umlaut problem, we can assign a + name like so: +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars={!()}, + codes={\def\OR{\llap{\rlap{\textsf{or}}\kern15pt}}}] +\texorpdfstring{\protect\"{u}}{\ifxetex! !"(u)\else\string\374\fi}{uml} +!OR +\tops{\protect\"{u}}{\ifxetex! !"(u)\else\string\374\fi}{uml} +\end{Verbatim} +where \cs{tops}\FmtMP{\cs{tops}} is an alias for \cs{texorpdfstring}. This +argument pair is seen several times in the demonstration files. There are +three special names, these are \texttt{space}, \texttt{punc}, and +\texttt{cr}; as a argument pair, these should appear as follows: +\verb!{}{space}!\FmtMP{\texttt{space}}, \verb~{,}{punc}~\FmtMP{\texttt{punc}}, and +\verb~{}{cr}~\FmtMP{\texttt{cr}}, respectively. Spaces and punctuation are not normally part of +the puzzle to be discovered by answering questions, though they could be. +The special name \texttt{cr} terminates a row. + +%The argument consists of a series of \textit{paired parameters}, the first of +%each pair is a letter in the puzzle, a punctuation or a space; and the second +%in the pair is a name, which is used as a field name for the underlying form +%fields. + +\newtopic\indent +In the design of the puzzle there are three sets of form fields to +manage: checkboxes for the questions, checkboxes for the answers, +and text fields for the puzzle. The checkboxes and puzzle letter are +all tied together by a common base field name, which is the second +parameter in the parameter pairs. + +\newtopic\indent +In our puzzle, ``Hello, J\"{u}rgen!'', we place the \cs{DeclarePuzzle} +in the preamble, as shown in \hyperref[fig:HJ]{Figure~\ref*{fig:HJ}}. +For letters, the second parameter in the pair can simply be the same, as in +\verb!{H}{H}! and \verb!{e}{e}!. + +\begin{figure}[htb]\centering +\begin{minipage}{3in} +\begin{Verbatim}[fontsize=\small,commandchars={*()}] +\DeclarePuzzle{% + {H}{H} + {e}{e} + {l}{l} + {l}{l} + {o}{o} + {,}{punc} + {}{space} + {J}{J} + {\tops{*textbf(\protect)\"{u}}% + {\ifxetex*space*"(u)\else*textbf(\string)\374}\fi}{uml} + {r}{r} + {g}{g} + {e}{e} + {n}{n} + {!}{punc} +} +\end{Verbatim} +\end{minipage} +\caption{The ``Hello, J\"{u}rgen'' Puzzle}\label{fig:HJ} +\end{figure} + +%For punctuation, the first argument is the punctuation mark, the +%second is a special name \texttt{punc}; consequently, you see in the +%above \verb!{,}{punc}! and \verb!{,}{punc}!. Punctuation is not part +%of the puzzle (though it could be), the macro that ultimately processes +%this list of paired parameters looks for the name \texttt{punc}, and +%handles it appropriately. + +%The space character also has a special second parameter +%\texttt{space}. The space will have a place in the puzzle, but has +%no question/answer corresponding to it. + +%Finally, there are the special latin-1 letters. In the puzzle above, I have +%an u-umlaut. The problem is that this umlaut appears in two contexts, a +%{\TeX} and PDF context; the u-umlaut will appear as typeset content by {\TeX} +%and will appear as a value of an Acrobat form field. The representation is +%different in each context. In this case, use the \textsf{hyperref} command +%\cs{texorpdfstring} (use can use a special alias command \cs{tops} as well). +%\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +%{\texorpdfstring{\"{u}}{\string\374}}{uml} +%{\tops{\"{u}}{\string\374}}{uml} +%\end{Verbatim} +%The first argument of the u-umlaut is +%\verb!\texorpdfstring{\"{u}}{\string\374}! (or +%\verb!\tops{\"{u}}{\string\374}!). When typeset, the first argument of the +%command \cs{texorpdfstring} (when the option \opt{viewmode} is active, for +%example) is used and in the PDF context, the second argument is used. + +\begin{quote} +\textbf{\textcolor{red}{Rule:}} As a general rule, and this rule will be +repeated later, there should be one question for each distinct second +argument (\ameta{name}). There should be \emph{no question} corresponding to the +names \texttt{space}, \texttt{punc}, and \texttt{cr}. +\end{quote} +In the example of \hyperref[fig:HJ]{Figure~\ref*{fig:HJ}}, letters like \texttt{e} and \texttt{l} appear +more than once in the puzzle. Note that the second argument of each +of these two \texttt{e}'s is the same. There should be only one for +this \texttt{e}, and when the question associated with \texttt{e} is +correctly answered, both \texttt{e}'s in the puzzle will appear. (If +you want a question for each \texttt{e}, then you need to name the +fields differently, \verb!{e}{e1}! and \verb!{e}{e2}!, for example.) + +\subsection{Begin composing the questions and answers}\label{composing} + +We create questions and answers for the puzzle within the \env{Composing} +environment. Questions are posed within the \env{cQ} environment and answers +are written within the \env{cA} environment. +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\DeclarePuzzle{!ameta(puzzle-args)} +\begin{Composing} +\begin{cQ}{!ameta(name)} +!qquad!ameta(!sffamily(some question)) +\end{cQ} +\begin{cA}[!ameta(alt-letter)]{!ameta(name)} +!qquad!ameta(!sffamily(some answer)) +\end{cA} +... +\end{Composing} +\end{Verbatim} +\begin{description} +\item[\normalfont\env{Composing}:] You compose the questions and + answers within the \env{Composing} environment. At the top of + the environment, certain counters are initialized. All the work + is done at the end of the environment: The number of questions + and answers are known, at which point, the order of the + questions and answers are randomized. + + The \env{Composing} environment follows \cs{DeclarePuzzle}. + +\item[\normalfont\env{cQ} and \env{cA}:] Within the + \texttt{Composing} environment, you compose your questions and + answers within the \env{cQ} and \env{cA} environments, + respectively. Each question must be followed by its answer. + You can have more answers than questions, but these answers + \emph{must} be listed last. +% (The answers will be randomized anyway.) +\end{description} +Each of these environments has one required argument, and \env{cA} has one +optional argument. The required argument, \ameta{name}, is the field name to +which this answer corresponds. (The second argument of the paired arguments +of \cs{DeclarePuzzle}.) + +This optional argument, \ameta{alt-letter}, of the \texttt{cA} environment is +only relevant when the document is compiled with the \texttt{showletters} +option. The value of the argument is a letter to appear in the answers column +(and in the answer key). Normally, one of the first entries in the +\cs{DeclarePuzzle} command is used. Cases where you would want to include +this optional argument are, +\begin{quote} +\begin{enumerate} +\item[(1)] when giving an answer that does not correspond to a question. + For example, in \texttt{dps\_demo.tex}, there are several answers that + are distractions +\begin{Verbatim}[xleftmargin=\amtIndent] +\begin{cA}[w]{fake1} +$14x+10$ +\end{cA} +\end{Verbatim} +In the puzzle this answer appears in the list of answers but does not correspond +to any question. The letter associated with this answer is `w'. + +\item[(2)] the letter is capitalized, suggesting a proper name or the +beginning of a sentence, use the optional argument to list the letter in +lower case. For example, +\begin{Verbatim}[xleftmargin=\amtIndent] +\begin{cA}[h]{H} +$-2x-2$ +\end{cA} +\end{Verbatim} +\end{enumerate} +\end{quote} + +\paragraph*{Easily set up the \env{Composing} environment.} Once you +decide on your puzzle (this is easy), you need to set up the corresponding +environments \env{Composing}, \env{cQ}, and \env{cA}. +\begin{quote} +\textbf{\textcolor{red}{Rule:}} As a general rule, and this rule will be +repeated later, there should be one question for each distinct second +argument, that is, for each distinct \ameta{name}, with the exception of +the names \texttt{space}, \texttt{punc}, and \texttt{cr}. +\end{quote} +Because of human errors, sometimes we have questions/\allowbreak answer pairs +that correspond to a duplicate field name---perhaps this letter occurs +multiple times. No, no, that violates the red rule above. After having made +this same error several times myself, I decided to let {\TeX} do the work for +me. + +\newtopic\noindent Just after the end of the + argument of \cs{DeclarePuzzle}, prior to authoring the questions and + answers, place the \cs{writeComposingEnv}: +\begin{Verbatim} +\writeComposingEnv +\end{Verbatim} +Remember, \cs{DeclarePuzzle} is in the preamble and the beginning of document +has not been encountered; the command writes an outline for the +puzzle---based on the arguments of \cs{DeclarePuzzle}---to the file +\cs{jobname\_comp.def} and ends the document. Once this file is created, copy +and paste its contents into your source file. It should look like this: +\begin{verbatim} +\begin{Composing} + +\begin{cQ}{M} +\end{cQ} +\begin{cA}{M} +\end{cA} + +\begin{cQ}{a} +\end{cQ} +\begin{cA}{a} +\end{cA} +... +\end{Composing} +\end{verbatim} +The correct number of environments should be there, with the correct +argument inserted for each environment. Cool! Now, just compose your +questions and answers. + +After \cs{jobname\_comp.def} is created and copied into the puzzle document, +\emph{delete the} command \cs{writeComposingEnv}. This command is not part of +the puzzle, but a helper command. As an option, rather than pasting the +contents into your document following the \cs{DeclarePuzzle}, you can fill in +your questions and answers to your puzzle within the \cs{jobname\_comp.def}, +input the file \cs{jobname\_comp.def} with \verb!\input{\jobname_comp.def}!. +\textcolor{red}{\textbf{Warning:}} If you leave your questions and answers in +the auxiliary file \cs{jobname\_comp.def} you may overwrite them by +un-commenting \cs{writeComposingEnv} and compiling your puzzle document. + +\newtopic\noindent Another rule: +\begin{quote} +\textbf{\textcolor{red}{Rule:}} You must have one correct answer per + question. Each answer is unique in the list of all answers (no two + answers can be the same). You can have more answers than questions + (distractions---answers ``close'' in appearance to the correct + answer). Each of the distractions must have a unique \ameta{name}. +\end{quote} + +\section{Placing the Content} + +The content consists of five parts, plus whatever you wish to include +in the document: +\begin{enumerate} + +\item The title and instructions. + +\item The puzzle + +\item The questions + +\item The answers + +\item The message field + +\end{enumerate} +Each of these is discussed the the sections that follow. + + +\subsection{The title and instructions} + +The title and instructions are your bailiwick, see package demo files +for suggestions. + +\subsection{The puzzle} + +\begin{description} +\item[\normalfont{\cs{insertPuzzle\darg{empty|\ameta{nCols}}}}:] The + puzzle, which consists of the first of the paired arguments declared in + the \cs{DeclarePuzzle} command, is laid out in a tabular format. The + one required argument of \cs{insertPuzzle} is either the empty argument + (\darg{}) or \ameta{nCols}, the number of columns per row to be used. + + If you say \cs{insertPuzzle\darg{}}, then + \cs{nPuzzleCols\darg{\ameta{nCols}}} is expected to appear in the + preamble. If the argument of \cs{insertPuzzle} is empty and + \cs{nPuzzleCols} does not appear in the preamble, a warning is issued + and \ameta{nCols} is set to 10. + + In the demo files, \cs{insertPuzzle} is enclosed in a \texttt{minipage} + environment (and in a \cs{fbox} as well). By placing \cs{insertPuzzle} in + this way, you can control the width of the table, and it may help fit it with + the other components of the game. + +\item[\normalfont{\cs{PuzzleAppearance}}:] Use this command to change + the appearance of the \app{Acrobat} text field that comprise the + interactive puzzle. The command takes one argument, this argument + consists of one or more commands from the \textsf{eForms} package + that change the appearance of a field. For example, +\begin{Verbatim}[commandchars=!()] +\PuzzleAppearance{\BC{1 0 0}} +\PuzzleAppearance{\BC{red}} %!textsf( if !pkg(xcolor) is loaded) +\end{Verbatim} +changes the boundary color to red. See the \pkg{eforms} +documentation. + +\item[\normalfont{\cs{rowsep\darg{\ameta{skip}}}}:] By setting \cs{rowsep}, you can adjust + the vertical space between tabular rows. The commands takes one + argument, the amount of vertical skip, for example, +\begin{Verbatim} +\rowsep{2ex} +\end{Verbatim} +\item[\normalfont{\cs{wdPuzzleFields\darg{\ameta{length}}}}] Sets the width of a puzzle field + to \ameta{length}. The default is 1.6em +\item[\normalfont{\cs{htPuzzleFields\darg{\ameta{length}}}}] Sets the height of the puzzle field +to \ameta{length}. The default is 11bp. +\end{description} + +\subsection{The questions} + +\begin{description} +\item[\normalfont{\cs{displayRandomizedQuestions}}:] The questions are + inserted by this command. This command must be placed in an + \texttt{enumerate} environment. This will number the questions, + so when, for example, the \texttt{showletters}, discussed later, + is taken, there is a visual mapping between the questions, the + answers and the puzzle. + +If the number of questions is not great, you can list the questions +in a single column; however, in the examples that I have done, I've +determined that a two column format (using the \texttt{multicol} +package) seems to me to be the best layout for the questions. + +\item[\normalfont{\cs{QuesAppearance}}:] Use this command to change the + appearance of the \app{Acrobat} checkboxes for the questions that + appear in the label margin. The command takes one argument, this + argument consists of one or more commands from the + \textsf{eForms} package that change the appearance of a field. + For example, +\begin{Verbatim}[commandchars=!()] +\QuesAppearance{\BC{gray}} %!textsf( assumes xcolor pkg or just !cs(BC{.5 .5 .5})) +\end{Verbatim} +changes the boundary color to a gray color. See the \pkg{eforms} documentation. + +\item[\normalfont{\cs{widestFmtdQNum\darg{\ameta{str}}}}] Sets the width of the checkbox +for the questions. The argument \ameta{str} is a string whose width determines the width +of the checkboxes. The default is \cs{widestFmtdQNum\darg{00.}}. If the numbers are typeset +in bold, then \cs{widestFmtdQNum\darg{\string\textbf\darg{00.}}} is a little wider to +account for the bold font. +\item[\normalfont{\cs{htOfQ\darg{\ameta{length}}}}] Sets the height of the checkbox for the question. +The default is \cs{htOfQ\darg{13bp}}. +\end{description} + +\subsection{The answers} + +\begin{description} +\item[\normalfont{\cs{displayRandomizedAnswers}}:] As with the + questions, the answer are displayed in by a similar command. Again, + this command should be in a list environment, preferably the + \texttt{itemize}. The list label is suppressed by placing + \cs{item[]} before each answer. When the \texttt{showletters} + option is taken, the letter this answer corresponds to will be the + label. + +One of the design layouts in the demo files has the questions in a +two column format in the center with two columns of answers, half +the answers to the left of the questions, and the other half to the +right. The two commands +\begin{Verbatim} +\displayRandomizedAnswersLeftPanel +\displayRandomizedAnswersRightPanel +\end{Verbatim} +are used for that purpose.\footnote{{\TeX} doesn't know his left +from his right, so you can actually place the left panel listing on +the right. {\TeX} will not object!} As with +\cs{displayRandomizedAnswers}, each of these commands should be in +an \texttt{itemize} environment. + +\item[\normalfont{\cs{AnsAppearance}}:] Use this command to change the + appearance of the \app{Acrobat} checkboxes for the answers that appear in + the label margin. The command takes one argument, this argument + consists of one or more commands from the \textsf{eForms} package + that change the appearance of a field. For example, +\begin{Verbatim}[commandchars=!()] +\AnsAppearance{\BC{gray}} %!textsf( assumes xcolor pkg, or !cs(BC{.5 .5 .5})) +\end{Verbatim} +changes the boundary color to a gray color. See the \textsf{eforms} documentation. + +\item[\normalfont{\cs{ltrFmtA\darg{\ameta{\string\cmd\darg{\#1}}}}}] Formats the letters in +the list of answers when the option \opt{showletters} is active. In the argument, \texttt{\#1} +references the current letter to be typeset. For example, \verb~\ltrFmtA{\textbf{\textcolor{blue}{#1}}}~ +typesets the letters in bold and blue. + +\item[\normalfont{\cs{widestFmtdALtr\darg{\ameta{str}}}}] Sets the width of the checkbox +for the answers. The argument \ameta{str} is a string whose width determines the width +of the checkboxes. The default is \cs{widestFmtdALtr\darg{w}}. + +\item[\normalfont{\cs{htOfA\darg{\ameta{length}}}}] Sets the height of the checkbox for the answer. +The default is \cs{htOfA\darg{13bp}}. +\end{description} + +\subsection{The message field} + +\begin{description} +\item[\normalfont{\cs{placeMessageField[\ameta{opts}]\darg{\ameta{wd}}\darg{\ameta{ht}}}}:] + This \app{Acrobat} text field is used to write messages to the user. If + the user tries to choose an answer before selecting an answer, s/he + gets the message +\[ + \texttt{"You must choose a question to answer before you answer!"} +\] +For the interactive version of this game\footnote{Does that mean +there is also a non-interactive version of this game, sir? Yes, yes +there is. \dps}, there is a language option for \pkg{dps} to +change the messages from English, the default, to German, for +example. + +The parameters are \ameta{wd} (the width of the text field), +\ameta{ht} (the height of the text field and \ameta{opt} (the +optional argument for changing the appearance of the field, as +described in the documentation of the \pkg{eforms} package. +\end{description} +The message field is automatically removed when the document is +compiled in the \opt{forpaper} option of the \pkg{web} +package. + +\subsection{Auxiliary files} + +Developing a puzzle file creates a number of auxiliary files, in addition to +the usual ones of a typical {\LaTeX} file. The \pkg{dps} package creates a +large number of CUT files and a few SAV files. If you create a sideshow (page~\pageref{s:sdshw}), +additional PDF files are created as well. As a general rule, do not delete these files +until you are finished building your puzzle and you have verified that is working correctly. + +\section{Commands for controlling randomization} + +When randomizing is to be used (that is, the option \opt{!nonrandomized} is in effect, or +the \opt{nonrandomized} option is not specified), there are several commands to +control the initial seed of the random number generator. +\begin{Verbatim}[commandchars=!()] +\useRandomSeed{!ameta(seed)} %!textsf( eg, )\useRandomSeed{187968637} +\inputRandomSeed +\useLastSeed +\end{Verbatim} +All commands are placed in the preamble. Only one of the three should appear during any compile. +\begin{description} +\item[\normalfont\cs{useRandomSeed\darg{\ameta{seed}}}]\hskip-\labelsep\relax\space initializes the + random number generator to \ameta{seed}. +\item[\normalfont\cs{inputRandomSeed}]\hskip-\labelsep\relax\space inputs + the seed value saved by the \opt{savedata} option; as a result, the + same randomization sequence is obtained each time the file is + compiled.\footnote{This assumes that randomized items are neither added + or deleted.} In effect, this command freezes the randomization sequence + as long as the file \cs{jobname\_data.sav} has not been deleted. To + continue to use this random sequence after \cs{jobname\_data.sav} is + deleted, save the value of the initial seed first, as described in the + description of the \opt{savedata} option on + \hyperref[item:savedata]{page~\pageref*{item:savedata}}. + +\item[\normalfont\cs{useLastSeed}]\hskip-\labelsep\relax\space initializes + the random number generator with the last random number generated in + the \emph{previous} compile. In this way, you get a new randomization + each time you compile the file. +\end{description} +The last two commands assume \cs{jobname\_data.sav} exists; otherwise they take an initial seed based on +the current date and time. + +\section{Printing and clearing the puzzle} + +The \pkg{dps} package provides the following two commands, which produce push buttons: +\begin{Verbatim}[commandchars=!()] +\printDPS[!ameta(form-options)]{!ameta(wd)}{!ameta(ht)} %!textsf( prints the document) +\resetDPS[!ameta(form-options)]{!ameta(wd)}{!ameta(ht)} %!textsf( clears the document) +\end{Verbatim} +The \ameta{wd} and \ameta{ht} are the width and height of the push button; +the optional argument \ameta{form-options} are key-value pairs to change the +appearance of the buttons. Familiarity with the \pkg{eforms} package is +needed. + +The \pkg{dps} provides the command \cs{dpsResetHook} to add JavaScript lines to the +action of \cs{resetDPS}. The command takes one argument to pass the JavaScript lines +to \cs{resetDPS}; for example, \verb|\dpsResetHook{dpsHideFld("btnEmoji");}|\FmtMP{\cs{dpsHideFld}} appears +in several of the example file. This hides the \texttt{btnEmoji} image. + +\section{Methods of handling long questions} + +All the basic examples (those in the folder \texttt{examples/basic}) feature +\emph{short questions} that conveniently fit into the space provided.\footnote{With the one exception +of \texttt{stat\_match1-print.tex} in the \texttt{basic} folder.} More +complex questions require longer questions. The problem, then, is to +develop a method of posing long questions, without disturbing the puzzle design, +for an \textit{interactive puzzle}. + +In this section, we detail two methods of posing long questions, while saving +space on a one page puzzle document; these are (1) place the long questions +into an appearance of an push button (yes, you can do that); and (2) place +the long questions into a layer (optional content group, OCG). All {\LaTeX} +workflows are supported by method (1), while method~(2) requires the +\app{dvips\,->\,distiller} workflow. + +Both methods are designed for an interactive puzzle\FmtMP{interactive puzzles}, not a paper puzzle. + +\subsection{The \tops{\protect\opt{usebtnappr}}{usebtnappr} option}\label{s:usebtnappr} + +\textbf{Demo file.} The demonstration file for this subsection is \texttt{stat\_match1.tex}, +found in the \texttt{examples/advanced/icon-appr} folder. + +\newtopic\noindent This solution requires two files: (1) the puzzle file; and the (2) icon file. + +\subsubsection{The puzzle file} + +Within the puzzle file, the \opt{usebtnappr} option is specified. The +\cs{usepackage} command for \pkg{dps} below specifies the minimal options: +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\usepackage[% + !textbf(usebtnappr), + nonrandomized, + savedata +]{dps} +\end{Verbatim} +%More on the \opt{wrtcontent} option in the section titled \mlNameref{ss:workflow}. + +\paragraph*{In the preamble.} We place two environments; +\env{embedding}, to embed the icons; and \env{setContent}, to pose the +long questions. + +\subparagraph*{Embedding the icons.} The \opt{usebtnappr} brings in the +\FmtMP{\pkg{icon-appr} package}\pkg{icon-appr} package,\footnote{\url{https://ctan.org/pkg/icon-appr}} which defines the +\env{embedding} environment and the \cs{embedIcon} command. The \pkg{dps} +package defines \cs{dpsEmbedIcons}. This command embeds all the dynamically +created PDF graphics that comprise the long questions. \cs{dpsEmbedIcons} is +followed by other optional \cs{embedIcon} commands. +\begin{Verbatim}[commandchars=!()] +\begin{embedding} +\dpsEmbedIcons +!ameta(other-embeds) +\end{embedding} +\end{Verbatim} +Below is the example from the demo file. +\begin{Verbatim}[xleftmargin=\amtIndent] +\begin{embedding} +\dpsEmbedIcons +\embedIcon[name=Emoji,placement=btnEmoji]{MyEmoji.pdf} +\end{embedding} +\end{Verbatim} +The second line is the optional one; here, we explicitly embed, using the +syntax of \pkg{icon-appr}, an additional graphic for use by the puzzle. + +\subparagraph*{Special note for \app{xelatex} users.} The \env{embedding} +environment is placed in the preamble but the indirect references (a PDF +term) of the embedded graphics are not calculated until the first page is +shipped out (a {\LaTeX} term); therefore, the \emph{puzzle should be on the second +page} when the \emph{\pkg{textpos} package is used}\FmtMP{\pkg{textpos} pkg} to position the graphics. This +issue does not arise when using the \pkg{eso-pic} package. + +\subparagraph*{Posing long questions.} Following the \env{embedding} environment comes the usual content for +designing the puzzle: the \cs{DeclarePuzzle} data structure, followed by the +\env{Composing} environment. It is within the \env{cQ} environment of the +\env{Composing} environment that there is a change in content. + +The\FmtMP{posing long question} \opt{usebtnappr} option +defines the \env{setContent} environment, which is placed in the \env{cQ} +environment. +\begin{Verbatim}[commandchars=!()] +\begin{cQ}{!ameta(name)} + !ameta(question-prompt) +\begin{setContent}{!ameta(name)} + !ameta(long-question) +\end{setContent} +\end{cQ} +\end{Verbatim} +The \ameta{name} argument of \env{setContent} is same as the argument of the +enclosing \env{cQ} environment. \env{setContent} is a verbatim write +environment; \cs{begin\darg{setContent}} can follow the end of the +\emph{question-prompt} (one or more words that suggest what the question is +about), but the \cs{end\darg{setContent}} must be in the left-most margin, as +shown above. We illustrate first with an example taken from the demo file: +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\begin{Composing} +\begin{cQ}{R} +Branches of Statistics!textbf(\begin{setContent}{R}) +The two branches of statistics are descriptive and +\underbar{\hspace{.5in}}. +!textbf(\end{setContent}) +\end{cQ} +\begin{cA}[r]{R} +inferential +\end{cA} +... +\end{Composing} +\end{Verbatim} +A long question is not required, in the demo file most have long questions and +some do not. + +The \env{setContent} environment writes its content verbatim to a CUT file +(named \cs{jobname-sc(\ameta{num}).cut}). For example, the CUT file for the +first question of the demo file reads, +\begin{Verbatim}[xleftmargin=\amtIndent] +\textbf{Problem 1}\newline +The two branches of statistics +are descriptive and \underbar{\hspace{.5in}}. +\end{Verbatim} +The first line seen above can be modified using the following two commands. +\begin{Verbatim} +\newcommand{\quesNumTxt}[1]{\protect\textbf{Problem #1}} +\newcommand{\quesNumTxTPost}{\protect\newline} +\end{Verbatim} +These may be redefined. + +\paragraph*{On the puzzle page.} Aside from the layout of the puzzle, questions, +and answers commands, above all these, place the following commands: +\begin{Verbatim}[commandchars=!()] +\placeQuesIcon{!ameta(placement-cmds)} +\placeOtherIcon{!ameta(placement-cmds)} +\end{Verbatim} +The nature of the \ameta{placement-cmds} depends on the ``placement'' package used. The demo files +use either the \FmtMP{\pkg{eso-pic}, \pkg{textpos} packages}\pkg{eso-pic} or +\pkg{textpos} package. The \ameta{placement-cmds} place the text field +\cs{dpsQuesIcon\darg{\#1}\darg{\ameta{wd}\darg{\ameta{ht}}}}. +The following is taken from the demo file, it uses the \pkg{eso-pic} package. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={@~^}] +\placeQuesIcon{\AddToShipoutPictureFG*{\AtTextCenter{\put(-72,0) + {@textbf~\dpsQuesIcon{#1}{2.25in}{9\baselineskip}^}}}} +\end{Verbatim} +If other icons were embedded in the \env{embedding} environment, those icons can be placed +using the \cs{placeOtherIcon} command. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={@~^}] +\placeOtherIcon{\AddToShipoutPictureFG*{\AtTextCenter{\put(-72,0) + {@textbf~\dpsOtherIcon[\I{\csOf{Emoji}}]{btnEmoji}{2.25in}{9\baselineskip}^}}}} +\end{Verbatim} + +\subsubsection{The icons file}\label{ss:iconfile} + +The \opt{usebtnappr} option requires the use of a second file, named +\texttt{icons.tex}.\footnote{The name of the file is hard-wired into the +package and cannot be changed at this time.} The \texttt{icons.tex} file in +the \texttt{examples/advanced/icon-appr}. The icons file (\texttt{icons.tex}) +is a very short file and is placed in the same folder as the puzzle file. +\begin{Verbatim}[commandchars={*@^}] +\documentclass{article} +\usepackage[!useacrobat]{icon-doc} +\margins{3pt}{3pt}{3pt}{3pt} %*textsf@ left,right,top,bottom (web command)^ +\screensize{9\baselineskip}{2.25in} %*textsf@ height,width (web command)^ +\begin{document} +\small +\createRequiredIcons{12}{stat_match1} +\end{document} +\end{Verbatim} +The icons file is placed in the came folder as the puzzle file. The \pkg{dps} +distribution has the \FmtMP{\pkg{icon-doc} package}\pkg{icon-doc} package, a +short package designed for the icons file. The package has two options +\opt{useacrobat} and \opt{!useacrobat}, the default is \opt{!useacrobat}. +Document authors who use \app{pdflatex}, \app{lualatex}, or +\app{dvips\,->\,distiller} need not bother with this option; the option is +designed for \app{xelatex} users. + +Use the \cs{margins} command to adjust the boundary margins of icons file. +Use the \cs{screensize} to adjust the height of the icons file and the width +of the icons file. The dimensions shown above are the ones used by the demo +file. + +The \cs{createRequiredIcons\darg{\ameta{num-ques}}\darg{\ameta{puzzle-file}}} +command has two arguments: \ameta{num-ques} is the number of questions in the +puzzle file; \ameta{puzzle-file} is the base name of the puzzle file. +The command has two behaviors: +\begin{enumerate} + \item \textbf{For \app{xelatex} authors that do not have \app{Acrobat}.} + When the icon file is compiled, the result is \ameta{num-ques} PDFs, + each PDF contains a \emph{single} long question. Since the author + does not have \app{Acrobat}, the icons file is compiled with the + \opt{!useacrobat} option. This case requires the + \FmtMP{\pkg{shellesc} pkg}\pkg{shellesc} package and that your + {\LaTeX} editor be setup to use the \texttt{shell-escape} switch of your editor. + Refer to Figure~\ref{fig:shesc} to see how to do this for the \app{WinEdt} editor. + Other editors/\TeX{} systems may support the \texttt{shell-escape} switch. +\begin{figure}[htb]\centering + \includegraphics[width=.67\linewidth]{graphics/shell-escape} + \caption{Setting \texttt{shell-escape} on \app{WinEdt}}\label{fig:shesc} +\end{figure} + \item \textbf{For all other cases of workflow.} When the icons file is + compiled, the result is a \emph{single} PDF (\texttt{icons.pdf}) with a page + for each long question in the puzzle file, in an order determined by + the randomization option (\opt{!nonrandomized} or + \opt{nonrandomized}). + + For a \app{xelatex} author who has \app{Acrobat}, the + \opt{useacrobat} needs to be used. +\end{enumerate} + +\paragraph*{Additional comments for \app{xelatex} authors.}\label{para:addCmts} In the case the author +does not own \app{Acrobat}, when the icons file is compiled, each of the +files \cs{jobname-sc(\ameta{num}).cut} is \emph{wrapped in a document +template}, compiled, and saved as \texttt{icon-\ameta{num}.pdf}. +The document wrapper is determined by the contents of the +\FmtMP{\env{icondoc} env}\env{icondoc} environment. The default declaration +of \env{icon-body} is, +\begin{Verbatim}[commandchars=!()] +\begin{icondoc} +\documentclass{article} +\usepackage{web} +\margins{3pt}{3pt}{3pt}{3pt} +\screensize{9\baselineskip}{2.25in} +\begin{document} +\small +\dpsInputContent %!textsf( required, defined in icon-doc) +\end{document} +\end{icondoc} +\end{Verbatim} +Notice that this markup is similar to the source file for \texttt{icons.tex}; +they differ in two respects, however: (1) the \pkg{icon-doc} package is not +used; and (2) in the body, we use \cs{dpsInputContent} rather than +\cs{createRequiredIcons}. If you use multiple workflows, the layout of the +icons file and the declarations of the \env{icondoc} environment should be +the same. Changes to the \env{icondoc} environment are made in the icons file. For example, +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars={*@^}] +%*textsf@ icons.tex^ +%*textsf@ modify a design parameters^ +\documentclass{article} +\usepackage[!useacrobat]{icon-doc} +\margins{4pt}{4pt}{4pt}{4pt} %*textsf@ left,right,top,bottom (web command)^ +\screensize{10\baselineskip}{3in} %*textsf@ height,width (web command)^ +%*textsf@ change *env@icondoc^ to reflect changes above^ +*textbf@\begin{icondoc}^ +\documentclass{article} +\usepackage{web} +\margins{4pt}{4pt}{4pt}{4pt} +\screensize{10\baselineskip}{3in} +\begin{document} +\small +\dpsInputContent %*textsf@ required, defined in icon-doc^ +\end{document} +*textbf@\end{icondoc}^ +\begin{document} +\small +\createRequiredIcons{12}{stat_match1} +\end{document} +\end{Verbatim} +\textbf{Why is \app{xelatex} so special (such a problem)?} The basic problem when dealing +with \app{xelatex} is that it does not obey the \key{page} key of \cs{includegrapics}. When a graphic is embedded +in a document we say, +\begin{quote} + \cs{embedIcon[name=Q\string\n,hyopts=\darg{page=\string\n}]\darg{icons.pdf}} +\end{quote} +where, \cs{n} is question number; in this case, \cs{n} is also the page +number where the question is located in \texttt{icons.pdf}. Since, the +\key{key} is not obeyed, we cannot bundle all the questions in a single PDF +and pull out the page we want; no, the questions must be their own PDF, the +embedding command is then, +\begin{quote} + \cs{embedIcon[name=Q\string\n]\darg{icons-\string\n.pdf}} +\end{quote} +where \cs{n} is the question number. + +\newtopic Hey, we're almost done with this option! + +\subsubsection{The workflow to build the puzzle file}\label{ss:workflow} + +Let's summarize the workflow to build a puzzle file that uses icon appearances +to display the long questions. We assume you have jumped through all the hoops of the previous section, +your puzzle file and icons file are ready to go. +\begin{enumerate} + \item Compile the puzzle file, using the compiler of your choice. If + you require a randomized listing of the questions and answers, + either compile with \opt{!nonrandomized}, or the \opt{nonrandomize} + option commented out or deleted. If you are randomizing, compile + with the command \cs{inputRandomSeed} in the preamble to input that + same initial seed back in when your later compile the puzzle file + in step~3.\footnote{Or, you can open the SAV file and copy and + paste the initial seed into the argument of \cs{useRandomSeed}.} + \item Compile the icons file, using your favorite compiler. If you are + a \app{xelatex} user, the option \opt{useacrobat} and + \opt{!useacrobat} as appropriate. (Refer to \textbf{\mlnameref{para:addCmts}} + on page~\pageref{para:addCmts} for more details.) + \item Return to the puzzle file. Compile the puzzle file again to + obtain the final version. + + \item Bring your PDF into \app{Adobe Reader DC} (or \app{Adobe Acrobat DC} if you + have it) and save the file. After saving, test the puzzle to be sure + the icons are displayed with the long questions. If it does not work, + repeat steps~1--3 more carefully. +\end{enumerate} +To familiarize yourself to the procedure, build the demo file +\texttt{stat\_match1.tex} using your favorite PDF creator. Try it with +several PDF creators, just for fun. The process is straight forward once +everything is properly set up. + +\subsection{The \tops{\protect\opt{uselayers}}{uselayers} option}\label{s:uselayers} + +\textbf{Demo files.} There are several example files in the +\texttt{examples/advanced/ocgs} folder, but in this discussion, we'll +reference, once again, \texttt{stat\_match1} found in the \texttt{ex1} +folder. There are two versions of this file \texttt{stat\_match1-ep.tex} and +\texttt{stat\_match1-tb.tex}. The latter uses the \pkg{textpos} package, the +latter uses the \pkg{eso-pic} package. For variety, we'll reference the +\pkg{textpos} version. + +\newtopic\noindent +The \opt{uselayers} option is actually a simpler approach (no icon file +needed), but there has more restrictions on the workflow. This option +requires \FmtMP{\pkg{aeb\_pro} pkg} the \pkg{aeb\_pro} package (with +correctly installed JS files \texttt{aeb.js} and \texttt{aeb\_pro.js}) and +requires a \FmtMP{\app{Acrobat} required}\app{dvips->distiller} PDF creator workflow. + +\subsubsection{The puzzle file} + +A minimal specification for the \pkg{aeb\_pro} and \pkg{dps} packages is +listed below: +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\usepackage[% + web={extended,tight}, + eforms, + !textbf(uselayers) +]{aeb_pro} +\usepackage[!textbf(uselayers), + nonrandomized, + savedata +]{dps} +\end{Verbatim} + +\paragraph*{Posing long questions.} The \cs{DeclarePuzzle} is as described in +\hyperref[s:DP]{Section~\ref*{s:DP}}. As in the case of \hyperref[s:usebtnappr]{Section~\ref*{s:usebtnappr}}, +the \env{setContent} environment is used to pose long questions. +\begin{Verbatim}[commandchars=!()] +\begin{cQ}{!ameta(name)} + !ameta(question-prompt) +\begin{setContent}{!ameta(name)} + !ameta(long-question) +\end{setContent} +\end{cQ} +\end{Verbatim} +The definition of \env{setContent} differs from that of \env{setContent} for +the \opt{usebtnappr} option. A long question is not required. + +The \env{setContent} environment writes its content verbatim to a CUT file +(named \cs{jobname-sc(\ameta{name}-\ameta{num}).cut}). For example, the CUT file for the +first question of the demo file reads, +\begin{Verbatim}[xleftmargin=\amtIndent] +\textbf{Problem 1}\newline +The two branches of statistics +are descriptive and \underbar{\hspace{.5in}}. +\end{Verbatim} +The first line, which is not part of the \env{setContent} content, seen above +can be modified using the following two commands. +\begin{Verbatim} +\newcommand{\quesNumTxt}[1]{\protect\textbf{Problem #1}} +\newcommand{\quesNumTxTPost}{\protect\newline} +\end{Verbatim} +These may be redefined. + +\begin{comment} +\fmtOCGQues{% + \parbox[t][9\baselineskip][t]{2.25in}{\kern0pt\small\hfuzz11pt + \psshadowbox[framesep=0pt]{\fcolorbox{red}{cornsilk}{% + \parbox{\linewidth}{\dpsQuesLayer{#1}\vskip3pt}}}}% +} +% These declaration go on the page where they are to appear +\placeQuesLayer{% + \begin{textblock*}{2.25in}[0,0](2.5in+.725in,3in) %(.33\paperwidth,.42\paperheight)\hfuzz11pt + \insertQuesLayer{#1} + \end{textblock*}% +} + +\placeOtherLayer{% + \begin{textblock*}{2.25in}[0,0](2.5in+.725in,3in)\centering + \xBld{owclogo}\parbox{2.25in}{\includegraphics[width=2.25in]{owc_self}}\eBld + \end{textblock*}% +} +\end{comment} + +\paragraph*{In the body of the puzzle page.} The following three commands are placed +on the same page as the puzzle is to appear. They precede the layout of the puzzle, questions, +and answers. +\begin{Verbatim}[commandchars=!()] +\fmtOCGQues{!ameta(formatting-comm)} +\placeQuesLayer{!ameta(placement-cmds)} +\placeOtherLayer{!ameta(placement-cmds)} +\end{Verbatim} +The argument of \FmtMP{\cs{fmtOCGQues}}\cs{fmtOCGQues} is a convenient way of designing how your long question +appears on the page. Within the argument, use \cs{dpsQuesLayer{\#1}} to symbolically reference +the question. For example, from the demo file, +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\fmtOCGQues{% + \parbox[t][9\baselineskip][t]{2.25in}{\kern0pt\small\hfuzz11pt + \psshadowbox[framesep=0pt]{\fcolorbox{red}{cornsilk}{% + \parbox{\linewidth}{!textbf(\dpsQuesLayer{#1})\vskip3pt}}}} +} +\end{Verbatim} +Here, we've used \cs{psshadowbox} from \pkg{pstricks-add}, + +The nature of the \ameta{placement-cmds} depends on the ``placement'' package used. The demo files +use either the \FmtMP{\pkg{eso-pic}, \pkg{textpos} packages}\pkg{eso-pic} or +\pkg{textpos} package. The \ameta{placement-cmds} argument places the question +\cs{insertQuesLayer\darg{\#1}}. + +For the command \FmtMP{\cs{placeQuesLayer}}\cs{placeQuesLayer} places the question layer, +symbolically represented by \cs{insertQuesLayer\darg{\#1}}. For example, from the demo file, +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\placeQuesLayer{% + \begin{textblock*}{2.25in}[0,0](2.5in+.725in,3in) + !textbf(\insertQuesLayer{#1}) + \end{textblock*}% +} +\end{Verbatim} +\cs{insertQuesLayer} sets the layer and inputs the formatted content. + +Use \FmtMP{\hfuzz4pt\cs{placeOtherLayer}}\cs{placeOtherLayer} to place other +non-question content in a layer. For example, from the demo file, +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()] +\placeOtherLayer{% + \begin{textblock*}{2.25in}[0,0](2.5in+.725in,3in)\centering + \xBld{owclogo}\parbox{2.25in} + {\includegraphics[width=2.25in]{owc_self}}\eBld + \end{textblock*}% +} +\end{Verbatim} +Here, you must use the \pkg{aeb\_pro} commands to create a named layer, using +the \cs{xBld}/\allowbreak\cs{eBld} command pair. The argument of \cs{xBld} is the name +of the layer. Within the \cs{xBld}/\cs{eBld} pair, we create our content of a +graphic. + +\subsection{Developing an end of game event} + +There are commands and JavaScript hooks to enable a knowledgable author to +create a special end-of-game event. For example, the graphic placed by +\cs{placeOtherIcon} or \cs{placeOtherLayer}, becomes visible when the player +finishes the puzzle. All the demo files in the \texttt{advanced} folder have +end of game events. The \pkg{dps} provides the command \cs{dpsFinishedEvent} +to add JavaScript lines to the action to the end of game event. The command +takes one argument to pass the JavaScript lines to the end of game event; for +example, \verb|\dpsFinishedEvent{dpsShowFld("btnEmoji");}|\allowbreak +\FmtMP{\leavevmode\llap{\cs{dpsFinishedEvent}}} appears in several of the +example file. This shows the \texttt{btnEmoji} image when the player has +finished the puzzle. + +\section{Creating a sideshow}\label{s:sdshw} + +Some of the advanced examples use a sideshow; as the player progresses through +the puzzle, with each success, a new piece of a graphic is revealed. A partially worked puzzle +is shown in \hyperref[fig:sideshow]{Figure~\ref*{fig:sideshow}}. + +\begin{figure}[htb]\centering\fboxsep0pt +\fbox{\includegraphics[width=.67\linewidth]{graphics/sideshow}} +\caption{Puzzle with sideshow, shown on left}\label{fig:sideshow} +\end{figure} + +There are two commands, placed in the preamble, that control the behavior of +the sideshow. +\begin{Verbatim} +\randomizePicMappings +\sortPicMappings +\end{Verbatim} +The order the sideshow pictures appears can be in their natural order, or in +a randomized order. To randomize the order, insert \cs{randomizePicMappings} +in the preamble; otherwise, the pictures appear in their natural order. + +Second command, \cs{sortPicMappings} implies \cs{randomizePicMappings}, but +with a twist. The pictures are placed in random positions as they appear; at +the end of the puzzle, a bubble sort is applied, and the pictures are sorted +to their natural order. Cool. + +In all cases, pressing the \textsf{Clear} button creates a new randomization +of the sideshow. + + +\paragraph*{Tiled graphics.}\label{para:tiledgraphics} A sideshow appears in pieces, called \emph{tiles}, that appear +one at a time as the puzzle is solved, see +\hyperref[fig:sideshow]{Figure~\ref*{fig:sideshow}}. The graphic to be used +must have been broken down into a series of \emph{tiled sub-graphics}. These +tiles must be created in a certain way and labeled in a specific manner. Use +the \FmtMP{\pkg{tile-graphic} pkg}\pkg{tile-graphic} package to tile the +graphic into either individual PDF tiled sub-graphics or as a single package +of tiled graphics.\footnote{\url{https://ctan.org/pkg/tile-graphic}} + +\subparagraph*{The base name of the graphic.}\label{subpara:basename} The \pkg{tile-graphic} has a naming convention +that this package respects: +\begin{itemize} + \item When the tiled graphics are individual files, they are named, for + example, \texttt{mypic\_01}, \texttt{mypic\_02}, \texttt{mypic\_03}, + \dots. The base name of this example is \texttt{mypic}. The graphical + file format of the tiles is any format the PDF creator supports for + graphical inclusion. It is usually most convenient for the tiled + files to be PDF files. + \item When the tiled graphics are packaged,\footnote{\app{xelatex} does not support packaged files, + the tiles should be individual PDFs, as describe previously.} the \pkg{tile-graphic} + package names the package file, for example, + \texttt{mypic\_package.pdf}. When packaged, the graphical file format + for the tiles are always PDFs. The base name of this example is \texttt{mypic}. +\end{itemize} + + +\newtopic +Additional details of how to create a sideshow are dependent on whether the +option \opt{usebtnappr} or \opt{uselayers} is taken. + +\subsection{Sideshow with the \tops{\protect\opt{usebtnappr}}{usebtnappr} option} + +\textbf{Demo file.} The demo file for this feature is \texttt{first\_date.tex} found +in the folder \texttt{examples/advanced/usebtnappr/sideshow}. + +\newtopic\noindent First we embed the pictures of the sideshow in the \env{embedding} +environment. +\begin{Verbatim}[commandchars=!()] +\begin{embedding} +\dpsEmbedIcons +!ameta(other-embedding commands) +!textbf(\sideshowPackaged!quad)%!sffamily( optional) +!bfseries\dpsEmbedSideShow[!ameta(ext)]{!ameta(n-pics)}{!ameta(path)} +\end{embedding} +\end{Verbatim} +There are two ways to present the sideshow pictures, as described in the +paragraph \textbf{\nameref{para:tiledgraphics}} above, to the +\cs{dpsEmbedSideShow} command: (1) as individual tiled graphics; or (2) as a +packaged graphic, the pages of which are the tiled graphics. The form of how +the picture is presented is signaled to the \cs{dpsEmbedSideShow} command by +the command \cs{sideshowPackage}, as indicated above. The first argument is +\ameta{ext}, the file extension of the graphic, this usually not needed; when +there is no \ameta{ext} specified, the extension is assumed to be +\texttt{pdf}. The second argument is \ameta{n-pics}, the number of tile +sub-graphics in the sideshow. The third argument, \ameta{path}, is the path +to the sideshow graphic. At the end of the \ameta{path} is the base name of +the graphic, as described in \textbf{\nameref{subpara:basename}} on +page~\pageref*{subpara:basename}; for example, \texttt{graphics/mypic} +indicates the tile files are in the \texttt{graphics} sub-folder, with base +name of \texttt{mypic}. + +\newtopic After embedding the sideshow graphics, insert them into the puzzle board +using, +\begin{Verbatim}[commandchars=!()] +\insertSideshow{!ameta(nRows)}{!ameta(nCols)}{!ameta(width)}{!ameta(height)} +\end{Verbatim} +where, \ameta{nRows} is the number of rows of the tiled graphic; +\ameta{nCols} is the number of columns of the tiled graphic; \ameta{width} is +the width of the tile; and \ameta{height} is the height of the tile. These +latter two are adjusted so the tile fits into the space allotted and the +aspect ratio is preserved. + +\newtopic\noindent +\textbf{\textcolor{red}{Remark.}} When compiling a puzzle with the +\opt{usebtnappr} option, the puzzle file compiles in two ``modes,'' depending +on the state of the switch \cs{ifwrtContent}. Each time the document is +compiled, the package looks for the file \texttt{icons-pglst.sav}, if it +exists, the switch \cs{ifwrtContent} is set false; otherwise, it is set to +true. The file \texttt{icons-pglst.sav} is created by \texttt{icons.tex}, the +existence of \texttt{icons-pglst.sav} means \texttt{icons.tex} has been +built. Once the puzzle file knows the \texttt{icons.tex} is built, the +switch \cs{ifwrtContent} is set to false, and its behavior is changed +slightly. If something goes wrong, delete \texttt{icons-pglst.sav}, and rebuild +the puzzle file first, the icons file next, then finally the puzzle file again. + +\subsection{Sideshow with the \tops{\protect\opt{uselayers}}{uselayers} option} + +\textbf{Demo file.} The two TEX files in the \texttt{examples/advanced/uselayers/sideshow} folder. + +\newtopic\noindent +When the \opt{uselayers} option is specified, only EPS files are supported. +\begin{Verbatim}[commandchars=!()] +\insertSideshow{!ameta(nRows)}{!ameta(nCols)}[!ameta(hy-opts)]{!ameta(path)} +\end{Verbatim} + +% layers +%\insertSideshow{3}{2}[hiresbb,width=.5\linewidth]{flowers1/DSC_0453} + +\section{Some small degree of security} + +If a puzzle is create for a class of students to take for credit; then some +security is appropriate. Typically, you post the puzzle with a print button +(see \cs{printDPS} above. After the student completes the puzzle, he/she +prints the results and hands it in for some credit. The \pkg{dps} package also +provides \cs{clearOnCloseOrSave}: +\begin{Verbatim} +\clearOnCloseOrSave +\end{Verbatim} +Place this command in the preamble. Now, when the puzzle is built, a student +tries to close or save the puzzle, the puzzle is cleared before closing or +saving. The only record is the printed version.\footnote{Perhaps this is a +mere nuisance, the student can make many copies of the printed puzzle, and +hand it around to others in the class. Nothing is foolproof.} + +%\section{Advanced hooks} +%There are several built-in hooks that can be exploited to author special effects. + +% The two commands \afterQhookA and \OnFocusQhookAA are hooks onto +% the \dpsQ command of the dps package. This allows us to post process +% the user's choice of a questions, and allows us to execute JS on focus. +% We use these two to call to JS function to support these additional + +% \afterQhookA +% \OnFocusQhookAA + +% afterCorrectChoiceHook() +% dpsFinishedHook() + +\section{Let's have some Fun} + +In order to make answering the questions ``fun,'' and in addition to +the puzzle (or message), I implemented a point system. Each time the +user checks an incorrect answer, that is recorded as a miss. After +completion of the game, the JavaScript determines if the user has +passed the test. To make it more interesting, a penalty point system +is also used: If the user incorrectly answer the same questions +multiple times (guessing!), penalty points are given. + +\newtopic\noindent +The document author can set the various parameters of this aspect of the game. +\begin{description} +\item[\normalfont{\cs{threshold\darg{\ameta{n}}}}:] The number, \ameta{n}, of + times a person is allowed to miss the same question before being + ``awarded'' penalty points. The command \cs{threshold} with its one + argument defines the command \cs{dsthreshold} which expands to the + argument, \texttt{n}, of \cs{threshold}. Set \cs{threshold} in the + preamble, and use \cs{dsthreshold} as part of the instructions or + description of the game. The default: \verb!\threshold{3}!. + +\item[\normalfont{\cs{penaltypoints\darg{\ameta{n}}}}:] The number, \ameta{n}, +of penalty points to be added into the final score. Penalty points +are ``awarded'' for missing the same question more than the number +specified by the argument of \cs{threshold}. The command +\cs{penaltypoints} with its one argument defines the command +\cs{dspenaltypoints} which expands to the argument, \texttt{n}, of +\cs{penaltypoints}. Set \cs{penaltypoints} in the preamble, and use +\cs{dspenaltypoints} as part of the instructions or description of +the game. Default: \verb!\penaltypoints{3}!. + +\item[\normalfont{\cs{passing\darg{\ameta{n}}}}:] The maximum number, +\ameta{n}, of questions the user needs to miss and still pass the +test. Passing or not does not depend on the number of penalty +points. The command \cs{passing} with its one argument defines the +command \cs{dspassing} which expands to the argument, \ameta{n}, of +\cs{passing}. Set \cs{passing} in the preamble, and use +\cs{dspassing} as part of the instructions or description of the +game. The default is \verb!\passing{4}!. + +The number of incorrect answers and the total penalty points are +combined. Based on the combined score, a final evaluation of the +user's knowledge on the subject is displayed. +\end{description} + +\section{Checking for validity} + +When creating the game, human error can sneak in. The most critical +part is the \cs{Declare\-Puzzle} command and getting the names of your +fields set up the way you want. Letters with the same field name +(the second parameter of the pair) will only need one question, they +will all ``light up'' when the question is answered. + +As explained earlier, after you've decided on your puzzle and the +field names, you can then create your \texttt{Composing} environment +using the \cs{writeComposingEnv} helper command. Review the +discussion in \Nameref{composing}. + +To help you lay out your design, use the \texttt{viewmode} option, +possibly along with the \texttt{showletter} option. This gives you a +nice preview and you can see where everything is located. You may +have to adjust the parameter for \cs{insertPuzzle} to fit the puzzle +into the allotted space. If enclosing puzzle, questions and answer +in frames, there may have to be some adjustment of the depth of the +controlling \texttt{minipage} environments, and so on, etc., etc., +etc., and, of course, etc. + +Assuming you have successfully posed questions and answers, and +designed a layout for your puzzle, the questions, and the answers, you are +ready to test it. Using the \texttt{nonrandomized} option is nice +for checking your puzzle; the questions and answers are listed in +the same order. + +If you have customized the text using the \texttt{lang=custom} +option, you need to check that your text displays correctly; this is +especially important if your new text contains accented characters, +such as our old friend \"{u}. To test your customized string, open +your puzzle document in \app{Acrobat} (\app{Reader} will not do here) and +execute these JavaScript lines in the console:\footnote{To execute +from the console, open the console window by pressing +\texttt{Ctrl+J}, paste in the code, highlight all the lines and +press the \texttt{Enter} key on the keyboard, or \texttt{Ctrl+Enter} +on the keypad.} +\begin{verbatim} +this.resetForm() +nMissed = 0; +nPenaltyPoints = 0; +nPassing = 4; +checkForFinished(); +\end{verbatim} +By changing the variables \texttt{nMissed}, \texttt{nPenaltyPoints} +and \texttt{nPassing}, and executing, you get the different messages +appearing in the message text field. + +\section{Using the \textsf{web} Package} + +The web package has a many features that can be utilized as a part +of your overall puzzle design. + +The package has a powerful template management system for inserting +background graphics into a document, and a system for painting the +background a color other than the default white. + +Use the \cs{margins} and \cs{screensize} commands to set the +dimensions of your puzzle game page: +\begin{Verbatim}[commandchars=!()] +\margins{!ameta(left)}{!ameta(right)}{!ameta(top)}{!ameta(bottom)} +\screensize{!ameta(height)}{!ameta(width)} +\end{Verbatim} +Enter the title and author's name, as well as other metadata: +\begin{Verbatim}[commandchars=!()] +\title{!ameta(doc-title)} +\author{!ameta(doc-author)} +\end{Verbatim} +See the documentation, \texttt{aeb\_man.pdf}, of the \href{http://www.ctan.org/pkg/acrotex}{\textsf{AeB} distribution} +for details. + +\section{Thanks} + +My thanks to J\"{u}rgen Gilg, of u-umlaut fame, for his help and +kind suggestions during the development of this game. + +That's all for now. Hope you enjoy \textsl{Das Puzzle Spiel} and +find it a useful learning tool. + +\newtopic\noindent +Now, I simply must get back to my retirement. \dps + +\newpage + +\section{Appendix}\label{appendix} + +The following is a subset of the PDFDocEncoding character set for PDF, these are +useful for creating your custom localization file \texttt{dps\_str\_cust.def}, as discussed +in \mlNameref{packopts}. + +\subsection{German Umlaut (dieresis)} +Here a little tabular how to substitute the German Umlaut +(dieresis) in PD1.\\[6pt] +% +\begin{tabular}{cl|cl|cl} +\"{A}&\verb!\string\304!&\"{O}&\verb!\string\326!&\"{U}&\verb!\string\334!\\ +\"{a}&\verb!\string\344!&\"{o}&\verb!\string\366!&\"{u}&\verb!\string\374!\\ +{\ss}&\verb!\string\337! +\end{tabular} + +\subsection{Accents} +Here a little tabular how to substitute accents in PD1.\\[6pt] +% +\begin{tabular}{cl|cl|cl} +\`{A}&\verb!\string\300!&\`{E}&\verb!\string\310!&\`{I}&\verb!\string\314!\\ +\`{a}&\verb!\string\340!&\`{e}&\verb!\string\350!&\`{\i}&\verb!\string\354!\\ +\'{A}&\verb!\string\301!&\'{E}&\verb!\string\311!&\'{I}&\verb!\string\315!\\ +\'{a}&\verb!\string\341!&\'{e}&\verb!\string\351!&\'{\i}&\verb!\string\355!\\ +\^{A}&\verb!\string\302!&\^{E}&\verb!\string\312!&\^{I}&\verb!\string\316!\\ +\^{a}&\verb!\string\342!&\^{e}&\verb!\string\352!&\^{\i}&\verb!\string\356!\\ +\`{O}&\verb!\string\322!&\`{U}&\verb!\string\331!&\"e&\verb!\string\353!\\ +\`{o}&\verb!\string\362!&\`{u}&\verb!\string\371!&\c{C}&\verb!\string\307!\\ +\'{O}&\verb!\string\323!&\'{U}&\verb!\string\332!&\c{c}&\verb!\string\347!\\ +\'{o}&\verb!\string\363!&\'{u}&\verb!\string\372!\\ +\^{O}&\verb!\string\324!&\^{U}&\verb!\string\333!\\ +\^{o}&\verb!\string\364!&\^{u}&\verb!\string\373! +\end{tabular} +\end{document} |