summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex3.tex
blob: 26722e775c1ebe0c6e302ce72fc120ed48f6caa5 (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
% Acrobat required
% use useacrobat option with pdftex and xetex if you have acrobat
\documentclass{article}
\usepackage{graphicx,fancyvrb}
% Edit this command as needed
\def\pthToExtras{../extras}
\usepackage[%
    web={
        pro,
        designv,
        tight,
%        forcolorpaper, % uncomment to get doc for paper
        centertitlepage,
        usesf
    },
    eforms,
%
% Attach source file, and the tex log (renamed \jobname.log
% to \jobname.tex.log to avoid the distiller from overwriting it.
% The distiller only creates the log if there some sort of error message; consequently,
% the log for distiller is not attached (no error), but the tex log is destroyed by distiller
    attachsource={tex,log,tex.log},
%
% Just for laughs, let's include Robot Man.
%
    attachments={extras.zip.txt, \pthToExtras/robot_man.pdf},
    aebxmp,
]{aeb_pro}

\DeclareDocInfo
{
    title=The AeB Pro Package\texorpdfstring{\\[1ex]}{: }Attachments and Doc Assembly,
    author=D. P. Story,
    university=Acro\negthinspace\TeX.Net,
    email=dpstory@acrotex.net,
    subject=Test file for the AeB Pro package,
    keywords={Adobe Acrobat, JavaScript},
    talksite=http://www.acrotex.net,
    talkdate={January 12, 2007},
    version=1.0,
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL=http://www.acrotex.net
}
\DeclareInitView{layoutmag={navitab=UseAttachments},windowoptions=fit}

\newbox\aebpbox
\newcommand{\cs}[1]{\texttt{\char`\\#1}}
\newcommand\newtopic{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
\vskip\medskipamount\noindent}
%
% As you do not have the necessary background files, the \addWatermarkFromFile
% will silently fail.
\begin{forpaper}
\begin{docassembly}
var pos=this.path.indexOf(this.documentFileName,"/");
var myPath=this.path.substring(0,pos);
try {
\addWatermarkFromFile({
    bOnTop:false,
    cDIPath:myPath+"\pthToExtras/Manual_BG_Print_AeB.pdf"
}); } catch(e) { console.println(e.toString()) };
try {
    \importSound({cName: "StarTrek", cDIPath: "\pthToExtras/trek.wav" });
} catch(e) { console.println(e.toString()) };
try {
    \importIcon({cName: "logo", cDIPath: "\pthToExtras/AeB_Logo.pdf"});
    \importIcon({cName: "logopush", cDIPath: "\pthToExtras/AeB_Logo_bw15.pdf"});
    \importIcon({cName: "logorollover", cDIPath: "\pthToExtras/AeB_Logo_bw50.pdf"});
    var f = this.getField("cheesySound");
    f.buttonPosition = position.iconOnly;
    var oIcon = this.getIcon("logo");
    f.buttonSetIcon(oIcon,0);
    oIcon = this.getIcon("logopush");
    f.buttonSetIcon(oIcon,1);
    oIcon = this.getIcon("logorollover");
    f.buttonSetIcon(oIcon,2);
} catch(e) { console.println(e.toString()) };
try {
  \importDataObject({cName: "AeBProEx2",cDIPath: "aebpro_ex2.pdf"});
  this.getDataObject("AeBProEx2").description="AeB Pro Example #2";
} catch(e){}
\end{docassembly}
\end{forpaper}
\begin{forscreen}
\begin{docassembly}
var pos=this.path.indexOf(this.documentFileName);
var myPath=this.path.substring(0,pos);
try {
    \addWatermarkFromFile({
        bOnTop:false,
        cDIPath:myPath+"\pthToExtras/Manual_BG_DesignV_AeB.pdf"
    });
} catch(e) { console.println(e.toString()) };
try {
    \importSound({cName: "StarTrek", cDIPath: "\pthToExtras/trek.wav" });
} catch(e) { console.println(e.toString()) };
try {
    \importIcon({cName: "logo", cDIPath: "\pthToExtras/AeB_Logo.pdf"});
    \importIcon({cName: "logopush", cDIPath: "\pthToExtras/AeB_Logo_bw15.pdf"});
    \importIcon({cName: "logorollover", cDIPath: "\pthToExtras/AeB_Logo_bw50.pdf"});
    var f = this.getField("cheesySound");
    f.buttonPosition = position.iconOnly;
    var oIcon = this.getIcon("logo");
    f.buttonSetIcon(oIcon,0);
    oIcon = this.getIcon("logopush");
    f.buttonSetIcon(oIcon,1);
    oIcon = this.getIcon("logorollover");
    f.buttonSetIcon(oIcon,2);
} catch(e) { console.println(e.toString()) };
try {
  \importDataObject({cName: "AeBProEx2",cDIPath: "aebpro_ex2.pdf"});
  this.getDataObject("AeBProEx2").description="AeB Pro Example #2";
} catch(e){}
\end{docassembly}
\end{forscreen}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

AeB Pro has two options for attaching files to the source PDF. The
approach is the \texttt{import\-Data\-Object} JavaScript method in
conjunction with the FDF techniques.

Also in this sample file, doc assembly techniques are also
demonstrated.\footnote{The attachments feature uses doc assembly
methods, but simplified for user convenience.}

\section{Attaching Files with AeB Pro}

There are two options for attaching files
\begin{enumerate}
    \item \texttt{attachsource} is a simplified option for attaching
    any file of the form \cs{jobname.}\texttt{\textsl{ext}}.

    \item \texttt{attachments} is a general option for attaching a
    file, as specified by its absolute or relative path.
\end{enumerate}

\subsection{The \texttt{attachsource} option}

Use this option to attach a file with the same base name as \cs{jobname}.

\begin{Verbatim}
    \usepackage[%
        driver=dvips,
        web={pro,usesf,...},
        attachsource={tex,dvi,log,tex.log},
        ...
    ]{aeb_pro}
\end{Verbatim}
Simply list the extensions you wish to attach to the current
document. In the example above, we attach the original source file
\cs{jobname.tex}, \cs{jobname.dvi},  \cs{jobname.log} (the distiller
log) and \cs{jobname.tex.log} (the tex log).


\newtopic One problem with attaching the log file is that the distiller also
produces a log file with the same name \cs{jobname.log}.
Consequently, the log file for the tex file is overwritten by the
distiller log file. You'll see from the PDF document, that the log
file attached is the one for the distiller.

A work around for this is to latex your file, rename the
log file to another extension, such as \cs{jobname.tex.log}, then
distill.

\subsection{The \texttt{attachments} option}

The \texttt{attachments} key is for attaching files other than ones
associated with the source file. The value of this key is a
comma-delimited list (enclosed in braces) of absolute paths and/or
relative paths to the file required to attach. For example,

\begin{Verbatim}
\usepackage[%
    driver=dvips,
    web={pro,usesf,...},
    attachments={extras.zip.txt,\pthToExtras/robot_man.pdf,
    /C/Documents and Settings/dps/My Documents/My Pictures/birthday17.jpg},
    ...
]{aeb_pro}
\end{Verbatim}
The first and second references are relative to the folder containing this
source file, and third one is an example of an absolute path
(picture not attached).

\newtopic There are some files that Acrobat does not attach, but
there is no public list of these. One finds them by discovery,
\texttt{.exe} and \texttt{.zip} files, for example.

A trick that I use to send \texttt{.zip} files through the email
(they are often stripped away by mail servers) is to \emph{hide} the
\texttt{.zip} file in a PDF as an attachment. But since Acrobat does
not attach \texttt{.zip}, I change the extension from \texttt{.zip}
to \texttt{zip.txt}, then inform the recipient to save the
\texttt{zip.txt} file and change the extension back to \texttt{.zip}.
Swave!

\section{Doc Assembly}

Ahhhh, document assembly. What can be said? This is a method that I
have used for many years and is incorporated into the
\textsf{insdljs} package under the name of \texttt{execJS}. Whereas
the \texttt{execJS} environment is still available to you, I've
simplified things.  The term doc assembly refers to the use of the
\texttt{docassembly} environment (which is just an \texttt{execJS}
environment).

The \texttt{execJS}/\texttt{docassembly} environments create an FDF
file with the various JavaScript commands that were contained in the
body of the environment. These environments also place in open page
action so that when the PDF is opened for the first time in Acrobat
Pro, the FDF file will be imported and the JS will be executed one
time and then discarded, see \cite{TUG:execJS} for an article on this topic.
This technique only works if you have Acrobat Pro.

In addition to the \texttt{docassembly} environment, AeB Pro also
has several macros that expand to JavaScript methods that I find
useful. These are
\begin{enumerate}
    \item \cs{addWatermarkFromFile}: inserts a background into the PDF

    \item \cs{importIcon}: imports icon files\footnote{The
    AcroMemory package uses these environments and functions to
    import icons.}

    \item \cs{importSound}: imports a sound file

    \item \cs{appopenDoc}: opens a document

    \item \cs{insertPages}: inserts pages into the PDF, useful for
    inserting pages of difference sizes, such as tables or figures,
    into a {\LaTeX} document which requires that all page be of a
    fixed size.

    \item \cs{importDataObject}: Attaches a file to the PDF. This
    function is used in the two attachments options of AeB Pro.
\end{enumerate}
See the AeB Pro documentation for details.  Here, in this demo file,
I present the code in the preamble of this document:
\begin{Verbatim}
var pos=this.path.indexOf(this.documentFileName);
var myPath=this.path.substring(0,pos);
\begin{docassembly}
\addWatermarkFromFile({
    bOnTop:false,
    cDIPath:myPath+"\pthToExtras/Manual_BG_Print_AeB.pdf"
});
\end{docassembly}
\end{Verbatim}
It is \emph{very important} to note that the arguments for this
(pseudo-JS method) are enclosed in matching parentheses/braces
combination, i.e., \verb!({!\dots\verb!})!. The arguments are
key-value pairs separated by a colon, and the parameters themselves
are separated by commas. (The argument is actually an
object-literal).  It is \emph{extremely important} to have the left
parenthesis/brace pair, \verb!({!, immediately follow the function
name. This is because the environment is a partial-verbatim
environment: \verb!\! is still the escape, but left and right braces
have been ``sanitized''.  The commands, like
\cs{addWatermarkFromFile} first gobble up the next two tokens, and
re-inserts \verb!({! in a different location. (See the
\textsf{aeb\_pro.dtx} for the definitions.)

For another cheesy demonstration, let's import a sound, associate it
with a button. I leave it to you to press the button at your
discretion.
\begin{center}%\previewOn
\setbox\aebpbox=\hbox{\includegraphics[height=16bp]{\pthToExtras/AeB_Logo.eps}}
\newtopic\pushButton[\S{S}\W{0}\A{\JS{%
    var s = this.getSound("StarTrek");\r
    s.play();
}}]{cheesySound}{\wd\aebpbox}{\ht\aebpbox}
\end{center}

\begin{Verbatim}
\begin{docassembly}
try {
    \addWatermarkFromFile({
        bOnTop:false,
        cDIPath:myPath+"\pthToExtras/Manual_BG_DesignV_AeB.pdf"
    });
} catch(e) { console.println(e.toString()) };
try {
    \importSound({cName: "StarTrek", cDIPath: "\pthToExtras/trek.wav" });
} catch(e) { console.println(e.toString()) };
\end{docassembly}
\end{Verbatim}
Above is the full verbatim listing of the \texttt{docassembly}
environment that will execute for the screen. You'll note the
\cs{importSound} command, which imports the sound file
\texttt{trek.wav}. I've also enclosed the individual commands in a
\texttt{try/catch} construct. Doing so is very useful for debugging
the script.

One last little demonstration of the doc assembly methods. In the
preamble, I've imported a few AeB logos (forgive me) and placed them
as appearance faces for the button above. Below is a listing of the
code, with some comments added.

\begin{Verbatim}[fontsize=\small]
\begin{docassembly}
...
...
// Import the sounds into the document
\importIcon({cName: "logo", cDIPath: "\pthToExtras/AeB_Logo.pdf"});
\importIcon({cName: "logopush", cDIPath: "\pthToExtras/AeB_Logo_bw15.pdf"});
\importIcon({cName: "logorollover", cDIPath: "\pthToExtras/AeB_Logo_bw50.pdf"});
var f = this.getField("cheesySound");    // get the field object of the button
f.buttonPosition = position.iconOnly;    // set it to receive icon appearances
var oIcon = this.getIcon("logo");        // get the "logo" icon
f.buttonSetIcon(oIcon,0);                // assign it as the default appearance
oIcon = this.getIcon("logopush");        // get the "logopush" icon
f.buttonSetIcon(oIcon,1);                // assign it as the down appearance
oIcon = this.getIcon("logorollover");    // get the "logorollover" icon
f.buttonSetIcon(oIcon,2);                // assign it as the rollover appearance
\end{docassembly}
\end{Verbatim}
The result is the button you see above.

\newtopic As a final example of \texttt{docassembly} usage, rather
than using the attachments options of AeB Pro, you can also attach
your own files using the \texttt{docassembly} environment.
\begin{Verbatim}[fontsize=\small]
\begin{docassembly}
...
...
try {
  \importDataObject({cName: "AeBProEx2",cDIPath: "aebpro_ex2.pdf"});
  this.getDataObject("AeBProEx2").description="AeB Pro Example #2";
} catch(e){}
\end{docassembly}
\end{Verbatim}
The attachments options automatically assign names. These names appear in the Description column of the attachments
tab of Acrobat/Reader.  For file attached using the \texttt{attachsource}, the base name plus extension is used, for
the files specified by the \texttt{attachments} key, the names are given sequentially, \texttt{"AeB Attachment 1"},
\texttt{"AeB Attachment 2"} and so on. When you roll your own, the description can be more aptly chosen.

\newtopic I have found many uses for the \texttt{execJS}
environment, or the simplified \texttt{docassembly} environment.
You are only limited by your imagination, and knowledge of
JavaScript for Acrobat.


\newpage
\markright{References}

\begin{thebibliography}{[1]}\label{references}
\addcontentsline{toc}{section}{\protect\numberline{}References}

\bibitem{TUG:execJS} ``\texttt{execJS}: A new technique for introducing discardable
JavaScript into a PDF from a \LaTeX{} source,'' TUG\textsc{boat}, The
Communications of the \TeX{} User Group, Vol.~22, No.~4, pp.\
265-268 (2001).

\end{thebibliography}



\end{document}

\importDataObject({cName: "\myEmbeddedFile",cDIPath: "aebpro_ex2.pdf"});