summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/aeb_pro/acromemory/doc/acromemory_man.tex
blob: fd8869d5384143c2ece7e83b22202d6f4a4b291a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,usesf,tight,latextoc,pro},
    eforms,
%    linktoattachments,
    aebxmp
]{aeb_pro}
%\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage[usecmtt]{myriadpro}
\usepackage[altbullet]{lucidbry}
\usepackage{acroman}

%\usepackage{myriadpro}
%\usepackage{acaslonpro}
%\usepackage{ajensonpro}
%\usepackage{minionpro}
%\usepackage{newsgothicstd}
%\usepackage{lucidbry}

\university{\AcroTeX.Net\\The AeB Pro family}
\title{The AcroMemory Package\texorpdfstring{\\}{: }Manual of Usage}
\author{D. P. Story}
\email{dpstory@acrotex.net}
\subject{Documentation for AcroMemory, the memory game}
\keywords{Adobe Acrobat, JavaScript, AcroSlicing, game}
\copyrightStatus{True}
\copyrightNotice{Copyright (C) \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$}}$}


\definePath\bgPath{"C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"}
\begin{docassembly}
\addWatermarkFromFile({
    bOnTop:false,
    cDIPath:\bgPath
});
\executeSave();
\end{docassembly}

\begin{document}

%\begingroup

%\linewidth=\fullscreenwidth
%\advance\linewidth\oddsidemargin
%\setlength{\oddsidemargin}{0pt}
\maketitle

%\endgroup

\changelinkcolorto{black}

\tableofcontents

\changelinkcolorto{webgreen}


\section{What is the AeB Pro Family?}

  Through the years, I have tried to make my AeB software
  ({Acro\negthinspace\TeX} eDucation Bundle) compatible with
  \textsf{pdftex} and \textsf{dvipdfm}; however, during that time,
  I've developed a number of techniques that require the use of
  Acrobat and distiller. Therefore, I have set off in a new
  direction and will be publishing a new line of {\LaTeX} packages,
  ones that require the use of Acrobat.\nhfootnote{I will, however,
  continue to develop the original AeB, never fear!}

\newtopic The current package, \textsf{AcroMemory}, requires the use
          of Acrobat Pro~7.0 or later.

\section{Introduction}

At the prompting and encouragement of my erstwhile friend,
J\"{u}rgen, I present to you \textsf{AcroMemory}, and for the life
of me, I can't remember why.

Oh, yes, \textsf{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).
\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 should be even, each tile should 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.
        There is no reset button at this time, to play again, the
        user must therefore close and open the document.
\end{itemize}
The demo files are \texttt{acromemory1\_1.tex},
\texttt{acromemory1\_2.tex}, \texttt{acromemory2\_1.tex} and
\texttt{acromemory2\_2.tex}. These files show how to lay out the
various elements of this package.

\newtopic\textbf{Requirements:} Acrobat~7 Professional.

\section{Distribution and Installation}\label{installation}

The distribution comes with the following files:
\begin{itemize}

    \item \texttt{acromemory.dtx}, \texttt{acromemory.sty} and \texttt{acromemory.ins}:
    These are the program files.  The file \texttt{acromemory.dtx} has additional documentation
    with more technical details than this manual.

    \item The files \texttt{acromemory1\_1.tex},
    \texttt{acromemory1\_2.tex}, \texttt{acromemory2\_1.tex} and
    \texttt{acromemory2\_2.tex}: The demo files for this package.

    \item \texttt{aeb\_pro.js}: A JavaScript file that contains
    security restricted methods.

    \item The \textsf{AeB Slicing} Batch Sequence: This is a batch
        sequence that slices a given image into a specified number of
        rows and columns. The documentation file name is
        \texttt{aebslicing\_sequ\_doc.pdf} and comes with the
        distribution. Installation details for \textsf{AeB Slicing}
        are contained in its documentation.

    \item Sample image files, \texttt{dinos} (for the
    \texttt{acromemory1} option) and \texttt{dpsweb} (this time
    for the \texttt{acromemory2} option), contained in their own folders.

\end{itemize}

\newtopic When you unzip \texttt{acromemory.zip}, the folder
\texttt{acromemory} will be created, the entire distribution will be
placed in this folder. This folder must be on your {\LaTeX} search
path and you need to refresh your file name database if you are
using a {\TeX} system, such as MIK\TeX, that has this database
scheme. At the top level will be the {\LaTeX} package and demo
files. The subfolders are
\begin{itemize}
    \item \texttt{aeb\_pro}: In this folder is \texttt{aeb\_pro.js}, a
        JavaScript file that needs to be installed on your hard drive.
        Copy this file to the User's
            \texttt{JavaScripts} folder. To find this folder, execute the
            script
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
app.getPath("user", "javascript");
\end{Verbatim}
in the JavaScript Debugger Console window.\nhfootnote{Place the cursor
on the line containing this script and press the \texttt{Ctrl+Enter}
key.} The return value of this is the path to the
\texttt{JavaScripts} folder; for example, on my system it returns
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
/C/Documents and Settings/dps/Application Data/
    Adobe/Acrobat/8.0/JavaScripts
