path: root/texmf-dist/doc/latex/annot-pro/annotpro_man.tex

%
% http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf
%
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass[12pt]{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,tight*,
        forcolorpaper,latextoc,extended},
        aebxmp,eforms,graphicxsp={showembeds}
]{aeb_pro}
\usepackage{array}
%\usepackage{aeb_mlink}
%\usepackage{myriadpro} %[usecmtt]
\usepackage[altbullet]{lucidbry}
\usepackage[dblevel=0]{annot_pro}
\usepackage{richtext}

\usepackage{xbmks}

\DeclareInitView{layoutmag={navitab:UseOutlines}}
\xbmksetup{colors={int=red},styles={intbf}}

\previewOff

%\DeclareInitView
%{%
%    layoutmag={mag=100},
%%    windowoptions={fit}
%}

%\useAAXdimtrue

\usepackage{makeidx}
\makeindex
\usepackage{acroman}

\usepackage[active]{srcltx}

\def\expath{../examples}

\urlstyle{rm}
\def\pkg{\textsf}
\let\app\textsf
\let\opt\texttt
\let\uif\textsf
\let\env\texttt
\let\key\texttt
\def\meta#1{\textit{\texttt{#1}}}
\def\ameta#1{$\langle\textit{\texttt{#1}}\rangle$}
\newdimen\aebdimen \aebdimen6pt %\partopsep \advance\aebdimen\partopsep
\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}%
\def\eVerb{\vskip\aebdimen\endgroup\noindent}
\def\SUB#1{\ensuremath{{}_{\text{#1}}}}

\def\darg#1{\texttt{\{#1\}}}
\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei}
\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup}
\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule}
\let\amtIndent\leftmargini
\edef\amtIndent{\the\parindent}

%\def\tutpath{doc/tutorial}
%\def\tutpathi{tutorial}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \texorpdfstring{\textsf{annot\_pro} Package\\[1em]}{annot\textunderscore pro Package: }
        Text, Stamp, File Attachment, Text Box, and Text Markup Annotations},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for annot\textunderscore pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.4, 2018/08/13},
    keywords={sticky notes, stamps, file attachment text box, free text, text markup, annotations},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-40pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-20pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\embedEPS[hiresbb,transparencyGroup]{AdobeDon}{../examples/graphics/AdobeDon}

\makeStamp{0.0 0.0 20.0 20.0}{AdobeDon}{%
    [ 20 \widthOf{AdobeDon} div 20 \widthOf{AdobeDon} div scale {AdobeDon} /SP pdfmark
}

\makeatletter
\def\setDisplayNumber#1#2{\kern0pt
    \setlength\abovedisplayshortskip{0pt}%
    \setlength\belowdisplayshortskip{0pt}%
    \setlength\abovedisplayskip{0pt}%
    \setlength\belowdisplayskip{0pt}%
    \begin{equation}\label{#2}\end{equation}\kern0pt
}
\renewenvironment{quote}[1][]
   {\def\@rgi{#1}\ifx\@rgi\@empty
    \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi
    \list{}{\rghtm} %{\rightmargin\leftmargin}%
    \item\relax}
   {\endlist}
\renewcommand*\descriptionlabel[1]{\hspace\labelsep
    \normalfont #1}
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{5}
\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
\renewcommand{\paragraph}
    {\renewcommand{\@seccntformat}[1]{\theparagraph}%
    \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}
\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
\def\echgCurrLblName#1{\edef\@currentlabelname{#1}}
\makeatother


\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}}

%\pagestyle{empty}
%\parindent0pt\parskip\medskipamount

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The annot_pro MANUAL";
var manualfilename="Manual_BG_Print_annotpro.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}
\begin{document}

\maketitle

\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage}
\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},%
  color=magenta,style={bf}]{acrotex}
\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},%
  color=magenta,style={bf}]{home}
\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},%
  color=magenta,style={bf}]{blog}


\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}

