From f2461d37fbf50a9a0469fd575362ab099d8e0390 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Tue, 30 Jun 2020 10:08:04 +0900
Subject: acromemory update

---
 texmf-dist/doc/latex/acromemory/acromemory-man.tex | 483 +++++++++++++++++++++
 1 file changed, 483 insertions(+)
 create mode 100644 texmf-dist/doc/latex/acromemory/acromemory-man.tex

(limited to 'texmf-dist/doc/latex/acromemory/acromemory-man.tex')

diff --git a/texmf-dist/doc/latex/acromemory/acromemory-man.tex b/texmf-dist/doc/latex/acromemory/acromemory-man.tex
new file mode 100644
index 00000000..86262a72
--- /dev/null
+++ b/texmf-dist/doc/latex/acromemory/acromemory-man.tex
@@ -0,0 +1,483 @@
+\documentclass{article}
+\usepackage[fleqn]{amsmath}
+\usepackage[
+    web={centertitlepage,designv,forcolorpaper,latextoc,pro},
+    eforms,
+%    linktoattachments,
+    aebxmp
+]{aeb_pro}
+\usepackage{pifont}
+\usepackage{graphicx}
+%\usepackage{aeb_mlink}
+%\usepackage{myriadpro}
+%\usepackage[usecmtt]{myriadpro}
+\usepackage[altbullet]{lucidbry}
+\usepackage{acroman}
+\usepackage[active]{srcltx}
+
+\edef\amtIndent{\the\parindent}
+
+%\usepackage{myriadpro}
+%\usepackage{acaslonpro}
+%\usepackage{ajensonpro}
+%\usepackage{minionpro}
+%\usepackage{newsgothicstd}
+%\usepackage{lucidbry}
+
+\DeclareDocInfo
+{
+    university={\AcroTeX.Net},
+    title={The \textsf{acromemory} Package},
+    author={D. P. Story},
+    email={dpstory@acrotex.net},
+    subject=Documentation for the acromemory package,
+    talksite={\url{www.acrotex.net}},
+    version={2.0, 2020/06/23},
+    Keywords={LaTeX, form field, memory puzzles, AcroTeX},
+    copyrightStatus=True,
+    copyrightNotice={Copyright (C) 2006--\the\year, D. P. Story},
+    copyrightInfoURL={http://www.acrotex.net}
+}
+
+\def\nhfootnote#1{\begin{NoHyper}\footnote{#1}\end{NoHyper}}
+
+\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
+   \kern-.6em \hbox{$\mathcal S$}}$}
+
+
+\chngDocObjectTo{\newDO}{doc}
+\begin{docassembly}
+var titleOfManual="The acromemory Package";
+var manualfilename="Manual_BG_Print_acromemory.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
+%\advance\linewidth\oddsidemargin
+%\setlength{\oddsidemargin}{0pt}
+\maketitle
+
+%\endgroup
+
+\changelinkcolorto{black}
+
+\tableofcontents
+
+\changelinkcolorto{webgreen}
+
+
+\section{Introduction}
+
+\pkg{AcroMemory} (\pkg{acromemory}) is a memory game in which you find the
+matching tiles. There are two versions---available as options of
+this package---for your enjoyment, \texttt{acromemory1} and
+\texttt{acromemory2} (the default). Only one option is allowed to be taken for any document,
+only one memory puzzle per document is supported. (In theory, you can have multiple instances of the same
+memory puzzle, but I don't really see a need for that.)
+\begin{itemize}
+   \item \texttt{acromemory1}: Here you have a single game board, a
+        rectangular region divided by rows and columns. The total number
+        of tiles \emph{must} be even, each tile \emph{must} have a matching twin.
+        The game begins with all the tiles hidden. The user clicks a
+        tile, then another. If the tiles do not match, they become
+        hidden again (you did remember the position of those tiles,
+        didn't you?); otherwise, they remain visible and are now
+        read-only. The game is complete when the user, with a lot of time
+        on his/her hands, matches all tiles. There is a running
+        tabulation kept on the number of tries.  There is also a button
+        which resets the game and randomizes the tiles.
+
+  \item \texttt{acromemory2}: For this game you have two identical
+        rectangular images subdivided into tiles (or slices), which
+        are arrayed in rows and columns. The tiles for one of the
+        two images is randomly re-arranged. The object of the
+        game is to find all the matching tiles by choosing a tile
+        from one image and a tile from the other image. As in the
+        first case, if the selected tiles do not match, they are
+        hidden after a short interval of time (you did remember the
+        position of those tiles, didn't you?); otherwise, they
+        remain visible and are now read-only. The game is over when
+        all tiles are matched; when this occurs, end-of-game special
+        effects occur that will dazzle the senses. There is an
+        option to view a small image to help you locate the matching
+        tiles on the non-randomized; useful if the image is complex.
+\end{itemize}
+\paragraph*{The demo files.} These are \texttt{acromemory1.tex} and
+\texttt{acromemory2.tex}. These files show how to lay out the
+various elements of this package.
+
+\paragraph*{Supported workflows.} This new version of \pkg{acromemory} is a complete
+re-write of the old version. All the common workflows are supported: \app{pdflatex},
+\app{lualatex}, \app{xelatex}, and \app{dvips -> distiller}.
+
+\section{Package Options}
+
+There are a few options of this package:
+\begin{itemize}
+    \item \texttt{acromemory1} and \texttt{acromemory2}: As described
+        earlier. The \texttt{acromemory2} option is the default.
+
+    \item \texttt{draft}: The \opt{draft} option is passed to the
+        \pkg{graphicx} package. Useful when setting up the layout of your
+        document and when composing the document. Works for \app{pdflatex}
+        and \app{lualatex} PDF creators.
+
+    \item \texttt{includehelp}: When building a file with the acromemory2
+        option, you can also include a help image, a small picture of the
+        game board to help the user to match the randomized tiles with the
+        ones on the non-randomized game board. Useful if the image is very
+        complex. The demo file \texttt{acromemory2.tex} contains the
+        necessary code for producing the help feature, the commands only
+        create the help feature if the \opt{includehelp} option is taken.
+\end{itemize}
+
+\section{Commands of the Package}
+
+We describe the commands of this package as well as methodology for creating
+tiled graphics for use by this package.
+
+\subsection{Commands for the \textsf{acromemory1} option}
+
+\begin{figure}[htb]\centering\fboxsep0pt
+\fbox{\includegraphics[width=.5\linewidth]{graphics/am1}}
+\caption{Partially worked \textsf{acromemory1} puzzle}\label{fig:am1}
+\end{figure}
+
+\paragraph*{The preamble.}
+For the \opt{acromemory1} option, the preamble begins with some variation of
+the following:
+\bVerb\def\1{\llap{\ding{192}\enspace}}\def\2{\llap{\ding{193}\enspace}}
+\begin{minipage}[t]{.5\linewidth}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+!normalfont!bfseries(Using the !pkg(web) package)
+\documentclass{article}
+!1\usepackage[%
+!1  web=designv,useacrobat
+!1]{aeb_pro}
+!2%\usepackage[designv]{web}
+\usepackage[acromemory1]{acromemory}
+\end{Verbatim}
+\end{minipage}\hfill
+\begin{minipage}[t]{.5\linewidth}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+!normalfont!bfseries(Without using the !pkg(web) package)
+\documentclass{article}
+\usepackage[acromemory1]{acromemory}
+\end{Verbatim}
+\end{minipage}
+\eVerb The lines \ding{192} are optional, the advantage of using the
+\pkg{aeb\_pro} package is that it enables the example files to be compiled
+\emph{using all workflows}: \app{pdflatex}, \app{lualatex}, \app{xelatex},
+and \app{dvips\,->\,distiller}. The alternative is to use \ding{193}, that
+is, the \pkg{web} package with a design option, in this case \opt{designv}.
+On the right is the appropriate declarations without using \pkg{web}. All
+sample files use the \pkg{web} package.
+
+\subparagraph*{Embedding the tiles.} The next step is to embed the tiles
+using the \env{embedding} environment of the \pkg{icon-appr}
+package:\footnote{\url{https://ctan.org/pkg/icon-appr}}
+\begin{Verbatim}[fontsize=\small,xleftmargin=\amtIndent]
+\begin{embedding}
+%\isPackage
+\amEmbedTiles{dinos}{10}{dinos/mydinos}
+\end{embedding}
+\end{Verbatim}
+The \cs{isPackage} and \cs{amEmbedTiles} commands are used for embedding the
+tiles.
+\bVerb\takeMeasure{\string\amEmbedTiles\darg{\ameta{name}}\darg{\ameta{n-tiles}}\darg{\ameta{path}}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\isPackage
+\amEmbedTiles{!ameta(name)}{!ameta(n-tiles)}{!ameta(path)}
+\end{dCmd}
+\eVerb were \ameta{name} is the name of the tile set; \ameta{n-tiles} is the
+number of \emph{distinct tiles}, and \ameta{path} is the path to the base name of
+the graphics. Note that for puzzles of type \opt{acromemory1}, the tiles are
+doubled to make a total of $2\times \texttt{\ameta{n-tiles}}$ tiles on the board.
+
+\subparagraph*{Comments on the tiled files required.} There are two ways the tiles
+are delivered:
+\begin{enumerate}
+  \item As a single package file, in which case the \pkg{acromemory} package
+      looks for the file \texttt{\ameta{path}\_package.pdf}. The tiles are
+      the pages of the package document. Signal to \pkg{acromemory} that the tiles
+      are packaged by including \cs{isPackage} prior to the \cs{embedTiles} command.
+      For example, from the \texttt{acromemory1.tex} demo file,
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\begin{embedding}
+\isPackage
+\amEmbedTiles{dinos}{10}{dinos/mydinos}
+\end{embedding}
+\end{Verbatim}
+    \pkg{acromemory} looks for the file \texttt{mydinos\_package.pdf} in the
+    \texttt{dinos} folder.
+
+    \textbf{Note.} This feature is only available for the \app{pdflatex}, \app{lualatex},
+    and \app{dvips\,->\,distiller} workflows.
+  \item If the files are not packaged, \pkg{acromemory} looks for the files
+    \texttt{\ameta{path}\_01.pdf}, \texttt{\ameta{path}\_02.pdf}, \dots, \texttt{\ameta{path}\_10.pdf}, \dots.
+    This method is available to all workflows, including \app{xelatex}.
+\end{enumerate}
+In addition to the tiles themselves, packaged or not, \pkg{acromemory} needs
+one or two more files. We illustrate using the dinos example. For the
+\app{dvips\,->\,distiller} workflow, \app{acromemory} looks for
+\texttt{mydinos.eps}; for all other workflows, it looks for
+\texttt{mydinos.pdf}. These files are used to measure the dimensions of a
+typical tile. The two basic files \texttt{mydinos.eps} and
+\texttt{mydinos.pdf} are just one of the tiles, perhaps it is just
+\texttt{mydinos\_01} as an EPS or PDF file.\footnote{If you never use the
+\app{dvips\,->\,distiller} workflow, EPS file is not needed.}
+
+
+\paragraph*{In the body of the document.}
+
+After the tiles have been embedded (in the preamble), we are ready to insert
+the tiles into the document with \cs{insertTiles}:
+\begin{Verbatim}[xleftmargin=\parindent]
+\insertTiles{dinos}{2in}{5}{4}
+\end{Verbatim}
+The syntax for \cs{insertTiles} is,
+\bVerb\takeMeasure{\string\insertTiles\darg{\ameta{name}}\darg{\ameta{width}}\darg{\ameta{n-rows}}\darg{\ameta{n-cols}}}%
+%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\insertTiles{!ameta(name)}{!ameta(width)}{!ameta(n-rows)}{!ameta(n-cols)}
+\end{dCmd}
+\eVerb where \ameta{name} matches the \ameta{name} to an earlier embedding;
+\ameta{width} is the width of your puzzle board; \ameta{n-rows} is the number
+of rows; and \ameta{n-cols} is the number of columns. Of course, $\texttt{\ameta{n-rows}}\times\texttt{\ameta{n-cols}}=2\times\texttt{\ameta{n-tiles}}$.
+
+\paragraph*{Other controls.} There a two other controls to mention.
+\bVerb\takeMeasure{\string\playItAgain[\ameta{eforms-opts}]\darg{\ameta{wd}}\darg{\ameta{ht}}}%
+%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\messageBox[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\playItAgain[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\end{dCmd}
+\eVerb \cs{messageBox} is a text field that displays various running scores; while
+\cs{playItAgain} is a push button for starting the matching game.
+
+\newtopic\noindent
+The results of all this effort are seen in \hyperref[fig:am1]{Figure~\ref*{fig:am1}},
+or by compiling, playing, and enjoying the file \texttt{acromemory1.tex}.
+
+
+\paragraph*{Creating the tiles.}
+This contents of these paragraphs can be skipped over on first reading. The
+sample file \texttt{acromemory1.tex} uses the `Mini Pics Lil Dinos' font set;
+you need not have the font set itself, the glyphs are contained in the
+mydinos support files.
+
+In this paragraph, we discuss the methodology for creating your own tile files.
+Two support files were developed to create the required files:
+\begin{itemize}
+  \item \texttt{myDinos\_package.tex} is used to create
+      \texttt{myDinos\_package.tex}, required for the \app{pdflatex},
+      \app{lualatex}, and \app{dvips\,->\,distiller} workflows. This file
+      should be studied to create your own package file with some other font
+      set.
+  \item \texttt{myDinos\_files.tex} is used to create the individual files,
+      \begin{quote}\texttt{myDinos\_01.pdf}, \texttt{myDinos\_02.pdf}, \dots,
+      \texttt{myDinos\_10.pdf}\end{quote} as well as the two additional files
+      \texttt{myDinos.pdf} and \texttt{myDinos.eps}. Again, this file should
+      be studied and modified to create these individual files for your own
+      font.
+\end{itemize}
+You need not use a font set to create the tile files, you can use a series of
+small graphics instead. We leave this as an exercise.
+
+\subsection{Commands for the \textsf{acromemory2} option}
+
+\begin{figure}[htb]\centering\fboxsep0pt
+\fbox{\includegraphics[width=.5\linewidth]{graphics/am2}}
+\caption{Partially worked \textsf{acromemory2} puzzle}\label{fig:am2}
+\end{figure}
+
+
+\noindent This option produces a two board matching game.
+\hyperref[fig:am2]{Figure~\ref*{fig:am2}} is a snapshot of the
+demo file \texttt{acromemory2.tex}.
+\paragraph*{Creating the required (tiled) graphics.} For this option you don't have to have a fancy font, any (interesting)
+picture will do. The first step is to decide how many rows and columns you
+want and then tile the image appropriately. To tile the graphic, use the
+\pkg{tile-graphic} package.\footnote{\url{https://ctan.org/pkg/tile-graphic}}
+In the \texttt{examples/duckie} folder, you will find \texttt{duckie-tg.tex},
+which was used to produce all the files needed to create the demo file
+\texttt{acromemory2.pdf}. Compile \texttt{duckie-tg.tex} using your preferred
+workflow to produce all required files.
+
+\newtopic\noindent
+Let's walk through the components of \texttt{acromemory2.tex}.
+
+\paragraph*{The preamble.}
+For the \opt{acromemory2} option, the preamble begins with some variation of
+the following:
+\bVerb\def\1{\llap{\ding{192}\enspace}}\def\2{\llap{\ding{193}\enspace}}
+\begin{minipage}[t]{.5\linewidth}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+!normalfont!bfseries(Using the !pkg(web) package)
+\documentclass{article}
+!1\usepackage[%
+!1  web=designv,useacrobat
+!1]{aeb_pro}
+!2%\usepackage[designv]{web}
+\usepackage[includehelp]{acromemory}
+\end{Verbatim}
+\end{minipage}\hfill
+\begin{minipage}[t]{.5\linewidth}
+\begin{Verbatim}[fontsize=\small,commandchars=!()]
+!normalfont!bfseries(Without using the !pkg(web) package)
+\documentclass{article}
+\usepackage[includehelp]{acromemory}
+\end{Verbatim}
+\end{minipage}
+\eVerb The lines \ding{192} are optional, the advantage of using the
+\pkg{aeb\_pro} package is that it enables the example files to be compiled
+\emph{using all workflows}: \app{pdflatex}, \app{lualatex}, \app{xelatex},
+and \app{dvips\,->\,distiller}. The alternative is to use \ding{193}, that
+is, the \pkg{web} package with a design option, in this case \opt{designv}.
+On the right is the appropriate declarations without using \pkg{web}. All
+sample files use the \pkg{web} package. The use of the \opt{includehelp}
+option is optional.
+
+\subparagraph*{Embedding the tiles.} The next step is to embed the tiles
+using the \env{embedding} environment of the \pkg{icon-appr}
+package:\footnote{\url{https://ctan.org/pkg/icon-appr}}
+\begin{Verbatim}[fontsize=\small,xleftmargin=\amtIndent]
+\begin{embedding}
+%\isPackage
+\amEmbedTiles{duck}{20}{duckie/duckie}
+\end{embedding}
+\end{Verbatim}
+The \cs{isPackage} and \cs{amEmbedTiles} commands are used for embedding the
+tiles.
+\bVerb\takeMeasure{\string\amEmbedTiles\darg{\ameta{name}}\darg{\ameta{n-tiles}}\darg{\ameta{path}}}%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\isPackage
+\amEmbedTiles{!ameta(name)}{!ameta(n-tiles)}{!ameta(path)}
+\end{dCmd}
+\eVerb were \ameta{name} is the name of the tile set; \ameta{n-tiles} is the
+number of \emph{tiles}, and \ameta{path} is the path to the base name of
+the graphics.
+
+In addition to the tiles themselves, packaged or not, \pkg{acromemory} needs
+one or two more files. We illustrate using the duckie example. For the
+\app{dvips\,->\,distiller} workflow, \app{acromemory} looks for
+\texttt{duckie.eps}; for all other workflows, it looks for
+\texttt{dickie.pdf}. These files are used to measure the dimensions of the
+image.\footnote{If you never use the \app{dvips\,->distiller} workflow,
+EPS file is not needed.}
+
+
+\paragraph*{In the body of the document.}
+
+After the tiles have been embedded (in the preamble), we are ready to insert
+the tiles into the document. Keep in mind, there are two puzzle boards:
+the left one which is the non-randomize tiled picture, and the one on the right
+which is the randomized tiled picture. The two commands \cs{insertTilesL} and \cs{insertTilesR}
+insert the left and right puzzle boards, respectively. For example,
+\begin{Verbatim}[xleftmargin=\parindent]
+\insertTilesL{duck}{2in}{4}{5}\qquad
+\insertTilesR{duck}{2in}{4}{5}
+\end{Verbatim}
+The syntax for \cs{insertTilesL} and \cs{insertTilesR} is,
+\bVerb\takeMeasure{\string\insertTilesL\darg{\ameta{name}}\darg{\ameta{width}}\darg{\ameta{n-rows}}\darg{\ameta{n-cols}}}%
+%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\insertTilesL{!ameta(name)}{!ameta(width)}{!ameta(n-rows)}{!ameta(n-cols)}
+\insertTilesR{!ameta(name)}{!ameta(width)}{!ameta(n-rows)}{!ameta(n-cols)}
+\end{dCmd}
+\eVerb where \ameta{name} matches the \ameta{name} to an earlier embedding;
+\ameta{width} is the width of your puzzle board; \ameta{n-rows} is the number
+of rows; and \ameta{n-cols} is the number of columns. Of course, $\texttt{\ameta{n-rows}}\times\texttt{\ameta{n-cols}}=\texttt{\ameta{n-tiles}}$.
+
+\paragraph*{Other controls.} There a two other controls to mention.
+\bVerb\takeMeasure{\string\rolloverHelpButton[\ameta{eforms-opts}]\darg{\ameta{wd}}\darg{\ameta{ht}}}%
+%
+\begin{dCmd}[commandchars=!()]{\bxSize}
+\tryItAgain[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\messageBox[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\helpImage[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\rolloverHelpButton[!ameta(eforms-opts)]{!ameta(wd)}{!ameta(ht)}
+\end{dCmd}
+\eVerb \cs{messageBox} is a text field that displays various running scores; while
+\cs{tryItAgain} is a push button for starting the matching game. The other two
+commands \cs{helpImage} and \cs{rolloverHelpButton} are used when the \opt{includehelp}
+option is taken. These two commands do nothing if \opt{includehelp} is not specified.
+
+\newtopic\noindent
+The results of all this effort are seen in \hyperref[fig:am2]{Figure~\ref*{fig:am2}},
+or by compiling, playing, and enjoying the file \texttt{acromemory2.tex}.
+
+
+\subsection{Commands common to both options}
+
+When the user begins to work on the puzzle(s) without first pressing the
+`\textsf{Play again}' or the `\textsf{Test your Memory}' button, an alert box
+with the one of the following messages appear, depending on whether
+\opt{acromemory1} or \opt{acromemory2} option is in force:
+\begin{Verbatim}
+\newcommand{\initFirstiMsg}{"Press the 'Play again'
+  button to initialize the puzzle"}
+\newcommand{\initFirstiiMsg}{"Press the 'Test Your Memory'
+  button to initialize the puzzle"}
+\end{Verbatim}
+`\textsf{Play again}' and `\textsf{Test your Memory}' are the default
+captions to  the \cs{playItAgain} and \cs{tryItAgain} controls. Should you change the
+caption of, for example, \cs{playItAgain}, you would then redefine \cs{initFirstiMsg}:
+\begin{Verbatim}[xleftmargin=\amtIndent]
+\playItAgain[\CA{Play!}]{}{12pt}
+\renewcommand{\initFirstiMsg}{"Press the 'Play!' button to
+  initialize the puzzle"}
+\end{Verbatim}
+Or, perhaps redefine the captions and messages for some other language.
+
+
+
+\section{Final comments}
+
+Use any of the demo files as a template to create your own memory
+game. Don't forget (use your memory?) that the \textsf{web} package
+has options to apply a background color or a graphic---this will
+jazz up your memory game.
+
+I do hope you find this game package fun, and that you will be
+creative in its use. Perhaps you can apply the techniques of this
+package to create your own game package, there are many
+possibilities.
+
+\newtopic Now, I simply must get back to my retirement! \dps
+
+
+
+\end{document}
-- 
cgit v1.2.3