\end{Verbatim}
For user's of Acrobat 10.1.1 (or later), the JavaScripts folder has moved,
see my blog article \textsl{\href{http://www.acrotex.net/blog/?p=737}{Acrobat Security Changes in 10.1.1 and
Acro\!\TeX}}.

After placing \texttt{aeb\_pro.js}, restart Acrobat so it will read this file.
    \item \texttt{dpsweb}: Image files used in \texttt{acromemory2\_1.tex} and \texttt{acromemory2\_2.tex}.
    \item \texttt{dinos}: Image files used in \texttt{acromemory1\_1.tex} and \texttt{acromemory1\_2.tex}.
\end{itemize}

\newtopic Follow the installation instructions for the \textsf{AcroSlicing} batch sequence.

\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, so it need never be used, actually.
    \item \texttt{iconfile}: There are two methods of delivering the slices of the game board(s) to this package:
    \begin{enumerate}
        \item The default method is to have one file for each sliced
            image. There is a numbering system for the slices, the same system
            used by \textsf{Aeb Slicing} batch sequence, is to number them
            with a two digit number across rows:\smallskip

\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\texttt{<basename>\_01}, \texttt{<basename>\_02}, ...
\end{Verbatim}

        \item[]The demo files \texttt{acromemory1\_2.tex} and
            \texttt{acromemory2\_2.tex} illustrate this method.

        \item All slices are placed in a single PDF in the same order just
            described, that is listed by rows. There is an option in the
            \textsf{AeB Slicing} batch sequence for ``packaging'' the
            slices in this way. The demo files \texttt{acromemory1\_1.tex}
            and \texttt{acromemory2\_1.tex} illustrate this method.
    \end{enumerate}
    The \textsf{AcroMemory} package expects, by default, the first method
    described. By specifying the \texttt{iconfile} option,
    \textsf{AcroMemory} will get the slices for the single PDF.

    \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 slices with the ones on
        the non-randomized game board. Useful if the image is very complex.
        The demo files \texttt{acromemory2\_1.tex} and
        \texttt{acromemory2\_2.tex} both contain the necessary code for
        producing the help feature, the commands only create the help feature
        if the \texttt{includehelp} option is taken.
\end{itemize}

