summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/acromemory/doc/acromemory_man.tex
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/source/latex/acromemory/doc/acromemory_man.tex')
-rw-r--r--texmf-dist/source/latex/acromemory/doc/acromemory_man.tex510
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}