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