\noindent\textbf{\color{red}Important.} You need to set the preferences of Acrobat as follows:
\begin{enumerate}
    \item Start Acrobat, and select \texttt{Edit > Preferences}
    \item Choose Trust Manager from the Categories panel on the left
    \item Check the `Allow external content' check box
\end{enumerate}
\noindent The above settings allow the post-distillation assembly to take place.

\section{Commands of the Package}

This section describes the various commands available to you through
this package. This section can be skipped on first reading, most of
the commands are described less formally in subsequent sections.

\newtopic The following commands are suitable for placement in the
preamble of your document.

\begin{itemize}
   \item \cs{theTotalTiles}: The total number of tiles in the game board. This parameter is required.
   For example, \verb!\theTotalTiles{20}!.
   \item \cs{theNumRows}: The number of rows in the game board. This parameter is required.
   For example, \verb!\theNumRows{5}!.
   \item \cs{theNumCols}: The number of columns in the game board.
   This parameter is required. For example, \verb!\theNumCols{4}!.
   \item \cs{theImportPath}: The import path to the base name of the image. The path
   should use the path specification as defined in the \emph{PDF Reference}, and the file name should
   have no extension. Required. For example,\smallskip
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\theImportPath{myFig/myimages}
\end{Verbatim}

   There is an optional argument that is typically used when the \texttt{iconfile} is in effect
   with the \texttt{acromemory2} option,  and an image of the game board is different from the
   path given by the optional argument; for example,
\begin{verbatim}
   \theImportPath[dpsweb/dpsweb]{dpsweb/dpsweb_package}
\end{verbatim}
   The required argument points the packaged icons, the optional argument points to
   a file showing the entire image. See \texttt{acromemory2\_1.tex} for an
   example of this situation.
   \item \cs{theIconExt}: The extension of the image file(s). Required if different
   from \texttt{pdf}. (Acrobat can make the conversion to PDF.)
   \item \cs{theTeXImageWidth}: The scaled width of the rectangular game board. The
   game board will be rescaled so that its width is equal to the value specified
   by the argument of this command, e.g., \verb!\theTeXImageWidth{2in}!.
   \item\cs{provideDimensions}: If the dimension of the game board is known, the width
   and height can be entered with this command using the two parameters. For example,
   \verb!\provideDimensions{2in}{2.5in}! (width, height).
\item \cs{bDebug}: A debugging command. When executed in the
    preamble, more is written to the Acrobat console as the document is
    opened the first time, also, the icons are initially visible so you
    can see the layout, and quickly play the game. This was used in
    development extensively to help develop the JavaScript.

\end{itemize}

\newtopic The rest of the commands in this section are properly
placed in the body of the document. They are the elements of the
game board(s) and supporting elements.

\newtopic\textbf{Game Board(s)}
\begin{itemize}
\item \cs{ulCornerHere}: Used with the \texttt{acromemory1} option,
this command sets the upper left corner of the game board. It is
followed by either of the two commands \cs{reserveSpaceByDimension} or
\cs{reserveSpaceByFile}.

\item \cs{LulCornerHere}, \cs{RulCornerHere}: Used with the
\texttt{acromemory2} option, these commands set the upper left
corner of the two game boards, on the left and the other on the
right. Each of these two commands is immediately followed by one of
the two commands \cs{reserveSpaceByDimension} or
\cs{reserveSpaceByFile}.

\item \cs{reserveSpaceByDimension}: If the size of the image is
known, you can reserve space for it by using this command. It has
two arguments: the first argument is the width of the image, the
second is the height. This command is useful for
\texttt{acromemory1} where the game board is made up of some many
rows and columns of tiles whose dimensions you know.

\item \cs{reserveSpaceByFile}: This command does an
\cs{includegraphics} in draft mode to get the dimensions of the game
board. The required space is made for the rescaled image. The
optional argument can be used to insert a file that has the same
aspect ratio as the puzzle, the default is the one specified by the
optional argument of \cs{theImportPath}, which, if not specified, is
the same as the required argument of \cs{theImportPath}.
\end{itemize}

\goodbreak
\newtopic\textbf{Supporting fields}
\begin{itemize}

\item \cs{messageBox}: A message text field. As the user works the
puzzle, the progress is reported to this field.
\end{itemize}

\newtopic The following button is only appropriate when the \texttt{acromemory1}
option is taken.

\begin{itemize}
\item \cs{playItAgain}: For the \texttt{acromemory1} option, this
button can be placed to reset the game board, the icons are
rearranged and hidden again.
\end{itemize}

\newtopic When \texttt{acromemory2} and the \texttt{includehelp}
options are taken, these commands are available. See the
\texttt{acromemory.dtx} documentation for indications of modifying
these commands.

\begin{itemize}
\item \cs{helpImage}: The button that will contain an icon of the
puzzle. There is one optional argument used to modify the appearance
of the button.

\item \cs{setHelpImageWidth}: Used to set the width of the
\cs{helpImage} button. The default width is 1 inch. For example,
\verb!\setHelpImageWidth{1.5in}!.

\item \cs{theHelpCaption}: Use this command to set the caption of
the help image. For example, \verb!\theHelpCaption{I need help}!.

Captions with accents and such, you need to use Unicode escape
sequences, \verb!\uXXXX!, where \texttt{XXXX} are four hexadecimal
digits. For example, the caption specified by
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\theHelpCaption{J\string\\u00FCrgen needs help}
\end{Verbatim}
will appear in the PDF document as `J\"{u}rgen needs help'. Notice the
\verb!\string\\! sequence that is needed from the {\LaTeX} source.


\item\cs{rolloverHelpButton}: The image is normally hidden until the
user rolls over the \cs{rolloverHelpButton}. The icon appears with a
caption under it, the content of the caption can be entered using
\cs{theHelpCaption}. This command has three parameters, one of which
is optional. The first (optional) parameter is used to change the
appearance of the button; the next two required parameters are the
width and height of the button.
\end{itemize}


\section{The \texttt{acromemory1} Option}

In this game, there is only one game board with an even number of
tiles. Each tile has an identical twin, and all the tiles are
randomly rearranged. The object of the game is to find all the
matching pairs. See the demo files \texttt{acromemory1\_1.tex} and
\texttt{acromemory1\_2.tex} for examples of this game; the former
file uses the \texttt{iconfile} option, whereas the latter does not.
Both illustrate the \cs{reserveSpaceByDimension} and
\cs{provideDimensions}. See the comments in these files for more
details.

