summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex')
-rw-r--r--texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex144
1 files changed, 97 insertions, 47 deletions
diff --git a/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
index 167bc0ea..e67994fb 100644
--- a/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
+++ b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
@@ -63,7 +63,7 @@
email={dpstory@acrotex.net},
subject={Documentation for annot\textunderscore pro from AcroTeX},
talksite={\url{www.acrotex.net}},
- version={1.1b, 2016/10/18},
+ version={1.2, 2018/04/26},
keywords={sticky notes, stamps, file attachment text box, free text, annotations},
copyrightStatus=True,
copyrightNotice={Copyright (C) \the\year, D. P. Story},
@@ -164,6 +164,13 @@ _path=_path.substring(0,pos)+"/"+manualfilename;
\tableofcontents
\selectColors{linkColor=webgreen}
+% New
+% X internalID
+% margprior
+% X hidden
+% X \currentAnnotName
+% annotpro*
+
\section{Introduction}
This package is used to create text, stamp, and file attachment
@@ -175,6 +182,11 @@ The package primarily in support of my \href{http://www.math.uakron.edu/~dpstory
{{Acro\negthinspace\TeX} PDF Blog}. I plan to use sticky notes, file attachments, and
custom stamps to make side-comments, and to provide source files.
+\section{Alternate package name: \texorpdfstring{\protect\pkg{annot-pro}}{annot-pro}}
+
+CTAN lists this package as \pkg{annot-pro}, so might as well have such a package by that name:
+\pkg{annot-pro} loads \pkg{annot\_pro} with the specified options.
+
\section{Requirements}
The requirements for your {\LaTeX} system, and well as any other
@@ -284,25 +296,31 @@ right in the \texttt{AllowPSFileOps} row to select Yes as the value.
The main command of this package is \Com{annotpro}; the command is controlled by
its optional parameters. The same command can create a text annotation (sticky note),
a stamp annotation, a file attachment or a Free Text (Text Box) annotation. The syntax of this command is
-\bVerb\takeMeasure{\string\annotpro[\ameta{KV-pairs}]\darg{\ameta{text}}}%
+\bVerb\takeMeasure{\string\annotpro*[\ameta{KV-pairs}]\darg{\ameta{text}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
-\annotpro[!ameta(KV-pairs)]{!ameta(text)}
+\annotpro*[!ameta(KV-pairs)]{!ameta(text)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproCmd}
\end{minipage}\end{minipage}\eVerb
-\PD The optional argument is one or more key-value pairs that describe the
-annotation; the required argument, \ameta{text}, is the ``contents'' of the
-annotation; for the text and stamp annotation, \ameta{text} becomes the
-contents of the popup annotation, for a file attachment annotation, which has
-not associated pop-up, it is the description of the file attachment that
-appears in the file attachment panel of Adobe Reader. In the latter case, the
-value of \ameta{text} should be rather short. The key-value pairs (\ameta{KV-pairs}) are
-described over the next few sections.
+\PD The optional argument consists is one or more key-value pairs
+(\ameta{KV-pairs}) that describe the annotation; the required argument,
+\ameta{text}, is the ``contents'' of the annotation; for the text and stamp
+annotation, \ameta{text} becomes the contents of the popup annotation, for a
+file attachment annotation, which has no associated pop-up, it is the
+description of the file attachment that appears in the file attachment panel
+of Adobe Reader. In the latter case, the value of \ameta{text} should be
+rather short. The key-value pairs (\ameta{KV-pairs}) are described over the
+next few sections.
+
+Normally, \cs{annotpro} uses the \cs{setkeys} command of \pkg{xkeyval} to
+determine the options specified, when the star-option is specified, \cs{annotpro}
+uses \cs{setkeys*} to evaluate the options, refer to the \pkg{xkeyval} documentation
+for a description of \cs{setkeys} and \cs{setkeys*}.
\paragraph*{\color{red}Sample files.} The sample files \texttt{annots.tex} and \texttt{textbox.tex} illustrate the features
of the \pkg{annotpro} package.
@@ -332,38 +350,69 @@ The following are key-value pairs common to all annotations.
\end{Verbatim}
\item \texttt{color}: The color of the title bar of the pop-up window of the annotation.
\item \texttt{readonly=\ameta{\upshape{true|false}}} Set the annotation to readonly. The user can click on the annot to
- see the popup, but the user, if using Acrobat, cannot move the annotation around on the page.
- The popup window can still be move by the user. (This property makes no difference to the
- user of Adobe Reader.)
+ see the popup, but the user, if using \app{Acrobat}, cannot move the annotation around on the page.
+ The popup window can still be moved by the user. (\texttt{readonly} is the same as \texttt{readonly=true}.)
+ \item \texttt{hidden=\ameta{\upshape{true|false}}} This key sets the annotation to hidden, it is not visible
+ and does not interact with the user. (\texttt{hidden} is the same as \texttt{hidden=true}.)
\item \texttt{opacity=\ameta{dec}}: The opacity value ($
\text0\le\text{\ameta{dec}}\le\text1$) to be used in painting the (icon of
the) annotation, but does apply to the pop-up window. The default
is 1.0.
\item[] Adobe Distiller handles the opacity for us in all cases except when we create a (dynamic) stamp.
If an opacity value less than 1 is desired, special techniques are needed, and the file needs to
- be distilled using the \textbf{Standard\_tranparency} job options.
-
+ be distilled using the \textbf{Standard\_transparency} job options.
+ \item \texttt{internalID=\ameta{name}} Each annot must have an internal
+ name (or ID), \emph{unique to the page on which it appears}. The
+ \pkg{annot\_pro} package maintains an internal counter
+ (\cs{ap@annot@cnt}) and routinely assigns each annotation an internal
+ name (or ID) of
+ \begin{quote}\ttfamily
+ annotpro\string\the\string\ap@annot@cnt
+ \end{quote}
+ The \opt{internamID} key allows you to assign an alternate internal
+ name. Thus, if you assign \texttt{internalID=myCoolAnnot}, an
+ annotation is created with the name \texttt{myCoolAnnot}. The
+ internal ID can be used by JavaScript to find a particular annot on
+ the page and to get its properties. The macro \cs{currentAnnotName}
+ contains the internal name of the most recent annot created.
\end{itemize}
-The following key-values are {\LaTeX} based concerning placement of the annotation in the margin.
+The following key-values are {\LaTeX} based concerning placement of the
+annotation in the margin.
\begin{itemize}
- \item \texttt{margin}: Use this key (it has no value), to declare that you want the annotation
- to appear in the margin. The \cs{marginpar} command from core {\LaTeX} is used, the placement
- of the annotation follows the rules set down by {\LaTeX}. You can reverse the placement of the
- annotation by using the {\LaTeX} command \cs{reversemarginpar} (annots placed in the right margin, and now placed in the left);
- you can return to the default by using \cs{normalmarginpar}.
-
- \item[] Given that you have use the \texttt{margin} key, there is an associated key that can be used, as well
- as a command.
+ \item \texttt{margin}: Use this key (it has no value), to declare that
+ you want the annotation to appear in the margin. The \cs{marginpar}
+ command from core {\LaTeX} is used, the placement of the annotation
+ follows the rules set down by {\LaTeX}. You can reverse the
+ placement of the annotation by using the {\LaTeX} command
+ \cs{reversemarginpar} (annots placed in the right margin, and now
+ placed in the left); you can return to the default by using
+ \cs{normalmarginpar}.
+
+ \item[] Given that you have use the \texttt{margin} key, there is an
+ associated key that can be used, as well as a command.
\begin{itemize}
- \item \texttt{margintext}: The value of this key is text that will be typeset just below the annotation icon.
- \item \cs{marginpartextformat}: A {\LaTeX} command for
- formatting the text in the margin, the default definition is\smallskip
+ \item \texttt{margintext}: The value of this key is text that
+ will be typeset just below the annotation icon.
+ \item \cs{marginpartextformat}: A {\LaTeX} command for formatting
+ the text in the margin, the default definition is\smallskip
\begin{Verbatim}
\margintextformat{\bfseries\tiny\color{blue}}
\end{Verbatim}
\end{itemize}
- \item[] For an annotation placed in the margin with margin text, you might want to use the \texttt{readonly}
- key, this prevents the user---even one using Acrobat---from moving the annotation away from its caption.
+ \item[] For an annotation placed in the margin with margin text, you
+ might want to use the \texttt{readonly} key, this prevents the
+ user---even one using Acrobat---from moving the annotation away
+ from its caption.
+ \item \texttt{margprior=\ameta{\cs{cmd}}} This key allows you to
+ operate on the annotation as a whole. The value \ameta{\cs{cmd}} is
+ expected to be, but it is not a requirement, a command taking one
+ argument. (This key-value pair defines \cs{anp@margprior} which
+ expands to \ameta{\cs{cmd}}; placement of \cs{anp@margprior} is
+ \texttt{\cs{anp@margprior}\darg{\meta{the-annot-code}}}. For
+ example, declaring \texttt{marprior=\cs{fbox}} draws an frame box
+ around the annotation, or
+ \texttt{marprior=\cs{raisebox\darg{10pt}}} raises the annotation
+ 10pt.
\end{itemize}
The following key-value is for your convenience.
\begin{itemize}
@@ -494,7 +543,7 @@ The following are the key-values associated with this annotation type.
\texttt{stamps.pdf}), the width and height are not known to
\textsf{annot\_pro}. In this case, use the \texttt{height} and \texttt{width} keys
to set the dimensions of the bounding box. Adobe Distiller will
- resize the stamp to the stamp is the largest one that can fit in
+ resize the stamp to the stamp that is the largest one that can fit in
the bounding box, the stamp will be centered vertically and
horizontally within the bounding box.
@@ -713,7 +762,9 @@ The required second argument is empty, which leads to an empty \uif{Text Box}.
A much more interesting exercise is to pre-populate the \uif{Text Box} with rich text for the
document consumer to read and/or to respond.
-\paragraph[Steps to create rich text content]{Steps to create rich text content.}\chgCurrLblName{Steps to create rich text content}\label{para:StepsRC}
+%[Steps to create rich text content]
+
+\paragraph{Steps to create rich text content.}\label{para:StepsRC}
We briefly outline the techniques to create rich text
for a \uif{Text Box} annotation.
\begin{itemize}
@@ -785,7 +836,7 @@ This default style is assignment a name that is used as the value of the
Once the \cs{rtpara}-declared paragraphs have been made and their names have passed through
\cs{setRVVContent}, you are ready to create a \uif{Text Box} annotation.
-\paragraph[Key-values for second argument]{Key-values for second argument.}\chgCurrLblName{Key-values for second argument}\label{para:KV2ndArg}
+\paragraph[Key-values for second argument]{Key-values for second argument.}\label{para:KV2ndArg}
The required second argument, refer to display~\eqref{display:textbox}, has
two keys, both of which are optional. You are encouraged to read the
documentation for the \pkg{richtext} package for greater understanding of the
@@ -867,8 +918,7 @@ result, features listed in the \uif{Paragraph} and \uif{Link} tabs of the
\uif{Text Box}.
\paragraph[Keys \& commands inherited from the \texorpdfstring{\protect\pkg{richtext}}{richtext} package]%
-{Keys \& commands inherited from the \pkg{richtext} package.}%
-\chgCurrLblName{Keys \& commands inherited from the \pkg{richtext} package}\label{para:InheritedKeys}
+{Keys \& commands inherited from the \pkg{richtext} package.}\label{para:InheritedKeys}
The following keys are supported by the \uif{Text Box} annotation:
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}[c]{4in}
@@ -897,17 +947,18 @@ not within an \uif{Text Box}. Refer to the documentation of the
\pkg{richtext} for details of these keys and commands. In this document, we
illustrate by example.
-\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{Key-values of \cs{rtpara}.}%
-\chgCurrLblName{Key-values of \cs{rtpara}}\label{para:KeysPara} The
-keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones -- may be used in the
-\ameta{KV-pairs} argument of \cs{rtpara} of display~\eqref{display:rtpara}.
+
+\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{%
+Key-values of \cs{rtpara}.}\label{para:KeysPara}
+The keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones
+-- may be used in the \ameta{KV-pairs} argument of \cs{rtpara} of
+display~\eqref{display:rtpara}.
\paragraph[Permissible commands within \texorpdfstring{\protect\ameta{rich-content}}{<rich-content>}]{%
-Permissible commands within \ameta{rich-content}.}\chgCurrLblName{Permissible
-commands within \ameta{\ameta{rich-content}}}\label{para:KeysCmdsRC} The
-\ameta{rich-content} argument of display~\eqref{display:rtpara} (normally)
-consists of Latin 1 characters, plus any markup in the form of the commands
-listed in display~\eqref{display:suppCmds}.
+Permissible commands within \ameta{rich-content}.}\label{para:KeysCmdsRC}
+The \ameta{rich-content} argument of display~\eqref{display:rtpara}
+(normally) consists of Latin 1 characters, plus any markup in the form of the
+commands listed in display~\eqref{display:suppCmds}.
\begin{itemize}
\item \cs{span} has two arguments, more on this command in the paragraph below
titled \Nameref{para:Span}.
@@ -944,7 +995,7 @@ The above markups, with the exception of \cs{span} are illustrated below.
The verbatim listing for this example is in the sticky note in the margin.
\paragraph[Some comments on the \texorpdfstring{\protect\cs{span}}{\textbackslash{span}}
-command]{Some comments on the \cs{span} command.}\chgCurrLblName{Some comments on the \cs{span} command}\label{para:Span}
+command]{Some comments on the \cs{span} command.}\label{para:Span}
the \cs{span} command, defined only locally within the \ameta{rich-text} argument \cs{rtspan} is a general purpose
command to format text. It has two argument:
\begin{quote}
@@ -981,8 +1032,7 @@ There are several styles of underlining \span{ulstyle=ul}{basic underlining},
The verbatim listing for this example is in the sticky note in the margin.
\paragraph[Key-values of \texorpdfstring{\protect\cs{setDefaultStyle}}{\textbackslash{setDefaultStyle}}]%
-{Key-values of \cs{setDefaultStyle}.}%
-\chgCurrLblName{Key-values of \cs{setDefaultStyle}}\label{para:KeysDS} The
+{Key-values of \cs{setDefaultStyle}.}\label{para:KeysDS} The
keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones --
may be used in the \ameta{KV-pairs} argument of \cs{setDefaultStyle} of
display~\eqref{display:setDefStyle}; however, only the keys \opt{font},