summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2017-07-13 10:25:48 +0900
committerNorbert Preining <norbert@preining.info>2017-07-13 10:25:48 +0900
commitcfe306ba1b7ec40855a300580b7981845d56edeb (patch)
treee2feaf2adf8a8afe43a995528097913793874d01 /texmf-dist/doc/latex/aeb-pro/examples/aebpro_ex5.tex
parent32d0671418a3cc6ad0465b06539ed54d96f77784 (diff)
add aeb-mlink aeb-pro aebxmp graphicxsp annot-pro
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.tex469
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}