This package is used to create text, stamp, and file attachment
annotations using \textbf{Adobe Distiller}, these annotations can be
viewed in Adobe Reader. For users of \textsf{pdf(la)tex}, use the
\textsf{pdfcomment} package by Josef Kleber.\footnote{Available at \href{http://ctan.org/pkg/pdfcomment}{ctan.org/pkg/pdfcomment}}

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
software, is highlighted in this section.

\subsection{{\LaTeX} Package Requirements}

The following packages, in addition to the standard {\LaTeX}
distribution, are required:
\begin{enumerate}
  \item The \textsf{xkeyval} package is used to set up the key-value
      pairs of the \cs{annot\-pro} command. Get a recent version.
  \item The \textsf{xcolor} package is strongly recommended.
  \item The \textsf{hyperref} package, a recent version.
  \item If you want to create custom stamps (on the fly) using the techniques
      developed for that purpose, the \textsf{graphicxsp} Package is required.\footnote
      {Available at \href{http://ctan.org/pkg/graphicxsp}{ctan.org/pkg/graphicxsp}}
  \item \pkg{annot\_pro} now requires \pkg{aeb\_mlink} (2018/08/18 or later) to implement
    text markup annotations. The \pkg{aeb\_mlink} package loads the \pkg{soul} package.
\end{enumerate}
The \textsf{annot\_pro} package is part of the \textcolor{blue}{AeB
Pro} family, which means \textbf{Adobe Distiller} is required. The
components of \textcolor{blue}{AeB} and \textcolor{blue}{AeB Pro}
are not required.\footnote{AeB: \href{http://ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}}${}^{,}$\footnote{AeB Pro:
\href{http://ctan.org/pkg/aeb-pro}{ctan.org/pkg/aeb-pro}}

\subsection{PDF Creator Requirements}

The \textsf{annot\_pro} package requires \textbf{Acrobat Distiller 5.0} (or
later) as the PDF creator. The document author typically uses dvips (or dvipsone) to
produce a PostScript file, which is then distilled to obtain a PDF.

If you wish to use (dynamically) created stamps that have opacity less than 1,
you need to distill using \textbf{Standard\_transparancy.joboptions} with distiller,
in this case, \textbf{Acrobat Distiller 6.0} (or later) is required; otherwise, this
distiller job options file is not needed.

The \textbf{Standard\_transparancy.joboptions} file is supplied with the \textsf{graphicxsp}
package; the documentation of the \textsf{graphicxsp} package includes installation instructions.

\section{Installation}

The installation is simple enough. Unzip \texttt{annot\_pro.zip} in a
folder that is on your {\LaTeX} search path.  Refresh your filename
database, if appropriate.

\begin{defineJS}{\winedtDist}
Run(|"c:\\Program Files\\Adobe\\Acrobat 9.0\\Acrobat\\acrodist.exe" -F "%P\\%N.ps"|,'%P',0,0,'%N.ps - Distiller',1,1);
\end{defineJS}

\paragraph*{\textcolor{red}{Important:}} When creating a file attachment annotation,
you must specify a path to the file to be attached, and distiller must embed
this file.  In recent versions of Acrobat,
security restrictions have been put in place to prevent
\textbf{Distiller} from reading files (the PostScript \textbf{file}
operator does not work). Fortunately, Distiller has a switch that
turns off this particular restriction. To successfully use this
package, therefore, you need to run Distiller by using the
\texttt{-F} command line switch.


Those using \app{Windows OS} can create a shortcut on the desktop, for example,
that starts \app{Distiller} with the \texttt{-F} switch. The \uif{Target} of the shortcut might read
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
"C:\Program Files (x86)\Adobe\
    Acrobat 9.0\Acrobat\acrodist.exe" -F
\end{Verbatim}
where we have wrapped the path to the next line to fit within the margins.
Once \app{Distiller} is started with \texttt{-F}, the switch remains in effect
until \app{Distiller} is closed.

If this package is used to create file attachment annotations without the
\texttt{-F} switch, you typically get the following error message in
the Distiller log file
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
%%[ Error: undefinedfilename; OffendingCommand: file ]%%
\end{Verbatim}
This tells you that either you have not started Distiller with the
\texttt{-F} command line switch, or Distiller can't find one of the
files that the \textbf{file} operator was trying to read.



\newtopic \textbf{Mac OS Users.} The above comments on the \texttt{-F} command line switch
is for Windows users, Mac OS users must choose the \texttt{AllowPSFileOps} user preference, this is located
in the \texttt{plist}, possibly located at
\begin{Verbatim}[fontsize=\small]
/Users/[User]/Library/Preferences/com.adobe.distiller9.plist
\end{Verbatim}
You can also use Spotlight, the search utility on Mac, to search for the string \texttt{com.adobe.distiller};
the result might be
\begin{quote}
\texttt{com.adobe.distiller9.plist}.\footnote{In the case of Adobe Distiller, version 9.0}
\end{quote}
Clicking on this find,
Spotlight opens \texttt{com.adobe.distiller9.plist} in the \texttt{plist} editor, see \hyperref[plist]{Figure~\ref*{plist}}.
If necessary, click on the arrow next to the Root to expand the
choices, then click the up and down arrows at the far
right in the \texttt{AllowPSFileOps} row to select Yes as the value.
\begin{figure}[hbt]\setlength{\fboxsep}{0pt}
\begin{center}
\fbox{\includegraphics[width=.75\linewidth]{plistEditor}}
\caption{com.adobe.distiller9.plist}\label{plist}
\end{center}
\end{figure}

\section{Package Options}\label{pkgOpts}

This package has several options to customize its use.

\begin{itemize}
  \item \opt{preview}: When this option is taken, the bounding rectangles
      are visible in the typeset document. This feature can be locally
      turned on with \cs{previewOn} and off with \cs{previewOff}.
%  \item \opt{useA10Icons} (the default) and \opt{!useA10Icons}: Beginning
%      with version 10 of \app{Acrobat} and \app{Adobe Reader} the
%      dimensions of the icons used changed. If your target audience uses
%      version~10 or later use the \opt{useA10Icons} option; if your target
%      population is using version~9 or prior, use the \opt{!useA10Icons}
%      option. This set of options are outdated, the default option is all
%      that is needed.
  \item \opt{richtext} and \opt{useTextBox}: All annotations supported by
      this package can now take rich text for its contents. If you use rich
      text in your comments, the \opt{richtext} option is required. (The
      \opt{useTextBox} option is deprecated in favor of \opt{richtext}.)
  \item \opt{scandoc} and \opt{!scandoc}: The \opt{scandoc} option is
      needed when using custom stamps; the \opt{!scandoc} turns off
      scanning. The \opt{!scandoc} is a convenience option.
  \item \opt{dblevel=\ameta{num}} Sets the level of information feedback; this option
  is passed to the \pkg{aeb\_mlink} package.
\end{itemize}



\section{The \texorpdfstring{\protect\cs{annotpro}}{\CMD{annotpro}} Command}

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{content}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\annotpro*[!ameta(KV-pairs)]{!ameta(content)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproCmd}
\end{minipage}\end{minipage}\eVerb
\PD The optional argument consists is one or more key-value pairs
(\ameta{KV-pairs}) that describe the annotation; the required argument,
\ameta{content}, is the ``content'' of the annotation; it is either text or a key-value pair.
Use the key-value option to insert rich text content; see Section~\ref{rtContent} on page~\pageref{rtContent} for
more information. For text and stamp annotations, \ameta{content} becomes the content 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 \app{Adobe Reader}. In the latter case, the value of \ameta{content} 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.

\subsection{Key-values common to all annotations}\label{s:CommonKeys}

The following are key-value pairs common to all annotations.

%{$\langle\textit{\texttt{#1}}\rangle$}

\begin{itemize}
  \item \texttt{type=$\langle$\upshape{text|stamp|fileattachment|textbox|highlight|}}\\
        \texttt{underline|squiggly|strikeout$\rangle$} The key determines
        the type of annotation to be produced. The \texttt{type} key is
        optional, if not present, \texttt{type=text} is assumed.
  \item \texttt{name=\ameta{name}} The name of the icon to use for the declared \texttt{type}. Permissible
        values are dependent on the \texttt{type}, and are discussed in subsequent sections.
  \item \texttt{title=\ameta{text}} Text to be displayed in the title bar of the annotation's pop-up window
        when open and active. By convention, this entry identifies the user who made the annotation,
        though any (short) text may be used. You can use \cs{setAnnotOptions} to globally set
        the title of each annotation, perhaps using your name.
\begin{Verbatim}[fontsize=\small]
    \setAnnotOptions{title={D. P. Story}}
\end{Verbatim}
  \item \texttt{subject=\ameta{text}} Text representing a short description of the subject of the annotation.
    You can use \cs{setAnnotOptions} to globally set the subject of each annotation,
\begin{Verbatim}[fontsize=\small]
    \setAnnotOptions{title={D. P. Story},
        subject={AcroTeX Communiqu\'e}}
\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 \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\_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.
\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.
  \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
\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 \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}
  \item \texttt{presets}: A key to allow the introduction of pre-defined options, for example,
    you might like all your comment annotations to be red, so you can define
\begin{verbatim}
   \def\myComments{type=text,name=Comment,color=red}
\end{verbatim}
then say
\begin{verbatim}
   \annotpro[presets=\myComment]{Way to go!}
\end{verbatim}
Additional options may be included,
\begin{verbatim}
   \annotpro[presets=\myComment,margin]{Way to go!}
\end{verbatim}
for example.

\end{itemize}

\subsection{Key-values for text annotations}

The position of the annotation is determined by its bounding rectangle; for the
text annotation, an icon is placed so that its upper left corner is at the upper
left corner of the bounding rectangle. The icons themselves have certain dimensions
that have been recorded within the \texttt{annot\_pro} package, so you need not worry
about leaving space for them.

An important fact about the icons used by text annotation is that they \emph{do not zoom in or out} as the page
magnification is changed; furthermore, the graphics commands \cs{scalebox} and \cs{resizebox} do not rescale
the icons as expected.

The following are options specific to the text annotation. Recall, the text annotation
is of \texttt{type=text}.
\begin{itemize}
    \item \texttt{name}: The name of the icon to use when displaying this annotation in closed form (no pop-up window visible).
    Possible values---as specified in the \textsl{PDF Reference}---are
    \texttt{Comment}, \texttt{Key}, \texttt{Note}, \texttt{Help},
    \texttt{NewParagraph}, \texttt{Paragraph}, and \texttt{Insert}.
    Additional icons that are available in recent versions of Adobe
    Reader are
\begin{quote}\raggedright
    \texttt{Check}, \texttt{Circle}, \texttt{Cross}, \texttt{Star}, \texttt{RightArrow}, \texttt{RightPointer},
    \texttt{UpArrow}, \texttt{UpLeftArrow}
\end{quote}
        If you are using comments in your document, and your audience have
        older versions of Adobe Reader, it is best to use only the seven
        listed in the \textsl{PDF Reference}.

    \item \texttt{open}: A Boolean value that determines whether the pop-up
        window is open or not. When \texttt{true} the pop-up is open. The
        package default is \texttt{false}. You can use \cs{setAnnotOptions}
        to set this option globally.

    \item \texttt{nohspace}, \texttt{novspace}, \texttt{nospace}: The
        presence of these commands zeroes out the dimension(s) of the
        bounding rectangle. Specifying \texttt{nohspace} as an option
        causes the icon to take up no horizontal space as the page is
        latexed. Here\annotpro[nohspace]{This a sticky note with the
        nospace option} is an example of a sticky note with the
        \texttt{nohspace} option. Without any of these three keys, the text
        annotation \annotpro[type=text,name=Key]{A sticky note that takes
        up TeX space. If you put the document into 100\% magnification,
        you'll see the note fits precisely into the allotted space.} fits
        exactly into the allotted space at
        \setLinkText[\A{\JS{this.zoom=100;}}\Color{0 .6 0}]{100\%
        magnification}, try it.

    When the icon takes up no {\TeX} space, it may cover content on
        the page, as it does above. Acrobat users can move the icon
        around, but AR users cannot move the icon. The pop-up window is
        movable and scalable, but the icon cannot be moved. Therefore,
        you must be careful about placement.

    Additional positioning of the icons can be made using standard {\LaTeX}
    commands such as \cs{raisebox} and \cs{smash}. For example,\smash{\raisebox{1in}{\annotpro[nospace,color=blue,opacity=.25]{I've raised this annot by 1in.
    I've also used the nospace key, the icon does not take up any TeX space.}}} the blue icon above was created by
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\footnotesize]
For example,\smash{\raisebox{1in}\raisebox{1in}{%
  \annotpro[nospace,color=blue,
    opacity=.25]{...clever message...}}}
\end{Verbatim}
Note that I've set the \texttt{opacity} to .25.

\end{itemize}


\subsection{Key-values for stamp annotations}

A stamp annotation is similar to a text annotation in the sense that
it has a pop-up window in which the contents of the message is
displayed; however, unlike the text annotation icons, the stamp
appearance by be re-scaled using \cs{scalebox} and \cs{resizebox} of
the graphics package; however, the keys \texttt{scale},
\texttt{widthTo}, and \texttt{heightTo}, as described below, are the
recommended methods of re-scaling a stamp.

The following are the key-values associated with this annotation type.

\begin{itemize}

\begingroup\raggedright

    \item \texttt{name}: The stamps listed in the \textsl{PDF
    Reference} are \texttt{Approved}, \texttt{AsIs},
    \texttt{Confidential}, \texttt{Departmental}, \texttt{Draft},
    \texttt{Experimental}, \texttt{Expired}, \texttt{Final},
    \texttt{ForComment}, \texttt{ForPublicRelease},
    \texttt{NotApproved}, \texttt{NotForPublicRelease},
    \texttt{Sold}, and \texttt{TopSecret}. If \texttt{name}
    is not specified, \texttt{Draft} is the default.\par\endgroup

    \item[] There are other stamps, not listed in the \textsl{PDF
    Reference}, but available in more recent versions of Acrobat.
    The file \texttt{stamps.pdf} lists all the stamps that I have
    access to. The names of these other stamps are recognized by the
    \texttt{name} key.

    \item[] The dimensions of the stamps listed above are all the
    same, they are \texttt{150bp} width and \texttt{40bp} high.

    \item[] Additional stamps are shipped by Acrobat, a listing of these
    appears in the file \texttt{stamps.pdf} (\texttt{stamps.tex}).

    \item\texttt{width}, \texttt{height}: If the value of
    \texttt{name} key is something other than one of the stamps
    listed above (one of the stamps listed in the file
    \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 that is the largest one that can fit in
    the bounding box, the stamp will be centered vertically and
    horizontally within the bounding box.

    \item[] Here are a couple of examples, the bounding box is should as a black \cs{fbox}.

\begin{itemize}

\begin{defineJS}{\annotstampi}
Exact fit:
\\annotpro[type=stamp,name=SBApproved,widthTo=106bp,color=webbrown]{This package just got better!}
\end{defineJS}
\begin{defineJS}{\annotstampii}
Bad rectangle, but stamp fits the best it can:
\\annotpro[type=stamp,name=SBApproved,width=50bp,height=50bp,color=webbrown]{This package just got better!}
\end{defineJS}




        \item This one
            {\previewOn\annotpro[type=stamp,name=SBApproved,widthTo=106bp,color=webbrown]{This
            package just got better!}} fits more or less exactly\annotpro[margin,readonly,margintext={\centering Good Fit}]{\annotstampi}.  I
            determined the dimensions of this stamp through some controls
            of the user interface. Contrast this stamp
            {\previewOn\annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This
            package just got better!}}\annotpro[margin,readonly,margintext={\centering Bad Fit}]{\annotstampii} obtained by setting
            \texttt{width=50bp} and \texttt{height=50bp}. Notice the
            ``best fit,'' and that the bounding box takes up space. We
            can use \cs{smash} to smash its vertical height, let's see
            how that looks
            {\previewOn\smash{\annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This
            package just got better!}}}.

\smallskip


\goodbreak

\previewOff

%        \item[] The code for producing these stamps are given in the margins.
%        \annotpro[margin,readonly,margintext={\centering Good Fit}]{\annotstampi}%
%        \annotpro[margin,readonly,margintext={\centering Bad Fit}]{\annotstampii}%

\begin{defineJS}{\annotstampiii}
Resize using \\resizebox. \\raisebox was used to lift the same up a little:
\\raisebox{4pt}{\\resizebox{.5in}{!}{\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}}
\end{defineJS}

    \item[] You can resize these stamps using \cs{scalebox} and \cs{resizebox}, like so:
    \raisebox{4pt}{\resizebox{.5in}{!}{\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}}.
    %\enspace
    The code for producing this stamp are given here \annotpro{\annotstampiii}.

\begin{defineJS}{\annotstampiv}
\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I give my stamp of approval!}}}
\end{defineJS}

\item To create a
    stamp\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I
    give my stamp of approval!}}} that takes up no space, it is easiest
    to use \cs{smash} and \cs{makebox[0pt][l]\darg{\ameta{contents}}}; here is one of
    the standard stamps as listed in the \textsl{PDF Reference}. The code
    for this stamp is given in this note \annotpro{\annotstampiv}.
\end{itemize}

\item[] Try changing the magnification of the page, you'll see that stamps are re-scaled as you zoom in or out, while
the text annotations are not. I don't like text annotations for this reason.

\begin{defineJS}{\annotstampv}
\\annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This is the best picture of me ever taken. Akron, about 2005.}
\end{defineJS}

\item\texttt{rotate}: Stamps can be rotated, use this key to enter an angle of rotation, for example,
    \texttt{rotate=30} rotates the stamp $\text{30}^\circ$ counter clock-wise.

\item[\textcolor{red}{\ding{043}}] Do not use the \cs{rotatebox} command of \textsf{graphics} package,
this command \emph{does not rotate} the stamp.

\item \texttt{scale}: Use this key to re-scale the stamp; the value of this key is a number between
    0 and 1. For example, \texttt{scale=.5} reduces both width and height in half.
\item \texttt{widthTo}: This key resizes the stamp so that the width is the value of this key; for example,
    \texttt{widthTo=2in} re-scales the stamp to have a 2in width.
\item\texttt{heightTo}: This key resizes the stamp so that the height is the value of this key; for example,
    \texttt{heightTo=2in} re-scales the stamp to have a 2in height.

\item[] Only one of the keys \texttt{scale}, \texttt{widthTo}, and \texttt{heightTo} are recognized
    for any stamp annotation. If all three are specified, only \texttt{scale} is used. If
    \texttt{widthTo} and \texttt{heightTo} are both specified, then \texttt{widthTo} is used.

\item[\textcolor{red}{\ding{043}}] The use of these keys is the recommend way of re-scaling
a stamp. These methods are compatible with the \texttt{rotate} key.

\item \texttt{customStamp}: You can create a custom stamp from any
    image you wish to use, here is
    \annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This
    is the best picture of me ever taken. Akron, about 2005.} one such
    example. The code for the above stamp is given here
    \annotpro{\annotstampv}.

\item \texttt{ap}: When the \texttt{\texttt{customStamp}} key is
    used, you have to supply an indirect reference to the appearance of
    the stamp. This reference is made through the \texttt{ap} key. The
    example above demonstrates the use of the \texttt{ap} key.
\end{itemize}
\textbf{\textcolor{red}{Important:}} When using the stamps of
\app{Acrobat} always perform a \uif{SaveAs} on the file when you have finished
building the file. This imports the appearances of the stamps into
the document and saves them.

\redpoint The creation of a custom stamp requires detailed list of steps, at
some point I'll write a white paper on the subject.\footnote{Use the \pkg{mkstmp} package
(\href{http://ctan.org/pkg/mkstmp}{ctan.org/pkg/mkstmp}),
details of how to create custom stamps are included in the documentation.}

\begin{defineJS}{\approvedStmp}
\\annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{...}
\end{defineJS}

\newtopic
Here's an example of the keys \texttt{rotate} and \texttt{widthTo}:
\begin{center}
            \annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{The source for this
            stamp is ...\string\r\approvedStmp}
\end{center}

\subsection{Key-values file attachment annotations}

The file attachment annotation has no pop-up window, the value of the required parameter is used as a description
of the attached file, and appears in the file attachment window.

The key-value pairs special to this type of annotation are as follows.

\begin{itemize}
    \item\texttt{name}: The name of the icon to use, permitted values are
    \texttt{Graph}, \texttt{Paperclip}, \texttt{PushPin}, and \texttt{Tag}. If the value of name is not
    specified, the default is \texttt{PushPin}. The annot\_pro package knows the dimensions of each of these
    icons, so you need not worry about them. They can be re-scale using standard commands from the graphics package,
    though, there may be little need of doing so.
    \item \texttt{file}: The value of the file key is the \emph{absolute path} to the file to be attached. I've
    devised a helper command \Com{defineAPath} that can be used to define the path to your file. For example, we can
    define a path to wherever the files are, like so
\begin{Verbatim}[fontsize=\footnotesize]
  \defineAPath{\graphicsPath}
    {C:/Users/Public/Documents/My TeX Files/%
        tex/latex/aeb/aebpro/annot_pro/examples/graphics}
\end{Verbatim}
\item[] The command takes two arguments, the name of the command to be defined, and the path.

\defineAPath{\graphicsPath}{C:/Users/Public/Documents/My TeX Files/tex/latex/aeb/aebpro/annot_pro/examples/graphics}

\begin{defineJS}{\fa}
\\annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The author of annot\_pro (ho, ho).}
\end{defineJS}

\item[] We can create a file attachment
    \annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The
    author of annot\_pro (ho, ho).} like so, ho, ho. Here is the code
    for this file attachment \annotpro[name=Star]{\fa}. Clicking the
    file attachment icon will open the file, in recent versions of
    Acrobat, the file is listed in the file attachments panel. Open it
    using the user interface, and you'll see the file listed, as well
    as a description, as passed to the annot as the second argument of
    \cs{annotpro}.
\end{itemize}

The file attachment icons can be resized using any of the graphics commands, \cs{scalebox} or \cs{resizebox}.

\subsection{The \texorpdfstring{\protect\uif{Text Box}}{Text Box}
    (\texorpdfstring{\protect\uif{Free Text}}{Free Text}) annotation}\label{s:textbox}

A \uif{Text Box} annotation is a rectangular region in which the user can
enter rich text. The annotation may be created and `pre-populated' with rich text from a
{\LaTeX} source through the \pkg{annot\_pro} package.

The \uif{Text Box} annotation, as implemented by this package, requires the
\pkg{richtex} package, dated 2018/08/05 or later. A one simple method for
introducing \pkg{richtext} is through the \opt{richtext} option of
\pkg{annot\_pro}. Placing the following line in the preamble:
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[richtext]{annot_pro}
\end{Verbatim}
declares you are going to use \uif{Text Box} annotations. The option does
nothing more than to execute \cs{usepackage\darg{richtext}[2018/08/05]}. The
option is more of a convenience.

To create a  \uif{Text Box} (originally named \uif{Free Text}) annotation use the \cs{annotpro} command.
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}{3.5in}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[xleftmargin=\leftmargini,commandchars=!(),fontsize=\small]
\annotpro[!textbf(type=textbox),!ameta(KV-pairs)]
    {richtext=!ameta(name),defstyle=!ameta(name)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:textbox}
\end{minipage}\end{minipage}\eVerb
Notice the second argument is not \ameta{content} as it is with the other annotations, but consists
of key-value pairs; recognized keys are \texttt{richtext} and \texttt{defstyle}.

\newtopic\noindent The sample file \texttt{textbox.tex} illustrates the features of this section.

\subsubsection{Creating an empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}}

A common application would be to create an empty \uif{Text Box} for the
document consumer to type in comments. Below is an example of a \uif{Free
Text} annotation, called \uif{Text Box} by the user-interface of
\app{Acrobat}/\app{Adobe Reader}.
\begin{flushleft} %\previewtrue
\begin{minipage}{2in}
\annotpro[title=dpstory,type=textbox,subject=Empty Text Box]{}
\end{minipage}\hfill
\begin{minipage}{\linewidth-2in-10pt}\small
Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to obtain
the \uif{Properties} toolbar, now click on the text box  to obtain the
\uif{Text Box Properties} toolbar. Double clicking on the text box
brings up the \uif{Text Box Text Properties} toolbar.
\end{minipage}
\end{flushleft}
The verbatim listing of the above \uif{Text Box} is,
\begin{Verbatim}[xleftmargin=\leftmargini]
\annotpro[type=textbox,
    title=dpstory,subject=Empty Text Box]{}
\end{Verbatim}
The required second argument is empty, which leads to an empty \uif{Text Box}.

\subsubsection{Creating a non-empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}}\label{ss:textbox}

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.

%[Steps to create rich text content]

\paragraph[Steps to create rich text content]{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}
    \item Use the \env{textboxpara} environment and the \cs{rtpara} command
    to declare your rich text paragraph.
\bVerb\takeMeasure{\string\rtpara[\ameta{KV-pairs}]\darg{\ameta{name\SUB{para}}}\darg{\ameta{rich-content}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\begin{textboxpara}
\rtpara[!ameta(KV-pairs)]{!ameta(name!SUB(para))}{!ameta(rich-content)}
...
\end{textboxpara}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:rtpara}
\end{minipage}\end{minipage}\eVerb
Details of the \cs{rtpara} command are found in the documentation manual of
the \pkg{richtext} package. The \env{textboxpara} environment is needed for
certain redefinitions of internals because of the different way rich text
is supported and implemented in the \uif{Text Box} annotation verses the
rich text field.

\item Use the \cs{setRVVContent} command on your \cs{rtpara}-declared rich text and give it
a name \ameta{name\SUB{rvvc}}.
\bVerb\takeMeasure{\string\setRVVContent\darg{\ameta{name\SUB{rvvc}}}\darg{\ameta{name\SUB{para}}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\setRVVContent{!ameta(name!SUB(rvvc))}{!ameta(name!SUB(para))}
...
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:setRVVC}
\end{minipage}\end{minipage}\eVerb
This command expands the paragraph named \ameta{name\SUB{para}} and
develops the rich text version and the plain text version. It is
\ameta{name\SUB{rvvc}} that is used as a value for the \opt{richtext} key
above and illustrated below. To reduce the number of names, you can use
the same name for \ameta{name\SUB{rvvc}} as for \ameta{name\SUB{para}}
(\cs{setRVVContent\darg{para1}\darg{para1}}).

The rich text \emph{form field} supports multiple paragraphs, and richer
formatting options than the \uif{Text Box} annotation. Of importance is
that the \uif{Text Box} annotation only permits a \emph{single paragraph}.

\item (Optional) Declare a (named) default style using \cs{setDefaultStyle}:
\bVerb\takeMeasure{\string\setDefaultStyle\darg{\ameta{name\SUB{ds}}}\darg{\ameta{KV-pairs}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\setDefaultStyle{!ameta(name!SUB(ds))}{!ameta(KV-pairs)}
...
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:setDefStyle}
\end{minipage}\end{minipage}\eVerb
This default style is assignment a name that is used as the value of the
\opt{defstyle} key mentioned earlier, and illustrated below. If a value for
\opt{defstyle} is not provided, a standard default style is used.

\end{itemize}
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.}\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
descriptions and examples found below.
\begin{description}
    \item[\texttt{richtext=\ameta{name\SUB{rvvc}}}] The \opt{richtext} key
        is the way the rich text is passed to the \uif{Text Box}. The
        \ameta{name\SUB{rvvc}} is declared by the \cs{setRVVContent}
        command. Use the command \cs{rtpara} within the \env{textboxpara}
        environment to define the actual rich text paragraph. For example,
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \bf{rich text}!}
\end{textboxpara}
\setRVVContent{myContent}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{!textbf(richtext=myContent)}
\end{Verbatim}
The above code produces the following \uif{Text Box}:
\begin{quote}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \bf{rich text}!}
\end{textboxpara}
\setRVVContent{myContent}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=myContent}
\end{quote}

    \item[\texttt{defstyle=\ameta{name\SUB{ds}}}] Through the
        \opt{defstyle} you can define set the default style (refer to the
        documentation of the \pkg{richtext} package. If this key does not
        appear, then a predefined default style is provided.
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},
    color=0000FF}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \it{rich text}!}
\setRVVContent{para1}{para1}
\end{textboxpara}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=para1,!textbf(defstyle=myDS)}
\end{Verbatim}
Notice that we've used the name `\texttt{para1}' for both \cs{setRVVContent}
and \cs{rtpara}. The above code produces the following \uif{Text Box}:
\begin{flushleft}%\previewtrue
\begin{minipage}{2in}
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},color=0000FF}
\begin{textboxpara}
\rtpara{para1}{\span{color=FF0000}{Hello world},
    this is \it{rich text}!}
\end{textboxpara}
\setRVVContent{para1}{para1}
\annotpro[type=textbox,title=dpstory,
    subject=Text Box]{richtext=para1,defstyle=myDS}
\end{minipage}\hfill
\begin{minipage}{\linewidth-2in-10pt}\small
Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to
obtain the \uif{Properties} toolbar, now double click on the text box to
obtain the \uif{Text Box Text Properties} toolbar to verify the font used
is indeed Myriad Pro.
\end{minipage}
\end{flushleft}
\end{description}
If you are at all interested in generating the \uif{Text Box} annotation using rich text
strings, you are encouraged to read the documentation on \pkg{richtext},
there you will learn about all the key-values available to format the text
and the paragraph.

The \pkg{richtext} package was written for rich text form fields, but applies
to rich text annotations as well; however, it should be noted that there are
differences between forms and text box annotations in how they handle rich
text. One of the major differences is that rich text annotations (\uif{Text
Box}) \emph{do not support} multiple paragraphs as form fields do; as a
result, features listed in the \uif{Paragraph} and \uif{Link} tabs of the
\uif{Form Field Text Properties} dialog box are not available for the
\uif{Text Box}.

\paragraph[Keys \& commands inherited from the \texorpdfstring{\protect\pkg{richtext}}{richtext} package]%
{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}
\xdef\panelWidth{\the\linewidth}%
\begin{quote}\raggedright
\opt{font}, \opt{size}, \opt{\st{raise}}, \opt{ulstyle},
\opt{color}, \opt{\st{url}}, \opt{style}, \opt{\st{raw}}, \opt{halign}
\end{quote}
\end{minipage}\hfill
\begin{minipage}[c]{\linewidth-\panelWidth}
\setDisplayNumber\label{display:suppKeys}
\end{minipage}\end{minipage}\eVerb
The following commands are supported:
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}[c]{4in}
\xdef\panelWidth{\the\linewidth}%
\begin{quote}\raggedright
\cs{span}, \cs{br}, \cs{it}, \cs{bf}, \cs{sup} and \cs{sub}
\end{quote}
\end{minipage}\hfill
\begin{minipage}[c]{\linewidth-\panelWidth}
\setDisplayNumber\label{display:suppCmds}
\end{minipage}\end{minipage}\eVerb
The ones having an overstrike are supported in a rich text \emph{form field}, but
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}.}\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 {\protect\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}.
    \item \cs{br} is a line break, it has no argument.
    \item \cs{it} is italic font; it has one argument, the text to be
        placed in italics: \cs{it\darg{this is italic}}.
    \item \cs{bf} is bold font; it has one argument, the text to be placed in bold:
    \cs{bf\darg{this is bold}}.

    \cs{it} and \cs{bf} may be nested: \cs{it\darg{\cs{bf\darg{bold and italic}}}}.

    \item \cs{sup} and \cs{sub} are superscript and subscript, respectively; they each
    have one argument, the text to be raised or lowered. For example,
    \verb~We can \sup{raise} or we can \sub{lower} text~.
