aebpro_ex5.tex

It uses latex to give question papers

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 >
GoTo > Previous Document} or by using the keyboard shortcut of
\texttt{Shift+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 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\_ex3.pdf}: Launch
and view this PDF. The code is
\begin{verbatim}
\ahyperextract[launch=view]{cooltarget}{aebpro\_ex3.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}