summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
blob: 167bc0eaf8f3bb141b200cfc780aa4ce4f302114 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
%
% 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{annot_pro}
\usepackage{richtext}

\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
\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

%\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, and Text Box Annotations},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for annot\textunderscore pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.1b, 2016/10/18},
    keywords={sticky notes, stamps, file attachment text box, free text, 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

\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{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}}
\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{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{text}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
\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.

\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.

\begin{itemize}
  \item \texttt{type=\ameta{\upshape{text|stamp|fileattachment|textbox}}} The \texttt{type} key determines the type of annotation to be produced;
        permissible values are \texttt{text}, \texttt{stamp}, and \texttt{fileattachment}. This
        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 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.)
  \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.

\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.
\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}[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 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}

\previewtrue

        \item This one \annotpro[type=stamp,name=SBApproved,widthTo=106bp,color=webbrown]{This package just got better!}
        fits more or less exactly.  I determined the dimensions of this stamp through some controls of the user interface.
        Contrast this this stamp
        \annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!}
        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,
        \smash{\annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!}}

\smallskip

\begin{defineJS}{\annotstampi}
Exact fit:
\\annotpro[type=stamp,name=SBApproved,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,color=webbrown]{This package just got better!}
\end{defineJS}

\previewfalse

        \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 \verb!\makebox[0pt][l]{text}!;
    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}

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 2016/09/30 or later. A one simple method for
introducing \pkg{richtext} is through the \opt{useTextBox} option of
\pkg{annot\_pro}. Placing the following line in the preamble:
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[useTextBox]{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}[2016/09/30]}. 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{text} 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}}

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}
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.}\chgCurrLblName{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.}%
\chgCurrLblName{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}.}%
\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[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}.
\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.
\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.}\chgCurrLblName{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}.}%
\chgCurrLblName{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 these 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'.

\subsubsection{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 user
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} and \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 can 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}%\previewtrue
\setRVVContent{para1}{para1}
\annotpro[type=textbox,width=4in,height=16bp*4]{richtext=para1}%
\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}%
\end{quote}
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!


\subsection{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}