\end{itemize}
The above markups, with the exception of \cs{span} are illustrated below.\label{exmpl:rt}
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{mypara}{\\it{This is italic}, whereas \\bf{this is bold}, but wait, we can do
\\it{\\bf{bold and italic}}.\\br\\br Moving on, we can \\sup{raise} or we can \\sub{lower} text.}
\\end{textboxpara}
\\setRVVContent{mypara}{mypara}
\\annotpro[type=textbox,width=3.5in]{richtext=mypara}
\end{defineJS}
\begin{quote}
\begin{textboxpara}
\rtpara{mypara}{\it{This is italic}, whereas \bf{this is bold}, but wait, we can do
\it{\bf{bold and italic}}.\br\br Moving on, we can \sup{raise} or we can \sub{lower} text.}
\end{textboxpara}
\setRVVContent{mypara}{mypara}
\annotpro[type=textbox,width=3.5in]{richtext=mypara}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
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.}\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}
\cs{span\darg{\ameta{KV-pairs}}\darg{\ameta{text}}}.
\end{quote}
The \ameta{KV-pairs} argument can be the keys of
display~\eqref{display:suppKeys} (again excluding the overstrike keys). The \ameta{text} argument is the
text to be made rich; experience shows that \cs{it}, \cs{bf}, \cs{sub} and \cs{sup} may be used within
\ameta{text}. Italic and bold may be accomplished using the \opt{style} key, probably preferred over
using \cs{it} and \cs{bf} within \ameta{text}.
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{Welcome to my \\span{style={strikeit,bold}}{poor}\\span{style=bold}{rich text world}.
We add a little color shall we try \\span{color=FF0000}{red} or \\span{color=00FF00}{green}?\\br\\br
There are several styles of underlining \\span{ulstyle=ul}{basic underlining},
\\span{ulstyle=2ul}{double underlining}, \\span{ulstyle=wul}{word underlining}, and
\\span{ulstyle=2wul}{double word underlining}. Cool.}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}
\end{defineJS}
\begin{quote}
\begin{textboxpara}
\rtpara{para1}{Welcome to my \span{style={strikeit,bold}}{poor}\span{style=bold}{rich text world}.
We add a little color shall we try \span{color=FF0000}{red} or \span{color=00FF00}{green}?\br\br
There are several styles of underlining \span{ulstyle=ul}{basic underlining},
\span{ulstyle=2ul}{double underlining}, \span{ulstyle=wul}{word underlining}, and
\span{ulstyle=2wul}{double word underlining}. Cool.}
\end{textboxpara}
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
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}.}\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},
\opt{size}, \opt{color}, and \opt{halign} are typically used. For example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()]
\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},
    size=12.0,color=0000FF,halign=left}
