diff options
Diffstat (limited to 'texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex')
-rw-r--r-- | texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex | 469 |
1 files changed, 469 insertions, 0 deletions
diff --git a/texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex b/texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex new file mode 100644 index 00000000..f155d89b --- /dev/null +++ b/texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex @@ -0,0 +1,469 @@ +% 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} |