summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/fldigigal/fdg_man.tex
blob: 2665aef525fd891dd4a998d94c641943b6fb9897 (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
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,tight,usetemplates,%usesf,
        forcolorpaper,latextoc,pro},
        eforms,aebxmp,graphicxsp={showembeds}
]{aeb_pro}
\usepackage{rmannot}
\usepackage{fldigigal}

%\usepackage{multicol}
\usepackage{aeb_mlink}
\usepackage{array}
\usepackage[altbullet]{lucidbry}
%\usepackage{myriadpro}

\usepackage{makeidx}
\makeindex
\usepackage{acroman}

\usepackage[inactive]{srcltx}

\def\expath{../examples}

\urlstyle{tt}

\makeatletter
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\makeatother

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \texorpdfstring{\textsf{fldigigal} Package\\[1em]}{: }
        Creating Flash Digital Galleries},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Creating Flash Digital Galleries},
    talksite={\url{www.acrotex.net}},
    version={1.0},
    keywords={AcroTeX, PDF, Flash Photo Gallery, rmannot},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-40pt,fontsize=large,color=aeb,afterskip=1sp}
\subsectionLayout{indent=-20pt,color=aeb,afterskip=1sp}
\subsubsectionLayout{indent=0pt,color=aeb,afterskip=1sp}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\newenvironment{eqComments}[1][\strut]{\smallskip\leftskip-\labelwidth
\item[]\textbf{\textcolor{blue}{#1}}}{\par\smallskip}

%----------fldigigal--------------
\definePath{\pathToSource}{%
    C:/Users/Public/Documents/My TeX Files/tex/%
        latex/aeb/aebpro/fldigigal/examples}
\definePath{\digisOnline}{%
    http://www.math.uakron.edu/~dpstory/photos/pa_demo}
\definePath{\digisLocal}{\pathToSource/digis}

\fdgXmlList{myDigis}
{%
    \image{path=\digisOnline/Chrysanthemum.jpg,caption=Jürgen\'s Chrysanthemum,online} %\iso{252}
    \image{path=\digisOnline/Desert.jpg,caption=Desert,online}
    \image{path=\digisOnline/Hydrangeas.jpg,caption=Hydrangeas,online}
    \image{path=\digisOnline/Jellyfish.jpg,caption=Jellyfish,online}
    \image{path=\digisOnline/Koala.jpg,caption=Koala,online}
    \image{path=\digisOnline/Lighthouse.jpg,caption=Lighthouse,online}
    \image{path=\digisOnline/Penguins.jpg,caption=Penguins,online}
    \image{path=\digisOnline/Tulips.jpg,caption=Tulips,online}
}
%---------fldigigal---------------------

%\pagestyle{empty}
\parindent0pt\parskip\medskipamount

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

\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}\label{s:intro}

The \textsf{fldigigal} package is the third application of \textsf{rmannot};
the others are the {\AcroFLeX} and \textsf{yt4pdf} packages.

The \emph{Flash Digital Gallery} distribution consists of a {\LaTeX}
package, \textsf{fldigigal}, several \textsf{SWF} files, a small collection
of digital photos, and sample files. The purpose of this distribution is
to provide a convenient way to create a Flash slideshow. The distribution
offers several design layouts of the slideshow, called \emph{galleries}.
Below is an example of a slideshow created by \textsf{fldigigal} using
source code from this document.
\begin{center}%\previewtrue
\resizebox{.9\linewidth}{!}
{%
    \fgRmAnnot[galleryopts={gallery=vthumbs1,auto=false,captionalign=center},
        posternote={Flash Digital Gallery},enabled=pageopen
    ]{myDigis}
}
\end{center}
The photos themselves may be embedded in the PDF file (increasing the
file size), or may be referenced with an URL. The gallery can be manually
operated, or set to change photos at a regular interval.

There are steps for creating a flash digital gallery:
\begin{enumerate}
    \item In the preamble of your document, specify the digitals (PNG,
    JPG, GIF) you want displayed in you gallery. This is entered by
    using the \cs{fdgXmlList} command. See the section
    \Nameref{fdgXmlList} for details.
    \item In the body of the document, create a Rich Media Annotation (RMA)
    using the command \cs{fgRmAnnot}, defined in \textsf{fldigigal}. For
    details of this command, see the section
    \Nameref{fgRmAnnot}.
\end{enumerate}



\section{Requirements}

This package is part of \textsf{AeB Pro}, which means Acrobat Distiller is
used to create the PDF; the package requires \textsf{rmannot}, which
creates rich media annotations. Therefore, we require
\begin{equation*}
    \boxed{\text{\large\bfseries Adobe Acrobat, version 9.0 or later}}
\end{equation*}
To use this package, the document author must have AeB and AeB Pro
installed, as well as \textsf{rmannot}. The manual for \textsf{rmannot}
needs to be read closely to install it properly and for it to function correctly.

\section{Configuring your installation}

In addition to configuring the \textsf{rmannot} package correctly, the
\textsf{fldigigal} package needs configuring as well. The \textsf{fldigigal}
comes with a configuration file \texttt{fldigigal.cfg}.  Open this file in
your favorite editor to see
\begin{Verbatim}[fontsize=\small]
% fldigigal config file. Delete the \endinput below and replace the path
% provided with the path to the swf folder of your fldigigal installation.
% This path is used to locate the fldigigal SWF files.
\endinput
\renewcommand{\fdgFolder}{C:/Users/Public/Documents/My TeX Files/%
    tex/latex/aeb/aebpro/fldigigal/swf}
\end{Verbatim}
Edit this file so that \cs{fdgFolder} points to the \texttt{swf} folder on
your computer.

\section{In the Preamble: Populating the
\texorpdfstring{\protect\cs{fdgXmlList}}{\CMD{fdgXmlList}}
Command}\label{fdgXmlList}

The {\AcroTeX} Flash Gallery SWF files take several arguments that are
passed to it using \texttt{FlashVars}; one such variable is a reference to
an XML file that contains the paths and captions to the digital files.
When I began developing the package, the XML file was just hand-written in
an editor; when I started to write the package, I included the
\cs{fdgXmlList} command which writes the XML file as the source file is
compiled.

At the bare minimum, the preamble must include a definition for
\cs{pathToSource} and the \cs{fdgXmlList} command.

The definition of \cs{pathToSource} should be made using the
\cs{definePath} command, defined in the \textsf{eforms} package.
Here is one such definition to a sample file in this distribution.
\begin{Verbatim}[xleftmargin=20pt,fontsize=\small]
\definePath{\pathToSource}{%
    C:/Users/Public/Documents/My TeX Files/tex/%
        latex/aeb/aebpro/fldigigal/examples}
\end{Verbatim}
The \textsf{fldigigal} uses the Adobe Distiller to create the PDF file.
Distiller only works with absolute file references; so, Distiller needs to
know the location of XML file that is to be written by the \cs{fdgXmlList}
command. \emph{This definition is required}.

Another (optional, but recommended) definition is the path to the digital
files. The photos may reside on your local hard drive, or on the Internet.
In the example that follows, we illustrate the method of defining the
paths; one for a local hard drive, the other for photos found online.
\begin{Verbatim}[xleftmargin=20pt,fontsize=\small]
\definePath{\digisOnline}{%
    http://www.math.uakron.edu/~dpstory/photos/pa_demo}
\definePath{\digisLocal}{\pathToSource/digis}
\end{Verbatim}
These paths may then be conveniently included in the \texttt{path} key
of the \cs{image} command, see below.

\begin{dCmd*}{.67\linewidth}
\fdgXmlList[<kv-pairs>]{<name>}{%
    \image{...}
    \image{...}
    ...
    \image{...}
}
\end{dCmd*}
\CmdDescription When the source document compiles, this command writes an
XML file to the source file's folder. The XML is later embedded in the PDF
file when the file is distilled.
\PD The command has three arguments, the first is optional.
\begin{itemize}
    \item[\texttt{[\#1]}] The optional argument labeled above as
        \texttt{[<kv-pairs>]} may include only two (Boolean) key-value
        pairs: \texttt{showcounts} and \texttt{nowrite}.
    \begin{itemize}
        \item \texttt{showcounts} When this key appears as \texttt{showcount} or as
        \texttt{showcount=true}, a count and a total count of the number of
        photos appearing in the gallery is displayed in the title bar.
        The count appears as (1 of 8), for example, but this can be
        redefined by the command \cs{fdgcntOf}. The default definition
        is\medskip
\begin{Verbatim}[xleftmargin=20pt,fontsize=\small]
\newcommand{\fdgcntOf}[1]{\space(#1 of \fdg@numDigis)}
\end{Verbatim}
\par\medskip The default is that no count is written to the title bar of the gallery.
    \item \texttt{nowrite} You optionally include this key in the list
    if the XML has already been written to your source folder; however, if
    you change options, or change the key-value pairs of the \cs{image}
    commands, you will need to re-write the XML by removing the \texttt{nowrite}
    option.
    \end{itemize}
    \item[\texttt{\#2}] The second parameter, \texttt{<name>}, is a
        unique name for the gallery being created with the photos; for
        example \texttt{myVacation2010}. The name should follow the
        rules of a JavaScript variable.
    \item[\texttt{\#3}] The third argument consists of a series of
    \cs{image} commands, each command takes three key-value pairs.
    \begin{itemize}
        \item \texttt{path}: The path to the digital file, the path may be
        that to a digital file on your hard drive, or on the Internet.
        A digital file may be a \textsf{JPG}, \textsf{PNG}, or \textsf{GIF} file.
        \emph{This key is required}.
        \item \texttt{caption}: The (short) descriptive string to be
        displayed along with the associated photo. This key is optional,
        if not present, the filename of the digital file is displayed. See
        the optional key-values \texttt{nocaptions} and \texttt{nocaptionstext} of
        \cs{fgRmAnnot}.
        \item \texttt{online}: Use this key to indicate that the
        \texttt{path} key is an \textsf{URL}, and refers to a resource on the
        Internet. If this key is not present, it is assumed that path
        points to a file on the local hard drive, and Distiller will get
        that file and embed it in the PDF. If Distiller does not find the
        file, distillation is aborted and a message is written to the
        distiller long which suggests that it cannot find the file.
    \end{itemize}
\end{itemize}
Below is an example of the \cs{fdgXmlList} used for this document, I've
modified the first two entries by removing the \texttt{online} key, and
replacing \cs{digiOnline} with \cs{digisLocal} to demonstrate how you
reference each type. (The definitions of \cs{digiOnline} and
\cs{digisLocal} appeared earlier.)  For this definition below, two files
will be embedded (the first two), all others are online and the gallery
will get them from the Internet.
\begin{Verbatim}[numbers=left,xleftmargin=20pt,fontsize=\small]
\fdgXmlList{myDigis}
{%
    \image{path=\digisLocal/Chrysanthemum.jpg,
        caption=Jürgen\'s Chrysanthemum}
    \image{path=\digisLocal/Desert.jpg,caption=Desert}
    \image{path=\digisOnline/Hydrangeas.jpg,caption=Hydrangeas,online}
    \image{path=\digisOnline/Jellyfish.jpg,caption=Jellyfish,online}
    \image{path=\digisOnline/Koala.jpg,caption=Koala,online}
    \image{path=\digisOnline/Lighthouse.jpg,caption=Lighthouse,online}
    \image{path=\digisOnline/Penguins.jpg,caption=Penguins,online}
    \image{path=\digisOnline/Tulips.jpg,caption=Tulips,online}
}
\end{Verbatim}
One comment is needed, refer to line~(3). I've included my friend,
J\"{u}rgen, name value of the \texttt{caption} key to demonstrate how to
use special latin-1 characters. The u-umlaut (ü) may be entered by your
keyboard, as I have, or by special command \verb!\iso{252}!,
which expands to `\makeatletter\texttt{\fdg@iso{252}}\makeatother'. The
interested user is referred to these two online documents.
\begin{align*}
&\text{\footnotesize\url{http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references}}\\
&\text{\footnotesize\url{http://www.html-entities.com/}}
\end{align*}
The \verb!\iso{<dec>}! command expands to \verb!&#<dec>;!, see above
\textsf{URLs} to determine the correct value of the \texttt{<dec>} to get
the desired glyph.

The second comment concerns the single apostrophe (\texttt{'}). The
captions are enclosed in single quotes, so if you want an apostrophe, you
must use the the character entity `\verb!&apos;!', or you can use
\verb!\'!, as I did above. This special command, redefined within a group,
expands to `\verb!&apos;!'. Thus, we can write \verb!Jürgen\'s!, or
\verb!Jürgen&apos;s!, or \verb!J\iso{252}rgen&apos;s!, etc. If you want to
use an ampersand, use `\verb!&amp;!'.

OK, that's it for the preamble; on to \cs{fgRmAnnot}!

\section{In the Body: Create a Gallery with
\texorpdfstring{\protect\cs{fgRmAnnot}}{\CMD{fgRmAnnot}}}\label{fgRmAnnot}

To create a flash gallery of photos, use the command \cs{fgRmAnnot}, its definition
uses the command \cs{rmAnnot}, which is defined in the \textsf{rmannot} package.
\begin{dCmd*}{.5\linewidth}
\fgRmAnnot[<kv-pairs>]{<name>}
\end{dCmd*}
\PD
\begin{enumerate}
    \item The first (optional) parameter is used to pass the key-value pairs of the
    \cs{rmAnnot} command. Additionally, the \texttt{galleryopts} key is
    recognized by the \cs{fgRmAnnot} command. The value of the \texttt{galleryopts} key
    consists of key-value pairs that customize the gallery.
    \begin{itemize}
        \item \texttt{gallery}: The value of this key determines the layout of the gallery.
        Permissible choices are  \texttt{vthumbs1} (vertical thumbnails on the left),
        \texttt{hthumbs1} (horizontal thumbnails below digital), and
        \texttt{nothumbs1} (no thumbnails, the caption bar is a multiline
        text field so longer captions may be displayed). More designs are
        possible, as my skill in
        Flash Professional Pro CS5 increases. The default is
        \texttt{vthumbs1}.
        \item \texttt{trans}: This key determines the transition effects.
            Possible values are \texttt{Blinds}, \texttt{Fade},
            \texttt{Fly}, \texttt{Iris}, \texttt{Photo},
            \texttt{PixelDissolve}, \texttt{Rotate}, \texttt{Squeeze},
            \texttt{Wipe}, \texttt{Zoom}, \texttt{Random}. The default is
            \texttt{Random}.
        \item \texttt{auto}: If true, the gallery will automatically
            display the list of photos at a regular interval. The user can
            stop the automatic display by pressing the pause button. The
            default is \texttt{auto=true}.
        \item \texttt{delay}: The delay, in seconds, between the automatic display of
        photos. The default is 6 (seconds).
        \item \texttt{captionalign} The alignment of the text in the caption bar. Possible choces
        are \texttt{left} (the default), \texttt{right}, and
        \texttt{center}. This key-value pair is ignored for
        \texttt{gallery=nothumbs1}.
        \item \texttt{nocaptions}: A Boolean key, which if \texttt{true},
        the caption strings are not displayed in the caption bar.
        \item \texttt{nocaptionstext}: If the \texttt{nocaptions} key is
        passed, you can populate the caption bar with a static string.
        Thus, \texttt{nocaptionstext=Hi Mom!} displays the string `Hi Mom' in
        the caption bar for each and every photo.
    \end{itemize}

    \item[] See the manual for the \textsf{rmannot} package for more details on the
    key-value pairs that can be passed through the optional first
    parameter.

    \item The \texttt{<name>} argument matches the \texttt{<name>}
    argument of a \cs{fdgXmlList} declared in the preamble.
\end{enumerate}

The example that appeared earlier in this manual has code

\begin{Verbatim}[numbers=left,xleftmargin=20pt,fontsize=\small]
\resizebox{.9\linewidth}{!}
{%
    \fgRmAnnot[%
        galleryopts={gallery=vthumbs1,auto=false,captionalign=center},
        posternote={Flash Digital Gallery},enabled=pageopen
    ]{myDigis}
}
\end{Verbatim}
Line~(1) shows how the gallery may be resized used using \cs{resizebox}
(or by using \cs{scalebox}). In line~(3) we have the \cs{fgRmAnnot}
command that creates the digital gallery. In line~(4), we specify some of the
\texttt{galleryopts} key-value pairs. The other key-value pairs (outside
the scope of \texttt{galleryopts} are \cs{rmAnnot} key-value pairs.
The second argument, the \texttt{<name>} argument is shown in line~(6).
This name matches the name declared earlier in the preamble in an
\cs{fdgXmlList} command.

\section{Sample files}

The following are the sample files shipped with \textsf{fldigigal}:
\begin{itemize}
    \item \texttt{fdg\_demo.tex} lays out the basic structure for creating
    a \emph{{\AcroTeX} Flash Digital Gallery}. You can experiment with
    this file by changing the options.
    \item \texttt{fdg\_demo\_fit.tex} demonstrates how to have a one-page
    gallery whose size matches the size of the page.
\end{itemize}
Advanced examples \href{http://www.math.uakron.edu/~dpstory/aebblog.html}{AeB Blog site}.


\bigskip

That's all for now, I simply must get back to my retirement. {\dps}

\end{document}