\end{Verbatim}
The name `\opt{myDS}' may then be used as the value of \opt{defstyle} key in the second argument
of \cs{annotpro}, see display~\eqref{display:textbox}.

\subsubsection{Key-values for text box annotations}

\hyperref[s:CommonKeys]{Section~\ref*{s:CommonKeys}} lists keys that are
common to all annotations; we list the ones that make sense for the \uif{Text
Box} annotation, and strikeout those that do not:
\begin{quote}\raggedright
\texttt{type}, \texttt{\st{name}}, \texttt{title}, \texttt{subject},
\texttt{\st{color}}, \texttt{readonly}, \texttt{opacity}, \texttt{margin},
\texttt{presets}
\end{quote}
In addition to these keys,  there are several keys particular to the text box
annotation. We list these and describe them in detail.
\begin{itemize}
    \item \texttt{width=\ameta{length}}: The width of the annotation, the
        default is \texttt{144bp} (\texttt{2in}).
    \item \texttt{height=\ameta{length}}: The height of the annotation, the
        default is \texttt{72bp} (\texttt{1in}).
    \item \texttt{bgcolor=\ameta{color}} The color to be used as the background color
    of the text box annotation. If \opt{bgcolor} has no value, transparent color is used.
    The default is white.
    \item \texttt{bcolor=\ameta{color}} The color to be used as the boundary color of the
    annotation. The default is black.
    \item \texttt{borderstyle=\ameta{choice}}: This keys determines the
        style of border to be used. It is a choice key, choices are
        \texttt{none}, \texttt{solid}, \texttt{dash1}, \texttt{dash2},
        \texttt{dash3}, \texttt{dash4}, \texttt{dash5}, \texttt{dash6},
        \texttt{cloud1}, and \texttt{cloud2}. The default is  \texttt{solid}.
    \item \texttt{borderwidth=\ameta{choice}}: The border width of the
        annotation, acceptable choices are  \texttt{.5}, \texttt{1}, \texttt{2},
        \texttt{3}, \texttt{4}, \texttt{6}, 8, and \texttt{10}. The default is \texttt{1}.
\end{itemize}
\begin{textboxpara}
\rtpara{para1}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=14bp*2, bgcolor=cornsilk,
bcolor=blue]{richtext=para1}}}\setRVVContent{para1}{para1}
\rtpara{para2}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=16bp*3, bgcolor, bcolor=red,
borderstyle=dash2, borderwidth=2]{richtext=para2}}}\setRVVContent{para2}{para2}
\rtpara{para3}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=18bp*3, bcolor=red,
borderstyle=cloud1]{richtext=para3}}}\setRVVContent{para3}{para3}
\end{textboxpara}%\previewtrue
\setDefaultStyle{myDS}{font=Courier,size=12.0,color=000000}
\annotpro[type=textbox, width=\linewidth, height=14bp*2, bgcolor=cornsilk, bcolor=blue]{richtext=para1,defstyle=myDS}\\[6bp]
\annotpro[type=textbox, width=\linewidth, height=16bp*3, bgcolor, bcolor=red, borderstyle=dash2, borderwidth=2]{richtext=para2,defstyle=myDS}\\[6bp]
\annotpro[type=textbox, width=\linewidth, height=18bp*3, bcolor=red, borderstyle=cloud1]{richtext=para3,defstyle=myDS}\\[6bp]
The second text box annotation above has transparent background color. Using your pointing device, move it around to verify
the background is `see through', compare with the other two by moving them around, not `see through'.