The tiles for this game were created by a font that I have called
`Mini Pics Lil Dinos'. The source file for the creation of the
\texttt{myDinos.pdf}, the icon file, is \texttt{myDinos.tex}. In
this \texttt{tex} file, the \textsf{web} package is used to create
pages 2~inches by 2~inches. The \texttt{multido} package from
\textsf{PSTricks} was used to produce the pages. See
\texttt{myDinos.tex} for additional comments.

To create your own icon file, you will need either a font set with
nice images on it, or you can be creative, perhaps using
\textsf{PSTricks} to create a series of figures.

Given that you have created your icons in a single file, should you
wish to save each page to a separate file, you can execute the
following JavaScript in the console, while the icons file is open in
Acrobat.\smallskip
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
var thisPath = /.*\//i.exec(this.path)[0];
var filename = this.documentFileName.replace(/\.pdf$/i,"");
for (var i = 0; i < this.numPages; i++) {
    var j = i+1;
    var index = (j < 10 ) ? ("0"+j) : (""+j);
    this.extractPages({
        nStart: i,
        cPath: thisPath+filename+"_" + index +".pdf"
    });
}
\end{Verbatim}
The code is included in the file \texttt{myDinos.tex}.


\section{The \texttt{acromemory2} Option}

This option was the original concept, it was only after I completed
the two game board version did I decide to do the classic one game
board version. This is why \texttt{acromemory2} is the default. The
\texttt{acromemory2} version was much more interesting and
challenging to create.

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 slice the image appropriately.
This is why I wrote the \textsf{AeB Slicing} batch sequence. Read
the documentation for \textsf{AeB Slicing} and slice your picture.

Not only do you need slices of your picture, you also need an \texttt{EPS}
of your picture. This is used by latex to leave room for the game board.
Acrobat can make the conversion for you, as follows:

\newtopic\textbf{To convert your image to EPS}
\begin{enumerate}
\item Bring your image into Acrobat
\item Click the \texttt{File > Save As} menu item
\item In the Save As dialog box, choose \texttt{Encapsulated PostScript (*.eps)} from the Save as type list
\item Navigate to the folder containing your tiles, and click the \texttt{Save} button
\end{enumerate}

\newtopic See the demo files \texttt{acromemory2\_1.tex} and
\texttt{acromemory2\_2.tex} for examples of this game; the former
file uses the \texttt{iconfile} option, whereas the latter does not.
Both illustrate the \cs{reserveSpaceByFile}. See the comments in
these files for more details.

Use either of these two demo files as a template to create your own
memory game. Don't forget that the \textsf{web} package has options
to apply a background color or a graphic---this will jazz up your
memory game.

\section{Assembly}

Try compiling one of the demo files. You must have the AeB already
installed on your system, of course.  Be sure to specify your dvi to
postscript converter, for most of you that will be dvips. For example,
the preamble of the demo docs, and later your own documents should
appear as follows:\smallskip
\begin{Verbatim}[xleftmargin=20pt,fontsize=\fontsize{9}{11}\selectfont]
\documentclass{article}
\usepackage[designv,nodirectory,dvips]{web} % <-- specify dvips or dvipsone
\usepackage[execJS]{eforms}
\usepackage{graphicx}
\usepackage{acromemory}
\end{Verbatim}

\newtopic LaTeX your source file, then invoke your dvi-to-ps
converter to obtain a postscript file.
Now open Acrobat Distiller and distill the new postscript document.
If all goes well, Acrobat will start, if not already, and the newly
created PDF document will open in it. Notice that the hour glass
cursor appears; this means that the post-assembly process is
ongoing: You note the one or two little dots on the page (where the
game boards should be), these are the fields creates by the commands
\cs{ulCornerHere}, \cs{LulCornerHere} or \cs{RulCornerHere}. They
are soon replaced by the game board(s). Amazing, simply amazing!

After the hour glass cursor changes, perhaps to the hand tool, be
sure to save your document, \emph{this is important}. By saving the
document, the game board does not have to be rebuilt every
time the file is opened. Once assembled and saved, the game can be
played on Adobe Reader 7.0 or later.

\newtopic\textbf{\color{red}Tip.} Use the \textsf{PDF Optimizer}, under the \textsf{Advance} menu, to
reduce the size of the file.\nhfootnote{For Acrobat 10, \textsf{PDF Optimizer} is called the
\textsf{Optimized PDF} under the \textsf{File \texttt{>} SaveAs}; also, you can use the \textsf{Reduced Size PDF}
menu function} For example, the file size of \texttt{acromemory2\_2.pdf}
after distillation was 462\,KB, but after running the
PDF Optimizer on it, the file size was reduced to 85\,KB!


\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}