% 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"});
