diff options
Diffstat (limited to 'texmf-dist/source/latex/acromemory/doc/acromemory_man.tex')
-rw-r--r-- | texmf-dist/source/latex/acromemory/doc/acromemory_man.tex | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/texmf-dist/source/latex/acromemory/doc/acromemory_man.tex b/texmf-dist/source/latex/acromemory/doc/acromemory_man.tex new file mode 100644 index 00000000..fd8869d5 --- /dev/null +++ b/texmf-dist/source/latex/acromemory/doc/acromemory_man.tex @@ -0,0 +1,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} |