\subsection{The text markup annotations}

We paraphrase the \textsl{PDF Reference}, version 1.7, on page~633,
\begin{quote}
Text markup annotations appear as highlights, underlines, strikeouts, and
jagged (``quiggly'') underlines in the text of the document. When opened,
they display a pop-up window the text of the associated note. The syntax
for \cs{annotpro} is given below:
\end{quote}
This annotation type represents a challenge to the {\LaTeX} package developer in that
this annotation is \annotpro[type=underline]{This first example demonstrates an underline text markup annotation.}{tied to typeset content of the document itself}.
\bVerb\takeMeasure{\quad{type=\ameta{\upshape{highlight|underline|squiggly|strikeout}}},}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\annotpro*[% !sffamily(Syntax for text markup annotation)
!quad(type=!ameta(!upshape(highlight|underline|squiggly|strikeout))),
!quad!ameta(KV-pairs)]{!ameta(content)}{!ameta(text)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproCmdtm}
\end{minipage}\end{minipage}\eVerb For a text markup annotation, the \texttt{type} key must be one of
the values listed above. Notice that when creating a text markup annotation, there is a third
required argument, \ameta{text}; compare this with the syntax of all other
annotations, given in display~\eqref{display:arbproCmd} on
page~\pageref{display:arbproCmd}. The \ameta{content} argument can be text or
a key-value pair, the latter is used to create rich text content. Refer to
Section~\ref{rtContent} for a discussion of this option.

