% Acrobat required
% use useacrobat option with pdftex and xetex if you have acrobat
% ----------------
%
% Instructions for compiling this file
%   1. Compile this file once, but do not make into a PDF yet.
%   2. Open the two files children/target1.tex and children/target2.tex
%      and compile these two files several times to resolve the cross-
%      references. Now, make into PDFs.
%   3. Return to this file and compile again to input cross-reference info
%      and make into a PDF via distiller.
%
\documentclass{article}
\usepackage{xr-hyper}
\usepackage[%
%    driver=dvips,
    gopro,
    web={designiv,usesf,tight},
    attachsource={tex,dvi},
    attachments={%
        children/target1.pdf,%      % AeB Attachment #1
        children/target2.pdf,%      % AeB Attachment #2
        ../extras/aest.xls          % AeB Attachment #3
    },
    linktoattachments,
    eforms
]{aeb_pro}

\externaldocument[target1-]{children/target1}

\DeclareDocInfo
{
    title=The AeB Pro Package\texorpdfstring{\\[1ex]}{: }Linking to Attachments,
    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},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL=http://www.acrotex.net
}
\talkdateLabel{Published:}

\newcommand{\cs}[1]{\texttt{\char`\\#1}}
\newcommand\newtopic{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
\par\vskip6pt\noindent}
\def\aftersverbskip{\noindent}
\newenvironment{sverbatim}
{\par\small\verbatim}
{\endverbatim\par\aftergroup\aftersverbskip}
\newenvironment{ssverbatim}
{\par\footnotesize\verbatim}
{\endverbatim\par\aftergroup\aftersverbskip}
\def\AcroTeX{Acro\negthinspace\TeX}

%\autolabelNum{AeST}{3}
%\autolabelNum{cooltarget}{3}
%\autolabelNum{attach1}{1}
%\autolabelNum{attach2}{2}
%
% \autolabelNum[mytarget]{1}
% \autolabelNum*[mytarget]{1}{New Title}
% \autolabelNum*[AeST]{3}{\u0022$|e^\u007B\u005Cln(17)\u007D|$\u0022 beep}
% \labelName{cooltarget}{\u0022$|e^\u007B\u005Cln(17)\u007D|$\u0022}
\begin{attachmentNames}
\autolabelNum{1}
%\autolabelNum{2}
\autolabelNum*{2}{target2.pdf Attachment File}
\autolabelNum*[AeST]{3}{AeBST Components}
\labelName{cooltarget}{My (cool) $|x^3|$ ~ % '<attachment>'}
\end{attachmentNames}
% The use of \importDataObject should occur after the \texttt{attachmentNames} environment.
%\def\u{\string\\u}%
\begin{docassembly}
var retn=\importDataObject({cName: "cooltarget",cDIPath: "aebpro_ex2.pdf"});
if ( (app.viewerVersion>7) && retn )
    this.getDataObject("cooltarget").description="\aref(cooltarget)";
\end{docassembly}

\def\preseti{bordercolor={0 0 1},highlight=outline,border=visible,linestyle=dashed,open=new}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

As we saw briefly in \texttt{aebpro\_ex3.tex}, it is possible to
attach a document using the \texttt{docassembly} environment, as
illustrated below,
\begin{sverbatim}
    \begin{docassembly}
    \importDataObject({
        cName: "cooltarget",
        cDIPath: "aebpro_ex2.pdf"
    });
    \end{docassembly}
\end{sverbatim}
In the above, we use \cs{importDataObject}, set the path to be
\texttt{cDIPath: "aebpro\_ex2.pdf"} (this can be absolute or
relative), and give the attachment a name with \texttt{cName:}
\texttt{"\cs{aref(cooltarget)}"}. The special command \cs{aref}, is
used to reference the assigned name has as its argument the label
name, \emph{delimited by parentheses}.

The parameter \texttt{cName} in the above \texttt{docassembly} code
is of particular importance. The value of \texttt{cName} is used in
the names tree for embedded files. It is used to reference the
attachment in the link code.  After the file is imported, the value
of \texttt{cName} is converted by Acrobat to Unicode. When
referencing it, you must know the unicode of the value of the
\texttt{cName} key.

First, we insert into the preamble, the \texttt{linktoattachments} option.
This brings in all the code and commands to be discussed in this document.
(See the preamble of this file.)

\section{Naming Attachments}

For documents attached by the \texttt{attachments} option, AeB Pro
assigns them ``names,'' which appear in the attachments tab of
Acrobat/Reader as the Description.\footnote{The Description is
important as it is the way embedded files are referenced
internally.} The names assigned are \texttt{AeB Attachment 1},
\texttt{AeB Attachment 2}, \texttt{AeB Attachment 3}, and so on.
If you embedded the file using the \texttt{docassem\-bly} environment
and the \cs{importDataObject} method, then you are free to assign a
name of your preference. However it is done, the names must be
converted to unicode on the {\TeX} side of things to set up the
links, and there must be a \LaTeX-like way of referencing this
unicode name, hence the development of the \texttt{attachmentNames}
environment and the two commands \cs{autolabelNum} and
\cs{labelName}.\footnote{It is important to note that
these are not needed unless you are linking to the embedded
files.}

We describe these by example. In the preamble you will find
\begin{sverbatim}
    \begin{attachmentNames}
    \autolabelNum{1}
    \autolabelNum*{2}{target2.pdf Attachment File}
    \autolabelNum*[AeST]{3}{AeBST Components}
    \labelName{cooltarget}{My (cool) $|x^3|$ ~ % '<attachment>'}
    \end{attachmentNames}
\end{sverbatim}
\textbf{\color{red}Note:} The \texttt{attachmentNames} environment
and the commands \cs{autolabel\-Num} and \cs{labelName} should be
used only in the parent document; for child documents they are not
necessary.

\begin{description}

\item[\cs{autolabelNum}:] For PDFs (or other files) embedded using the
\texttt{attachments} option, use the \cs{autolabelNum} command. The
syntax is
\begin{verbatim}
    \autolabelNum[<label>]{<num>}
\end{verbatim}
The first optional argument is the label to be used to refer to this
embedded file; the default is \texttt{attach<num>}. The second
argument is the second is a number, 1, 2, 3.., which
corresponds to the order the file is listed in the value of the
\texttt{attachments} key.\footnote{To minimize the number of changes
to the document, if you later add an attachment, add it to the end
of the list so the earlier declarations are still valid.}

\item[\cs{autolabelNum*}:] There is a star form of \cs{autolabelNum}, which
allows to to change the description of the attachment.
\begin{verbatim}
    \autolabelNum*[<label>]{<num>}{<description>}
\end{verbatim}
By default, the first attachment has label name \texttt{attach<num>}
and has a description of \texttt{AeB Attachment <num>}, This command
allows you not only to change the label, but to change the description
of the attachment as well.

\item[\cs{labelName}:] For files that are embedded in using
\cs{importDataObject}, use the command \cs{labelName} for assigning
the name, and setting up the correspondence between the name and the
label.
\begin{verbatim}
    \labelName{<label>}{<description>}
\end{verbatim}
The first argument is the label to be used to reference this
embedded file.  The second parameter you can assign an arbitrary
name.
\end{description}

\newtopic The \texttt{<description>} parameter used in
\cs{autolabelNum*} and \cs{labelName} can be an arbitrary string
assigned to the description of this embedded file, the characters
can be most anything in the Basic Latin unicode set, 0021--007E,
with the exception of left and right braces \verb!{}!, backslash
\verb!\! and double quotes \texttt{"}. 

You can also enter the unicode character codes directly by typing
\cs{uXXXX} in the \texttt{<description>}, where \texttt{XXXX} are four hex digits. (Did I say not
to use `\verb!\!'?) This is very useful when using the trouble making
characters such as backslash, left and right braces, and double
quotes, or using unicode above 00FF (Basic Latin + Latin-1). To illustrate, suppose we wish
the description of \texttt{cooltarget} to be
\begin{sverbatim}
    "$|e^{\ln(17)}|$"
\end{sverbatim}
All the bad characters!
\begin{sverbatim}
\labelName{cooltarget}{\u0022$|e^\u007B\u005Cln(17)\u007D|$\u0022}
\end{sverbatim}
From the unicode character tables we see that
\begin{itemize}
\item  left brace \cs{u007B}
\item right brace \cs{u007D}
\item backslash \cs{u005C}
\item double quotes \cs{u0022}
\end{itemize}
See the example file \texttt{aebpro\_ex6.tex} for additional examples of the use
of \cs{uXXXX} character codes.

There are several ``helper'' commands as well: \cs{EURO}, \cs{DQUOTE}, \cs{BSLASH},
\cs{LBRACE} and \cs{RBRACE}. When the \cs{u} is detected, an \cs{expandafter} is executed.
This allows a command to appear immediately after the \cs{u}, things work out well if the
command expands to four hex numbers, as it should. Thus, instead of typing
\cs{u0022} you can type \verb!\u\DQUOTE!.

\section{Linking to Embedded Files}\label{embed}

This package defines two commands, \cs{ahyperref} and
\cs{ahyperlink}, to create links between parent and child and child
and child. The default behavior of \cs{ahyperref} (and
\cs{ahyperlink}) is to set up a link from parent to child.
\cs{ahyperlink} and \cs{ahyperref} are identical in all respects
except for how it interprets the destination. (Refer to
\Nameref{jump} for details.)

\newtopic The commands each take three arguments, the
first one of which is optional
\begin{verbatim}
    \ahyperref[<options>]{<target_label>}{<text>}
    \ahyperlink[<options>]{<target_label>}{<text>}
\end{verbatim}
\noindent In the simplest case, we jump from the parent to the first page of a
child file, like so \ahyperref{attach1}{target1.pdf}, given by\dots
\begin{verbatim}
    \ahyperref{attach1}{target1.pdf}
\end{verbatim}
This is the same as \ahyperref[goto=p2c]{attach1}{target1.pdf}, the code is\dots
\begin{verbatim}
    \ahyperref[goto=p2c]{attach1}{target1.pdf}
\end{verbatim}
The \texttt{goto} key is one of the key-value pairs taken by the
optional argument. Permissible values for the \texttt{goto} key are
\texttt{p2c} (the default), \texttt{c2p} (child to parent) and
\texttt{c2c} (child to child).

\newtopic
\fcolorbox{blue}{webyellow}{\parbox{\linewidth-2\fboxsep-2\fboxrule}{\textbf{\textcolor{red}{TIP:}}
After jumping to an attachment you can return to the point of origin
(in the parent document) by selecting the menu item \texttt{View >
Page Navigation > Previous View} or by using the keyboard shortcut of
\texttt{Alt+Left Arrow}}}

\newtopic Similarly, link to the other embedded files in this parent:
\ahyperref{attach2}{target2.pdf} and \ahyperref{cooltarget}{aebpro\_ex2.pdf}

In all cases above, the \cs{ahyperlink} command could have been used, because no
\emph{named} destination was specified, without a named destination, the these links jump to page~1.


\subsection{Jumping to a target}\label{jump}

As you may know, {\LaTeX}, more exactly, \texttt{hyperref} has two
methods of jumping to a target in another document, jump to a label
(defined by \cs{label}) and jump to a target set by
\cs{hypertarget}. Each of these is demonstrated for embedded files
in the next two sections.

\subsubsection{Jumping to a \texorpdfstring{\protect\cs{hypertarget}}{\textbackslash hypertarget}
with \texorpdfstring{\protect\cs{ahyperlink}}{\textbackslash ahyperlink}}

There is a destination defined by the hyperref command
\texttt{hypertarget} in \texttt{target1.pdf} and we shall jump to
it. Here we go! \ahyperlink[dest=mytarget]{attach1}{Jump!}. The
code for this jump is
\begin{verbatim}
    \ahyperlink[dest=mytarget]{attach1}{Jump!}
\end{verbatim}
\noindent Note that \texttt{dest=mytarget}, where ``\texttt{mytarget}'' is the
label assigned by the \cs{hypertarget} command in \texttt{target1.pdf}.

\penalty-5000

\subsubsection{Jumping to a \texorpdfstring{\protect\cs{label}}{\textbackslash label}
with \texorpdfstring{\protect\cs{ahyperref}}{\textbackslash ahyperref}}

{\LaTeX} has a cross-referencing system, to jump to a target set by
the \cs{label} command we use the \textsf{xr-hyper} package that
comes with \texttt{hyperref}. Using label referencing, we can jump to
\ahyperref[dest=target1-s:intro]{attach1}{Section~\ref*{target1-s:intro}}
on page~\pageref*{target1-s:intro} of the embedded file
\texttt{target1.pdf}. Swave! The code for the jump is
\begin{verbatim}
    \ahyperref[dest=target1-s:intro]{attach1}
        {Section~\ref*{target1-s:intro}}
\end{verbatim}
\noindent we set \verb!dest=target1-s:intro!

The label in \texttt{target1.pdf} is \texttt{s:intro}, in the preamble of
this document we have
\begin{verbatim}
    \externaldocument[target1-]{children/target1}
\end{verbatim}
\noindent which causes \textsf{xr-hyper} to append a prefix to the label (this
avoids the possibility of duplication of labels, over multiple
embedded files).

\goodbreak
\subsection{Optional Args of \texorpdfstring{\protect\cs{ahyperref}}{\textbackslash ahyperref}
and \texorpdfstring{\protect\cs{ahyperlink}}{\textbackslash ahpyerlink}}

The \cs{ahyperref} commands has a large number of optional arguments
enabling you to create any link that the user interface of Acrobat
Pro can create, and more. These are documented in
\textsf{aeb\_pro.dtx} and well as the main documentation. Suffice it
to have an example or two.

By using the optional parameters, you can create any link the UI can create:
\ahyperref[dest=target1-s:intro,bordercolor={0 1 0},highlight=outline,%
border=visible,linestyle=dashed]{attach1}{Jump!}
This link is given by\dots
\begin{verbatim}
    \ahyperref[%
        dest=target1-s:intro,
        bordercolor={0 1 0},
        highlight=outline,
        border=visible,
        linestyle=dashed
    ]{attach1}{Jump!}
\end{verbatim}
\noindent Now what do you think of that?

\newtopic The argument list can be quite long, as shown above. If you have some favorite settings, you can
save them in a macro, like so,
\begin{sverbatim}
    \def\preseti{bordercolor={0 0 1},highlight=outline,open=new,%
        border=visible,linestyle=dashed}
\end{sverbatim}
\noindent Then, I can say, more simply, \ahyperref[dest=target1-s:intro,preset=\preseti]{attach1}{Jump!}
This link is given by\dots
\begin{sverbatim}
\ahyperref[dest=target1-s:intro,preset=\preseti]{attach1}{Jump!}
\end{sverbatim}
\noindent I've defined a \texttt{preset} key so you can predefine some common settings you like to use,
the enter these settings through preset key, like so \verb!preset=\preseti!. Cool.

Note that in the second example, I've included \texttt{open=new}, this causes the embedded file to open
in a new window. For Acrobat/Reader operating in MDI, a new child window will open; for SDI (version 8),
and if the user preferences allows it, it will open in its Acrobat/Adobe Reader window.

\newtopic
\fcolorbox{blue}{webyellow}{\parbox{\linewidth-2\fboxsep-2\fboxrule}{\textbf{\textcolor{red}{TIP:}}
After jumping to an attachment that opens a new window, just close the new window to
return the parent document. \texttt{:-\textrm{\{})}}}

\section{Opening and Saving with \texorpdfstring{\protect\cs{ahyperextract}}
    {\textbackslash ahyperextract}}

In addition to embedding and linking a PDF, you can embed most any
file and programmatically (or through the UI) open and/or save it to
the local file system.

To attach a file to the parent PDF, you can use the
\texttt{attachsource} or the \texttt{attachments} options of AeB
Pro, or you can embed your own using the \texttt{importDataObject}
method, as described earlier in this file.

If an embedded file is a PDF, then you can link to it, using
\cs{ahyperref} or \cs{ahyperlink}; we can jump to an embedded PDF
and jump back. If the embedded file is not a PDF, then jumping to it
makes no sense; the best we can do is to open the file (using an
application to display the file) and/or save it to the local hard
drive.

The AeB Pro package has the command \cs{ahyperextract} to extract
the embedded file, and to save it to the local hard drive, with an
option to start the associated application and to display the file.
The syntax for \cs{ahyperextract} is the same as that of the other two commands:
\begin{verbatim}
    \ahyperextract[<options>]{<target_label>}{<text>}
\end{verbatim}
\noindent The \texttt{<options>} are the same as \cs{ahyperref}, the \texttt{<target\_label>} is the one associated
with the attachment name, and the \texttt{<text>} is the link text.

\newtopic In addition to the standard options of \cs{ahyperref}, \cs{ahyperextract} recognizes one additional key, \texttt{launch}.
This key accepts three values: \texttt{save} (the default), \texttt{view} and \texttt{viewnosave}. The following is a
partial verbatim listing of the descriptions given in the \textsl{JavaScript for Acrobat API Reference}, in the section
describing \texttt{importDataObject} method of the Doc object:
\begin{itemize}
    \item \texttt{save}: The file will not be launched after it is saved. The user is prompted for a save path.
    \item \texttt{view}: The file will be saved and then launched.
        Launching will prompt the user with a security alert warning
        if the file is not a PDF file. The user will be prompted for a
        save path.
    \item \texttt{viewnosave}: The file will be temporarily saved and
        then launched. Launching will prompt the user with a security
        alert warning if the file is not a PDF file. A temporary path
        is used, and the user will not be prompted for a save path.
        The temporary file that is created will be deleted by Acrobat
        upon application shutdown.
\end{itemize}

\newtopic Here is a series of examples of usage:
\begin{enumerate}

\item \ahyperextract[launch=view]{cooltarget}{aebpro\_ex2.pdf}: Launch
    and view this PDF. The code is
\begin{verbatim}
\ahyperextract[launch=view]{cooltarget}{aebpro\_ex2.pdf}
\end{verbatim}
When you extract (or open) PDF in this way, any links created
by \cs{ahyperref} or \cs{ahyperlink} as the PDF being viewed is no longer an embedded file of the
parent.

\item View the \ahyperextract[launch=viewnosave]{tex}{aebpro\_ex5.tex}. The code is
\begin{verbatim}
\ahyperextract[launch=viewnosave]{tex}{aebpro\_ex5.tex}
\end{verbatim}
Note that for attachments brought in by the \texttt{attachsource} option,
the label for that attachment is the file extension, in this case
\texttt{tex}.

\item \ahyperextract[launch=save]{AeST}{AeBST Component List}: This is an Excel spreadsheet which lists
the components of the {Acro\negthinspace\TeX} eDucation System
Tools. Here you are prompted to save; the spreadsheet will not be launched:
\begin{verbatim}
\ahyperextract[launch=save]{AeST}{AeBST Component List}
\end{verbatim}
\end{enumerate}

\section{Final Assembly}

To assemble your parent document with all the cross-references to
its embedded children, perform the following steps.
\begin{enumerate}

\item {\LaTeX} the parent document so that the auxiliary file
    \cs{jobname\_xref.cut}. This file is read by the children when they
    are {\LaTeX}ed.

\item {\LaTeX} the child documents. The child documents will write
    their own auxiliary file and read \cs{jobname\_xref.cut}. (Multiple
    compiles may be necessary to bring the auxiliary document up to
    date.)

\item Make PDF for the child documents.

\item Now {\LaTeX} the parent again, which will read in the
    auxiliary files of the children, if needed. Distill and \textsl{Le
    Voil\`{a}}, you have it!

\item At this point you can clean up all auxiliary files.

\end{enumerate}

\end{document}