\subsubsection{Key-values for the text markup annotation}

This annotation inherits many of the key-values listed earlier, and recognized a few more.

The following is the list of keys common to all annotations, taken from Section~\ref{s:CommonKeys}.
The keys that are not applicable to the text markup annotation are struck out.
\begin{quote}
\key{type}, \key{\st{name}}, \key{title}, \key{subject}, \key{color} (the
color of the appearance of the annotation), \key{hidden} (a hidden
annotation may be made visible using JavaScript), \key{readonly},
\key{opacity}, \key{internalID}, \key{\st{margin}}, \key{\st{margintext}},
\key{presets}
\end{quote}
In addition to the ones above, there are several keys for this type of annotation. These address the problem
of text markup that crosses page boundaries. The techniques are from \pkg{aeb\_mlink}.
\begin{itemize}
   \item \key{crackat=\ameta{num}} Break the \ameta{text} after the \ameta{num}${}^{\text{th}}$ syllable.
   \item \key{hyph=\ameta{\upshape{true|false}}} If \texttt{true}, a hyphen character is inserted at the break point.
   (The default is \texttt{false}.)
   \item \key{crackinsat={\ameta{\LaTeX-markup}}} This key inserts \ameta{\LaTeX-markup} after the
   break in the annotation, more precisely, after the hyphen, if any.
   \item \key{copycontent=\ameta{\upshape{true|false}}} Now here's an idea.
       When the \key{text} of a text markup annotation is ``cracked''
       (broken), a new annotation is created on the next page where its
       \ameta{text} is the remaining text (following the
       \ameta{num}${}^{\text{th}}$ syllable), We can either transfer the
       \key{content} to the new annotation or not. If
       \key{copycontent=true} (or just \key{copycontent}) the
       \ameta{content} is transferred to the to the annotation on the next
       page. The default is \key{copycontent=false}, that is, do not copy
       the original \key{content}. The content of the annotation on the
       next page is \cs{apContText}, the definition of which is,
\begin{Verbatim}[fontsize=\small]
\newcommand\apContText{Continued from previous annotation}
\end{Verbatim}
This command may be redefined.
\end{itemize}

\subsubsection{Text markup illustrated}

In this section, the four supported text markup annotation types are
illustrated, and the problem of breaking (or cracking) a text markup annotation
is discussed. The examples presented in this section are available on the sample
file \texttt{text-markup.tex}, found in the \texttt{examples} folder.

\paragraph[Ordinary text markups]{Ordinary text markups.}
These are annotations that do not cross a page boundary.

\begin{itemize}\tightsettings
\item \textbf{Highlight:} \annotpro[type=highlight]{Try to remember this,
    it's important}{A \emph{highlight} text markup annotation: Let's extend
    this text to cross to the next line.}
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\annotpro[type=highlight]{Try to remember this, it's
  important}{A \emph{highlight} text markup annotation:
  Let's extend this text to cross to the next line.}
\end{Verbatim}

\item \textbf{Underline:} \annotpro[type=underline]{Memorize this
    passage}{An \emph{underline} text \emph{markup} annotation: Let's extend this
    text to cross to the next line.}
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\annotpro[type=underline]{Memorize this passage}
  {An \emph{underline} text \emph{markup} annotation:
  Let's extend this text to cross to the next line.}
\end{Verbatim}

\item \textbf{Squiggly:} \annotpro[type=squiggly]{This needs revision}{An
    \emph{squiggly underline} text markup annotation:  Let's extend this
    text to cross to the next line.}
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\annotpro[type=squiggly]{This needs revision}{An
  \emph{squiggly underline} text markup annotation:
  Let's extend this text to cross to the next line.}
\end{Verbatim}

\item \textbf{Strike-Out:}
    \annotpro[type=strikeout]{Nonsense!}{An \emph{strikeout} text markup annotation:  Let's
    extend this text to cross to the next line.}
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\annotpro[type=strikeout]{Nonsense!}{An \emph{strikeout}
  text markup annotation:  Let's extend this text to
  cross to the next line.}
\end{Verbatim}
\end{itemize}
In all cases, the default color is used. (The default color is the same as
the default color that \app{Adobe Acrobat} or \app{Adobe Reader} assigns.)

\paragraph[Cracked text markups]{Cracked text markups.} A tricky problem unique to text markups is the
possibility of \ameta{text} crossing over to the next page; in this circumstance, either rewrite the paragraph containing
the annotation, or crack it up, that is, break it into two annotations, let the second one move to the next page.
To illustrate:
\begin{quote}\def\pb{\penalty-10 \rule{\linewidth}{.4pt}\makebox[0pt][l]{\hspace{\marginparsep}\small page break}\par\smallskip}%\turnSyllbCntOn
\annotpro[type=underline,crackat=34,hyph,crackinsat=\pb]{Memorize this
    passage}{An \emph{underline} text \emph{markup} annotation: Let's extend this
    text to cross to the next line. We are not near a page boundary, so we must simulate
    cracking up the text markup annotation.}
\end{quote}
If you are viewing this documentation in a PDF viewer that supports comment
annotations (\app{Adobe Reader}), you can inspect the \ameta{content}. Prior
to the ``page break'', \ameta{content} is ``Memorize this passage''; after
the ``page break'', the \ameta{content} is the expansion of the command
\cs{apContText}. The verbatim listing of is,
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\begin{quote}
  \def\pb{\penalty-10 \rule{\linewidth}{.4pt}\makebox[0pt][l]
  {\hspace{\marginparsep}\small page break}\par\smallskip}%
\annotpro[type=underline,!textbf(crackat=34),hyph,crackinsat=\pb]
  {Memorize this passage}{An \emph{underline} text \emph{markup}
  annotation: ... cracking up the text markup annotation.}
\end{quote}
\end{Verbatim}
In the above code, \key{crackat=34} is used to break the \ameta{text} apart into two annotations of the
same type and properties. The \key{hyph} key is used because the break point is at an hyphenated word.
the \key{crackinst} key is used to insert additional material after the hyphen; it simulates a break
in the page. (A \cs{pb} command is locally defined as a convenience command.)

The above example is repeated, but with \key{copycontent} and another command \cs{turnSyllbCntOn}
that can be helpful in the authoring stage.
\begin{quote}\turnSyllbCntOn
\def\pb{\penalty-10 \rule{\linewidth}{.4pt}\makebox[0pt][l]{\hspace{\marginparsep}\small page break}\par\smallskip}%\turnSyllbCntOn
\annotpro[type=underline,crackat=34,hyph,copycontent,crackinsat=\pb]{Memorize this
    passage}{An \emph{underline} text \emph{markup} annotation: Let's extend this
    text to cross to the next line. We are not near a page boundary, so we must simulate
    cracking up the text markup annotation.}
\end{quote}
If you view the \ameta{content} of annotations A8 versus A9, you''ll see they are the same; the content
was copied between annotations, unlike the previous example. The other interesting change
is the numbering of the syllables as the \pkg{soul} package sees them. You can now see why I chose
\key{crackat=34}, it was the end of a line and that line ended in a hyphenated word. The notation
A8 and A9 mark the beginning of a text markup annotation; these markups are referenced in the \app{Distiller}
log or the \app{ps2pdf} log. The markups can be turned on and off by
the commands \cs{mlMarksOn} and \cs{mlMarksOff}. The counting of syllables can be turned off by
executing \cs{turnSyllbCntOff} (or by deleting or commenting out \cs{turnSyllbCntOn}).
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\begin{quote}!textbf(\turnSyllbCntOn)
  \def\pb{\penalty-10 \rule{\linewidth}{.4pt}\makebox[0pt][l]
    {\hspace{\marginparsep}\small page break}\par\smallskip}%
\annotpro[type=underline,crackat=34,hyph,!textbf(copycontent),
  crackinsat=\pb]{Memorize this passage}{An \emph{underline}
  text \emph{markup} annotation: ... cracking up the text
  markup annotation.}
\end{quote}
\end{Verbatim}
\textbf{Important.} You may have to compile several times to bring auxiliary
files up to date. The {TEX} log will contain warnings on the state of the
annotations; the \app{Distiller} or \app{ps2pdf} log contains even more
information. You can increase the amount in information written to the logs
by increasing the value of the \opt{dblevel}, try \opt{dblevel=1}.

\section{Creating rich text contents}\label{rtContent}

When the content (or comment) of an annotation is text, the syntax for the
supported annotations are given in display~\eqref{display:arbproCmd}
and~\eqref{display:arbproCmdtm}. An alternate syntax is implemented for
the case of rich text content. Our comments in this section do not include the text box, which
has already been covered in detail in Section~\ref{s:textbox}; the syntax for a text box is
given in display~\eqref{display:textbox}.
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[richtext]{annot_pro}
\end{Verbatim}
As with the text box, to obtain rich text in the content of the annotation,
the \opt{richtext} option is required. That being required, the alternate
syntax for the (non-text box) annotations is,
\bVerb\takeMeasure{\quad{type=\ameta{\upshape{highlight|underline|squiggly|strikeout}}},}%
\def\1{\rule[15pt]{0pt}{0pt}}
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\annotpro*[% !sffamily(Syntax for text markup annotation)
!quad(type=!ameta(!upshape(highlight|underline|squiggly|strikeout))),
!quad!ameta(KV-pairs)]{richtext=!ameta(name)}{!ameta(text)}
!1\annotpro*[% !sffamily(Syntax for all other annotations)
!quad!ameta(KV-pairs)]{richtext=!ameta(name)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproRT}
\end{minipage}\end{minipage}\eVerb
In the above, \ameta{content} is replaced by \texttt{richtext=\ameta{name}}.

The techniques for using rich text are described in the subsection
`\mlnameref{ss:textbox}' on page~\pageref{ss:textbox}.
\emph{Only} the \key{richtext} key is supported; the \key{defstyle} key is
not supported, so \emph{do not use it}.


\subsection{Annotations with rich text illustrated}

Only two examples are presented here: firstly, a sticky note\annotpro[margin,readonly]{richtext=mypara} appears in the margins, and
secondly, \annotpro[type=highlight]{richtext=mypara}{a text markup annotation within this current paragraph}.
The verbatim listing of the highlight text markup is,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()]
\annotpro[type=highlight]!textbf({richtext=mypara}){a text markup
  annotation within this current paragraph}
\end{Verbatim}
where \texttt{mypara} was defined earlier in
paragraph~\mlNameref{para:KeysCmdsRC}. (See sticky note labeled
`\textcolor{blue}{\textbf{The Code}}' in the margins of that paragraph, on
page~\pageref{exmpl:rt}.)

\subsection{Accented glyphs and the unicode characters}

There are several advantages that text box annotation have over rich text
form fields: movability and unicode. An annotation can be moved around the
page by the user quite easily, a form field typically cannot unless the
document consumer is using \app{Acrobat}. Also, when it comes to using
unicode, text box annotations are far superior to rich text form fields.
Unicode characters may be inserted using the convenience commands
\cs{uHex}\marginpar{\small\cs{uHex}} and
\cs{uDec}\marginpar{\small\cs{uDec}}, where the first take a hex code as its
argument and the second takes a non-negative integer as its argument. Latin1
accented characters may be entered using octal notation for example,
\verb~J\374rgen~
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{J\\374rgen is a nice fellow, though I've never met him.\\br\\br
We've communicated, J\\uHex{00FC}rgen and I, via email. J\\uDec{252}rgen where are you?}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}
\end{defineJS}
\begin{textboxpara}
\rtpara{para1}{J\374rgen is a nice fellow, though I've never met him.\br\br
We've communicated, J\uHex{00FC}rgen and I, via email. J\uDec{252}rgen where are you?}
\end{textboxpara}
\begin{quote}
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4in,height=16bp*4]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}

\begin{comment}

But wait, we're not done. In theory, we can access any unicode character through the use
of \cs{uHex} or \cs{uDec}. I'll randomly pick off some unicode characters.
\begin{defineJS}{\annotextboxi}
\\begin{textboxpara}
\\rtpara{para1}{%
\\uHex{01A2}, \\uHex{023E}, \\uHex{03A3}, \\uHex{0416},
\\uHex{0583}, \\uHex{06A6}, \\uHex{263A}, \\uHex{FB21},
\\uHex{82A0}, \\uHex{4EE4}, \\uHex{F92C}, \\uHex{5475}}
\\end{textboxpara}
\\setRVVContent{para1}{para1}
\\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1}
\end{defineJS}
\begin{textboxpara}
\rtpara{para1}{%
\uHex{01A2}, \uHex{023E}, \uHex{03A3}, \uHex{0416},
\uHex{0583}, \uHex{06A6}, \uHex{263A}, \uHex{FB21},
\uHex{82A0}, \uHex{4EE4}, \uHex{F92C}, \uHex{5475}}
\end{textboxpara}
\begin{quote}%\previewtrue
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
Cool!

\end{comment}

\section{Setting Global Options with
    \texorpdfstring{\protect\cs{setAnnotOptions}}{\CMD{setAnnotOptions}}}

Global options are by using the \cs{setAnnotOptions} command.
In the preamble of this document I placed
\begin{Verbatim}[fontsize=\footnotesize]
\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}}
\end{Verbatim}
That way, I didn't have to constantly type in my personal name for each example. These options can be overwritten
by specifying options locally, if I say, \cs{annotpro[author=Don Story]\darg{Hi there!}}, the author is now my
alter ego, Don Story.

%\redpoint\textbf{\textcolor{red}{Important:}} Certain key, \texttt{name}, should not be used to set global options,
%\cs{setAnnotOptions} tests for these, and puts them back to their default values that are expected
%by \cs{annotpro}. These keys should only be used for passing options to \cs{annotpro} in its option list.


\bigskip
\noindent
That's all for now, I simply must get back to my retirement. \dps\space\annotpro[type=stamp,
    customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{%
    Did I say that I had to get back to my retirement?}

\end{document}