summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2018-06-11 12:41:38 +0900
committerNorbert Preining <norbert@preining.info>2018-06-11 12:41:38 +0900
commit119c41f672f44e3acc86d1518ed0a3d8e0149d77 (patch)
treed8ff092e105b1cfe5ce75b5c259201b4356de136 /texmf-dist/source/latex
parenta490ec665932a1db0f08a98eacea1bf799256db8 (diff)
update annot-pro
Diffstat (limited to 'texmf-dist/source/latex')
-rw-r--r--texmf-dist/source/latex/annot-pro/annot_pro.dtx231
-rw-r--r--texmf-dist/source/latex/annot-pro/annot_pro.ins2
-rw-r--r--texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex144
3 files changed, 296 insertions, 81 deletions
diff --git a/texmf-dist/source/latex/annot-pro/annot_pro.dtx b/texmf-dist/source/latex/annot-pro/annot_pro.dtx
index 7e30b00e..ab9649a5 100644
--- a/texmf-dist/source/latex/annot-pro/annot_pro.dtx
+++ b/texmf-dist/source/latex/annot-pro/annot_pro.dtx
@@ -2,7 +2,7 @@
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% annot_pro package, %%
-%% Copyright (C) 2002-2016 D. P. Story %%
+%% Copyright (C) 2002-2017 D. P. Story %%
%% dpstory@uakron.edu %%
%% %%
%% This program can redistributed and/or modified under %%
@@ -14,7 +14,7 @@
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{annot_pro}
-%<package> [2016/10/18 v1.1b Provides selected PDF annotation support (dps)]
+%<package> [2018/04/26 v1.2 Provides selected PDF annotation support (dps)]
%<*driver>
\documentclass{ltxdoc}
\usepackage[fleqn]{amsmath}
@@ -22,6 +22,7 @@
\let\uif\textsf\let\app\textsf
\let\pkg\textsf\let\env\texttt
\def\psf#1{\textsf{\textbf{#1}}}
+\let\opt\texttt
%\def\texorpdfstring#1#2{#1}
%\pdfstringdefDisableCommands{\let\\\textbackslash}
\OnlyDescription % comment out for implementation details
@@ -59,7 +60,21 @@ of changes goes here. Execute
% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
% {\PackageInfo{web}{cannot find aebdonotindex.def}}
%
+% \section{Alternate package name: \texorpdfstring{\protect\pkg{annot-pro}}{annot-pro}}
+% CTAN lists this package (\pkg{annot\_pro}) as \pkg{annot-pro}, so we'll create
+% a dummy package by that name.
+% \changes{v1.2}{2018/04/26}{Added dummy package \string\pkg{annot-pro}}
% \begin{macrocode}
+%<*altpkgname>
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{annot-pro}
+ [2018/04/26 v1.0 annot-pro Alt-name (dps)]
+\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{annot_pro}}
+\ProcessOptions
+\RequirePackage{annot_pro}
+% \end{macrocode}
+% \begin{macrocode}
+%</altpkgname>
%<*package>
\RequirePackage{xkeyval}
% \end{macrocode}
@@ -121,6 +136,8 @@ of changes goes here. Execute
% \begin{macrocode}
\DeclareOptionX{preview}{\previewtrue}
\@ifundefined{ifpreview}{\newif\ifpreview\previewfalse}{}
+\providecommand{\previewOn}{\previewtrue}
+\providecommand{\previewOff}{\previewfalse}
% \end{macrocode}
% \changes{v1.1}{2016/09/29}{Added \string\texttt{useA10Icons} and \string\texttt{useTextBox} options}
% (2016/09/29) Added \texttt{useA10Icons} and \texttt{useTextBox} options
@@ -136,10 +153,36 @@ of changes goes here. Execute
\DeclareOptionX{useTextBox}{\def\ap@requireRichTextAsNeeded{%
\RequirePackage{richtext}[2016/10/03]}}
\let\ap@requireRichTextAsNeeded\relax
+% \end{macrocode}
+% The \IndexOpt{scandoc}\opt{scandoc} option calls some doc assembly JavaScript to scan the document
+% for stamp annotations. For stamps shipped by Adobe this is not necessary, but for any custom stamps,
+% this is needed.
+% \begin{macrocode}
+\DeclareOptionX{scandoc}{\let\anp@InputScanDoc\anp@scanDoc
+ \PassOptionsToPackage{execJS}{insdljs}}
+% \end{macrocode}
+% During document development, you don't what to scan the newly created PDF after you build it to,
+% perhaps, edit the text. In this case, use the \IndexOpt{!scandoc}\opt{!scandoc} option. You want to scan the document when you build the document for the last time
+% before publishing it. Be sure to save the document using the SaveAs menu item. This saves the
+% stamp appearances (symbology in this case) as part of the document.
+% \begin{macrocode}
+\DeclareOptionX{!scandoc}{\let\anp@InputScanDoc\relax}
+% \end{macrocode}
+% The default is not to scan the document. Remember, the final document must be scanned; that is,
+% it must be build with the \opt{scandoc} option in effect.
+% \begin{macrocode}
+\let\anp@InputScanDoc\relax
+\def\anp@scanDoc{\InputIfFileExists{scandoc-anp.def}
+ {\PackageInfo{annot_pro}{Inputting the scandoc-anp.def file}}
+ {\PackageWarning{annot_pro}{Cannot find the file scandoc-anp.def}}}
+% \end{macrocode}
+% \begin{macrocode}
\ProcessOptionsX\relax
+\RequirePackage{trig}
\RequirePackage{hyperref}
\RequirePackage{calc}
\RequirePackage{insdljs}
+\ifx\anp@InputScanDoc\relax\else\let\execjs=y\fi
\RequirePackage[structure]{taborder}
\ap@requireRichTextAsNeeded
% \end{macrocode}
@@ -159,7 +202,6 @@ of changes goes here. Execute
\def\ap@csarg#1#2{\expandafter#1\csname#2\endcsname}
% \end{macrocode}
% Definitions for creating a rectangle used to create a building box for the annot.
-% This switch is later used when creating a custom stamp.
% \begin{macrocode}
\def\ap@Bbox#1#2{%
\edef\bbox@width{#1}\edef\bbox@height{#2}%
@@ -207,6 +249,14 @@ of changes goes here. Execute
\define@key{annotpro}{name}[]{\def\annotpro@name{#1}}
\let\annotpro@name\@empty
% \end{macrocode}
+% The \opt{internalID} key allows you to specify the \psf{NM} entry. Must be
+% unique throughout the page. The default is \texttt{annotpro\string\the\string\ap@annot@cnt}.
+% The key is used only for the most particular of applications.
+% \changes{v1.1c}{2017/06/06}{Added \string\texttt{internalID}}
+% \begin{macrocode}
+\define@key{annotpro}{internalID}[]{\def\annotpro@internalID{#1}}
+\let\annotpro@internalID\@empty
+% \end{macrocode}
% \end{macro}
% For a text annotation, the following are permitted values for \texttt{name}:
% \begin{macrocode}
@@ -236,7 +286,7 @@ TopSecret}[Draft]{\def\annotpro@@name{#1}}%
% \begin{macrocode}
% \end{macrocode}
% \begin{macro}{customStamp}
-% There is a third case. The user can create a custom stamp using graphicxsp
+% There is a third case. The user can create a custom stamp using \pkg{graphicxsp}
% package.
% \begin{macrocode}
\define@key{annotpro}{customStamp}[]{\def\ap@customstamp@name{#1}}
@@ -334,6 +384,15 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
% \end{macro}
% \end{macro}
% \end{macro}
+% \begin{macro}{margprior}
+% Again, when the \texttt{margin} option is taken, we can insert content just inside
+% the left brace of the \cs{marginpar} command.
+% \changes{v1.1c}{2017/06/06}{Added the key \string\texttt{margprior}}
+% \begin{macrocode}
+\define@key{annotpro}{margprior}[]{\def\anp@margprior{#1}}
+\let\anp@margprior\@empty
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{presets}
% A convenience key to allow the introduction of pre-defined options, for example,
% you might like all your comment fields to be red, so you can define
@@ -402,28 +461,39 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
dash1,dash2,dash3,dash4,dash5,dash6,cloud1,cloud2}[solid]{%
\ifcase\nr\relax
\def\ap@border@code{}\or
- \def\ap@border@code{/BS <</S/S\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[2.0 2.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[3.0 3.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[4.0 4.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[4.0 3.0 2.0 3.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[4.0 3.0 16.0 3.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BS <</D[8.0 4.0 4.0 4.0]/S/D\ap@bwidth>>}\or
- \def\ap@border@code{/BE<</I 1.0/S/C>>/RD[\ap@BE@i@calc\space\ap@BE@i@calc
+ \def\ap@border@code{%
+ /BS <</S/S\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[2.0 2.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[3.0 3.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[4.0 4.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[4.0 3.0 2.0 3.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[4.0 3.0 16.0 3.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BS <</D[8.0 4.0 4.0 4.0]/S/D\ap@bwidth>>}\or
+ \def\ap@border@code{%
+ /BE<</I 1.0/S/C>>/RD[\ap@BE@i@calc\space\ap@BE@i@calc
\space\ap@BE@i@calc\space\ap@BE@i@calc]%
\ifx\ap@bwidth\@empty\else/BS <<\ap@bwidth>>\fi}\or
- \def\ap@border@code{/BE<</I 2.0/S/C>>/RD[\ap@BE@ii@calc\space\ap@BE@ii@calc
+ \def\ap@border@code{%
+ /BE<</I 2.0/S/C>>/RD[\ap@BE@ii@calc\space\ap@BE@ii@calc
\space\ap@BE@ii@calc\space\ap@BE@ii@calc]%
\ifx\ap@bwidth\@empty\else/BS <<\ap@bwidth>>\fi}\fi
\def\annotpro@border{#1}}{\PackageWarning{annot_pro}{Bad
- choice for borderstyle,\MessageBreak permissible values are none, solid,%
- dash1, dash2, dash3,\MessageBreak dash4, dash5, dash6, cloud1, cloud2. Try again}}
+ choice for borderstyle,\MessageBreak permissible values are none,
+ solid, dash1, dash2, dash3,\MessageBreak dash4, dash5, dash6,
+ cloud1, cloud2. Try again}}
\def\ap@border@code{/BS <</S/S\ap@bwidth>>}
-\define@choicekey+{annotpro}{borderwidth}[\val\nr]{.5,1,2,3,4,6,8,10}[1]{%
+\define@choicekey+{annotpro}
+ {borderwidth}[\val\nr]{.5,1,2,3,4,6,8,10}[1]{%
\edef\ap@bwidthNum{\val}%
\def\ap@bwidth{/W #1}}{\PackageWarning{annot_pro}{Bad
- choice for borderwidth,\MessageBreak permissible values are .5, 1, 2,\MessageBreak
- 3, 4, 6, 8, 10. Try again}}
+ choice for borderwidth,\MessageBreak permissible values are
+ .5, 1, 2,\MessageBreak 3, 4, 6, 8, 10. Try again}}
\def\ap@bwidthNum{1}
\let\ap@bwidth\@empty
% \end{macrocode}
@@ -431,9 +501,19 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
% \begin{macro}{readonly}
% Set the annotation to readonly.
% \begin{macrocode}
-\define@key{annotpro}{readonly}[ 64 add]{\def\ap@readonly{#1}}
+%\define@key{annotpro}{readonly}[ 64 add]{\def\ap@readonly{#1}}
+\define@boolkey{annotpro}{readonly}[true]{\ifKV@annotpro@readonly
+ \def\ap@readonly{ 65 add}\else\let\ap@readonly\@empty\fi}
\let\ap@readonly\@empty
% \end{macrocode}
+% Added the \texttt{hidden} option.
+% \changes{v1.1c}{2017/06/06}{Added \string\texttt{hidden} property}
+% \begin{macrocode}
+%\define@key{annotpro}{hidden}[ 2 add]{\def\ap@hidden{#1}}
+\define@boolkey{annotpro}{hidden}[true]{\ifKV@annotpro@hidden
+ \def\ap@hidden{ 2 add}\else\let\ap@hidden\@empty\fi}
+\let\ap@hidden\@empty
+% \end{macrocode}
% \end{macro}
% \begin{macro}{nohspace}
% \begin{macro}{nohspace}
@@ -685,8 +765,10 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
\endgroup
% \end{macrocode}
% \section{The main code}
+% \changes{v1.1c}{2017/06/06}{Define convenience command \string\cs{currentAnnotName}}
% \begin{macrocode}
\newcount\ap@annot@cnt
+\def\currentAnnotName{annotpro\the\ap@annot@cnt}
\newcount\ap@cusstamp@cnt
{\catcode`\#=12\gdef\ap@signalCustomAP{#}}
\def\pStamp#1{\ap@signalCustomAP#1}
@@ -702,8 +784,10 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
% The implementation of rich text in a FreeText annotation is a little different from
% that of a rich text form field. We made some adjustments here for an annotation.
% \begin{macrocode}
-\def\ap@sub#1{\rvorvstring{<span style="vertical-align:-0.0pt;">#1</span>}{#1}}%
-\def\ap@sup#1{\rvorvstring{<span style="vertical-align:+0.0pt;">#1</span>}{#1}}%
+\def\ap@sub#1{%
+ \rvorvstring{<span style="vertical-align:-0.0pt;">#1</span>}{#1}}%
+\def\ap@sup#1{%
+ \rvorvstring{<span style="vertical-align:+0.0pt;">#1</span>}{#1}}%
\def\ap@uDec#1{\rt@amp\rt@hashtag#1;}
\def\ap@uHex#1{\rt@amp\rt@hashtag x#1;}
\def\ap@afterParaFont{%
@@ -718,6 +802,8 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
}
% \end{macrocode}
% \begin{environment}{textboxpara}
+% Rich text for the Text Box annotation is enclosed within this environment, then use \cs{rtpara} to
+% format the text.
% \begin{macrocode}
\newenvironment{textboxpara}{%
\let\rt@sub\ap@sub\let\rt@sup\ap@sup
@@ -742,19 +828,29 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
% \verb!\#!
% \begin{macrocode}
\let\#\ap@signalCustomAP
- \@nnotpro
-}
-\newcommand{\@nnotpro}[1][]{%
+ \@nnotpro}
% \end{macrocode}
-% Increment a global counter, to count the annots as we create them.
+% Added a star option to \cs{annotpro}. When specified (\DescribeMacro{\annotpro*}\cs{annotpro*}),
+% the options are expanded with \cs{setkeys*}. Also new is the
+% options are expanded first before \cs{setkeys} or \cs{setkeys*} is applied.
+% \changes{v1.1c}{2017/06/06}{Added a star option to \string\cs{annotpro}}
% \begin{macrocode}
- \global\advance\ap@annot@cnt1\relax
+\def\@nnotpro{\@ifstar{\def\qr@isStar{*}\@nnotproi}
+ {\let\qr@isStar\@empty\@nnotproi}}
+\newcommand{\@nnotproi}[1][]{%
% \end{macrocode}
-% Process options
+% Process options after expanding them
% \begin{macrocode}
- \setkeys{annotpro}{#1}%
- \@nn@tpro
-}
+ \expandafter\setkeys\qr@isStar{annotpro}{#1}%
+% \edef\temp@exp{\noexpand\setkeys\qr@isStar{annotpro}{#1}}\temp@exp
+\ifx\annotpro@internalID\@empty
+% \end{macrocode}
+% Increment a global counter, to count the annots as we create them.
+% \begin{macrocode}
+ \global\advance\ap@annot@cnt1\relax
+ \xdef\currentAnnotName{annotpro\the\ap@annot@cnt}\else
+ \xdef\currentAnnotName{\annotpro@internalID}\fi
+ \@nn@tpro}
\newcommand{\@nn@tpro}[1]
{%
% \end{macrocode}
@@ -903,6 +999,17 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
\def\ap@ImageRef{\annotpro@ap\the\ap@cusstamp@cnt}%
\expandafter\ap@useStamp\expandafter{\annotpro@ap}%
% \end{macrocode}
+% We do not allow custom stamps to be initially rotated.
+% \changes{v1.1c}{2017/06/06}{For custom stamps, do not allow the rotate
+% key to be nonzero.}
+% \begin{macrocode}
+ \ifx\annotpro@rotate\@empty\else
+ \PackageWarning{annot_pro}{The rotate
+ key for a custom stamp is not\MessageBreak
+ supported. Setting rotate=0}%
+ \let\annotpro@rotate\@empty
+ \fi
+% \end{macrocode}
% After making many experiments, there seems to be a need to
% reduce dimensions by \texttt{2bp} so that the desired dimensions
% are displayed through the user interface. There seems to
@@ -1028,10 +1135,13 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
\expandafter\relax\else\expandafter\marginpar\fi
% \end{macrocode}
% Set the bounding box, and layout the annotation using the \textbf{pdfmark} operator.
+% \changes{v1.1c}{2017/06/06}{added \string\cs{anp@margprior} followed by braces, so
+% \string\cs{anp@margprior} could operate on the annot as a whole.}
% \begin{macrocode}
- {\pdf@rect{\ap@Bbox{\ap@thisWidth}{\ap@thisHeight}}\literalps@out{%
+ {\anp@margprior{%
+ \pdf@rect{\ap@Bbox{\ap@thisWidth}{\ap@thisHeight}}\literalps@out{%
[ \eq@objdef\ap@Rect
- /F 4\ap@readonly
+ /F 4\ap@hidden\ap@readonly
/Open \annotpro@open
/Title (\annotpro@enc@title)
/Subj (\annotpro@enc@subject)
@@ -1062,10 +1172,11 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
% \begin{macrocode}
/Name (\annotpro@@name)
/Subtype/\ap@type
- /NM (annotpro\the\ap@annot@cnt)
+ /NM (\currentAnnotName)
+% /NM (annotpro\the\ap@annot@cnt)
/M (D:\ap@pdfdate)
\ap@this@AP\ap@this@FS\ap@this@CA\ap@this@Rotate
- /ANN pdfmark}\apmargintext}%
+ /ANN pdfmark}\apmargintext}}%end grouping, end marginpar
\to@insertStrucTabOrder{Annot}\endgroup
}
% \end{macrocode}
@@ -1152,10 +1263,62 @@ are Graph,Paperclip,PushPin,Tag. Try again}}
>> /PUT pdfmark
[ {apFileStream\the\ap@annot@cnt} /CLOSE pdfmark}%
}
+%</package>
+%<*scandoc>
+% \end{macrocode}
+% \subsection{Document assembly}
+% The document assembly code is executed when the \texttt{scandoc} option is used. It is executed
+% then the document is first opened.
+% \begin{macrocode}
+\begin{execJS}{scan4anp}
+var aANPStamps=new Array();
+if (typeof scancomplete=="undefined") {
+ var scancomplete=false;
+ this.syncAnnotScan();
+ for (var p=0; p<this.numPages; p++) {
+ a=this.getAnnots(p);
+ if (a!=null) {
+ for (var i=0; i<a.length; i++) {
+% \end{macrocode}
+% At this time, we search only for annots of type \texttt{"Stamp"} and with AP beginning
+% with `\texttt{\#}', for these are user installed stamps or dynamic stamps.
+% \begin{macrocode}
+ if ( a[i].type=="Stamp" && a[i].AP.indexOf("\#")==0 ) {
+ aANPStamps.push(p);
+ break;
+ }
+ }
+ }
+ }
+}
+ANPscrollPage.index=0;
+function ANPscrollPage() {
+% \end{macrocode}
+% We go to the page where each stamp of the type we are interested in. Opening the page
+% causes \app{Acrobat} to populate the dynamic stamps.
+% \begin{macrocode}
+ if (ANPscrollPage.index<aANPStamps.length) {
+ this.pageNum=aANPStamps[ANPscrollPage.index];
+ ANPscrollPage.index+=1;
+ } else {
+ app.clearInterval(anpTO);
+ scancomplete=true;
+ this.pageNum=0;
+ }
+}
+if (aANPStamps.length>0)
+ var anpTO=app.setInterval("ANPscrollPage()", 5);
+\end{execJS}
+%</scandoc>
+%<*package>
% \end{macrocode}
% Set global options for this package.
% \begin{macrocode}
\setAnnotOptions{title,subject,open=false,color}
+% \end{macrocode}
+% Input \texttt{scandoc-anp.def}, if required.
+% \begin{macrocode}
+\anp@InputScanDoc
%</package>
% \end{macrocode}
% \Finale
diff --git a/texmf-dist/source/latex/annot-pro/annot_pro.ins b/texmf-dist/source/latex/annot-pro/annot_pro.ins
index db093b1d..50819072 100644
--- a/texmf-dist/source/latex/annot-pro/annot_pro.ins
+++ b/texmf-dist/source/latex/annot-pro/annot_pro.ins
@@ -49,6 +49,8 @@
\generate{%
\file{annot_pro.sty}{\from{annot_pro.dtx}{copyright,package}}
+ \file{annot-pro.sty}{\from{annot_pro.dtx}{copyright,altpkgname}}
+ \file{scandoc-anp.def}{\from{annot_pro.dtx}{copyright,scandoc}}
}
\Msg{***************************************************************}
diff --git a/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
index 167bc0ea..e67994fb 100644
--- a/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
+++ b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex
@@ -63,7 +63,7 @@
email={dpstory@acrotex.net},
subject={Documentation for annot\textunderscore pro from AcroTeX},
talksite={\url{www.acrotex.net}},
- version={1.1b, 2016/10/18},
+ version={1.2, 2018/04/26},
keywords={sticky notes, stamps, file attachment text box, free text, annotations},
copyrightStatus=True,
copyrightNotice={Copyright (C) \the\year, D. P. Story},
@@ -164,6 +164,13 @@ _path=_path.substring(0,pos)+"/"+manualfilename;
\tableofcontents
\selectColors{linkColor=webgreen}
+% New
+% X internalID
+% margprior
+% X hidden
+% X \currentAnnotName
+% annotpro*
+
\section{Introduction}
This package is used to create text, stamp, and file attachment
@@ -175,6 +182,11 @@ The package primarily in support of my \href{http://www.math.uakron.edu/~dpstory
{{Acro\negthinspace\TeX} PDF Blog}. I plan to use sticky notes, file attachments, and
custom stamps to make side-comments, and to provide source files.
+\section{Alternate package name: \texorpdfstring{\protect\pkg{annot-pro}}{annot-pro}}
+
+CTAN lists this package as \pkg{annot-pro}, so might as well have such a package by that name:
+\pkg{annot-pro} loads \pkg{annot\_pro} with the specified options.
+
\section{Requirements}
The requirements for your {\LaTeX} system, and well as any other
@@ -284,25 +296,31 @@ right in the \texttt{AllowPSFileOps} row to select Yes as the value.
The main command of this package is \Com{annotpro}; the command is controlled by
its optional parameters. The same command can create a text annotation (sticky note),
a stamp annotation, a file attachment or a Free Text (Text Box) annotation. The syntax of this command is
-\bVerb\takeMeasure{\string\annotpro[\ameta{KV-pairs}]\darg{\ameta{text}}}%
+\bVerb\takeMeasure{\string\annotpro*[\ameta{KV-pairs}]\darg{\ameta{text}}}%
\begin{minipage}{\linewidth}
\begin{minipage}{\bxSize}
\xdef\panelWidth{\the\linewidth}%
\begin{Verbatim}[frame=single,commandchars=!()]
-\annotpro[!ameta(KV-pairs)]{!ameta(text)}
+\annotpro*[!ameta(KV-pairs)]{!ameta(text)}
\end{Verbatim}
\end{minipage}\hfill
\begin{minipage}{\linewidth-\panelWidth}
\setDisplayNumber\label{display:arbproCmd}
\end{minipage}\end{minipage}\eVerb
-\PD The optional argument is one or more key-value pairs that describe the
-annotation; the required argument, \ameta{text}, is the ``contents'' of the
-annotation; for the text and stamp annotation, \ameta{text} becomes the
-contents of the popup annotation, for a file attachment annotation, which has
-not associated pop-up, it is the description of the file attachment that
-appears in the file attachment panel of Adobe Reader. In the latter case, the
-value of \ameta{text} should be rather short. The key-value pairs (\ameta{KV-pairs}) are
-described over the next few sections.
+\PD The optional argument consists is one or more key-value pairs
+(\ameta{KV-pairs}) that describe the annotation; the required argument,
+\ameta{text}, is the ``contents'' of the annotation; for the text and stamp
+annotation, \ameta{text} becomes the contents of the popup annotation, for a
+file attachment annotation, which has no associated pop-up, it is the
+description of the file attachment that appears in the file attachment panel
+of Adobe Reader. In the latter case, the value of \ameta{text} should be
+rather short. The key-value pairs (\ameta{KV-pairs}) are described over the
+next few sections.
+
+Normally, \cs{annotpro} uses the \cs{setkeys} command of \pkg{xkeyval} to
+determine the options specified, when the star-option is specified, \cs{annotpro}
+uses \cs{setkeys*} to evaluate the options, refer to the \pkg{xkeyval} documentation
+for a description of \cs{setkeys} and \cs{setkeys*}.
\paragraph*{\color{red}Sample files.} The sample files \texttt{annots.tex} and \texttt{textbox.tex} illustrate the features
of the \pkg{annotpro} package.
@@ -332,38 +350,69 @@ The following are key-value pairs common to all annotations.
\end{Verbatim}
\item \texttt{color}: The color of the title bar of the pop-up window of the annotation.
\item \texttt{readonly=\ameta{\upshape{true|false}}} Set the annotation to readonly. The user can click on the annot to
- see the popup, but the user, if using Acrobat, cannot move the annotation around on the page.
- The popup window can still be move by the user. (This property makes no difference to the
- user of Adobe Reader.)
+ see the popup, but the user, if using \app{Acrobat}, cannot move the annotation around on the page.
+ The popup window can still be moved by the user. (\texttt{readonly} is the same as \texttt{readonly=true}.)
+ \item \texttt{hidden=\ameta{\upshape{true|false}}} This key sets the annotation to hidden, it is not visible
+ and does not interact with the user. (\texttt{hidden} is the same as \texttt{hidden=true}.)
\item \texttt{opacity=\ameta{dec}}: The opacity value ($
\text0\le\text{\ameta{dec}}\le\text1$) to be used in painting the (icon of
the) annotation, but does apply to the pop-up window. The default
is 1.0.
\item[] Adobe Distiller handles the opacity for us in all cases except when we create a (dynamic) stamp.
If an opacity value less than 1 is desired, special techniques are needed, and the file needs to
- be distilled using the \textbf{Standard\_tranparency} job options.
-
+ be distilled using the \textbf{Standard\_transparency} job options.
+ \item \texttt{internalID=\ameta{name}} Each annot must have an internal
+ name (or ID), \emph{unique to the page on which it appears}. The
+ \pkg{annot\_pro} package maintains an internal counter
+ (\cs{ap@annot@cnt}) and routinely assigns each annotation an internal
+ name (or ID) of
+ \begin{quote}\ttfamily
+ annotpro\string\the\string\ap@annot@cnt
+ \end{quote}
+ The \opt{internamID} key allows you to assign an alternate internal
+ name. Thus, if you assign \texttt{internalID=myCoolAnnot}, an
+ annotation is created with the name \texttt{myCoolAnnot}. The
+ internal ID can be used by JavaScript to find a particular annot on
+ the page and to get its properties. The macro \cs{currentAnnotName}
+ contains the internal name of the most recent annot created.
\end{itemize}
-The following key-values are {\LaTeX} based concerning placement of the annotation in the margin.
+The following key-values are {\LaTeX} based concerning placement of the
+annotation in the margin.
\begin{itemize}
- \item \texttt{margin}: Use this key (it has no value), to declare that you want the annotation
- to appear in the margin. The \cs{marginpar} command from core {\LaTeX} is used, the placement
- of the annotation follows the rules set down by {\LaTeX}. You can reverse the placement of the
- annotation by using the {\LaTeX} command \cs{reversemarginpar} (annots placed in the right margin, and now placed in the left);
- you can return to the default by using \cs{normalmarginpar}.
-
- \item[] Given that you have use the \texttt{margin} key, there is an associated key that can be used, as well
- as a command.
+ \item \texttt{margin}: Use this key (it has no value), to declare that
+ you want the annotation to appear in the margin. The \cs{marginpar}
+ command from core {\LaTeX} is used, the placement of the annotation
+ follows the rules set down by {\LaTeX}. You can reverse the
+ placement of the annotation by using the {\LaTeX} command
+ \cs{reversemarginpar} (annots placed in the right margin, and now
+ placed in the left); you can return to the default by using
+ \cs{normalmarginpar}.
+
+ \item[] Given that you have use the \texttt{margin} key, there is an
+ associated key that can be used, as well as a command.
\begin{itemize}
- \item \texttt{margintext}: The value of this key is text that will be typeset just below the annotation icon.
- \item \cs{marginpartextformat}: A {\LaTeX} command for
- formatting the text in the margin, the default definition is\smallskip
+ \item \texttt{margintext}: The value of this key is text that
+ will be typeset just below the annotation icon.
+ \item \cs{marginpartextformat}: A {\LaTeX} command for formatting
+ the text in the margin, the default definition is\smallskip
\begin{Verbatim}
\margintextformat{\bfseries\tiny\color{blue}}
\end{Verbatim}
\end{itemize}
- \item[] For an annotation placed in the margin with margin text, you might want to use the \texttt{readonly}
- key, this prevents the user---even one using Acrobat---from moving the annotation away from its caption.
+ \item[] For an annotation placed in the margin with margin text, you
+ might want to use the \texttt{readonly} key, this prevents the
+ user---even one using Acrobat---from moving the annotation away
+ from its caption.
+ \item \texttt{margprior=\ameta{\cs{cmd}}} This key allows you to
+ operate on the annotation as a whole. The value \ameta{\cs{cmd}} is
+ expected to be, but it is not a requirement, a command taking one
+ argument. (This key-value pair defines \cs{anp@margprior} which
+ expands to \ameta{\cs{cmd}}; placement of \cs{anp@margprior} is
+ \texttt{\cs{anp@margprior}\darg{\meta{the-annot-code}}}. For
+ example, declaring \texttt{marprior=\cs{fbox}} draws an frame box
+ around the annotation, or
+ \texttt{marprior=\cs{raisebox\darg{10pt}}} raises the annotation
+ 10pt.
\end{itemize}
The following key-value is for your convenience.
\begin{itemize}
@@ -494,7 +543,7 @@ The following are the key-values associated with this annotation type.
\texttt{stamps.pdf}), the width and height are not known to
\textsf{annot\_pro}. In this case, use the \texttt{height} and \texttt{width} keys
to set the dimensions of the bounding box. Adobe Distiller will
- resize the stamp to the stamp is the largest one that can fit in
+ resize the stamp to the stamp that is the largest one that can fit in
the bounding box, the stamp will be centered vertically and
horizontally within the bounding box.
@@ -713,7 +762,9 @@ The required second argument is empty, which leads to an empty \uif{Text Box}.
A much more interesting exercise is to pre-populate the \uif{Text Box} with rich text for the
document consumer to read and/or to respond.
-\paragraph[Steps to create rich text content]{Steps to create rich text content.}\chgCurrLblName{Steps to create rich text content}\label{para:StepsRC}
+%[Steps to create rich text content]
+
+\paragraph{Steps to create rich text content.}\label{para:StepsRC}
We briefly outline the techniques to create rich text
for a \uif{Text Box} annotation.
\begin{itemize}
@@ -785,7 +836,7 @@ This default style is assignment a name that is used as the value of the
Once the \cs{rtpara}-declared paragraphs have been made and their names have passed through
\cs{setRVVContent}, you are ready to create a \uif{Text Box} annotation.
-\paragraph[Key-values for second argument]{Key-values for second argument.}\chgCurrLblName{Key-values for second argument}\label{para:KV2ndArg}
+\paragraph[Key-values for second argument]{Key-values for second argument.}\label{para:KV2ndArg}
The required second argument, refer to display~\eqref{display:textbox}, has
two keys, both of which are optional. You are encouraged to read the
documentation for the \pkg{richtext} package for greater understanding of the
@@ -867,8 +918,7 @@ result, features listed in the \uif{Paragraph} and \uif{Link} tabs of the
\uif{Text Box}.
\paragraph[Keys \& commands inherited from the \texorpdfstring{\protect\pkg{richtext}}{richtext} package]%
-{Keys \& commands inherited from the \pkg{richtext} package.}%
-\chgCurrLblName{Keys \& commands inherited from the \pkg{richtext} package}\label{para:InheritedKeys}
+{Keys \& commands inherited from the \pkg{richtext} package.}\label{para:InheritedKeys}
The following keys are supported by the \uif{Text Box} annotation:
\bVerb\begin{minipage}{\linewidth}
\begin{minipage}[c]{4in}
@@ -897,17 +947,18 @@ not within an \uif{Text Box}. Refer to the documentation of the
\pkg{richtext} for details of these keys and commands. In this document, we
illustrate by example.
-\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{Key-values of \cs{rtpara}.}%
-\chgCurrLblName{Key-values of \cs{rtpara}}\label{para:KeysPara} The
-keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones -- may be used in the
-\ameta{KV-pairs} argument of \cs{rtpara} of display~\eqref{display:rtpara}.
+
+\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{%
+Key-values of \cs{rtpara}.}\label{para:KeysPara}
+The keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones
+-- may be used in the \ameta{KV-pairs} argument of \cs{rtpara} of
+display~\eqref{display:rtpara}.
\paragraph[Permissible commands within \texorpdfstring{\protect\ameta{rich-content}}{<rich-content>}]{%
-Permissible commands within \ameta{rich-content}.}\chgCurrLblName{Permissible
-commands within \ameta{\ameta{rich-content}}}\label{para:KeysCmdsRC} The
-\ameta{rich-content} argument of display~\eqref{display:rtpara} (normally)
-consists of Latin 1 characters, plus any markup in the form of the commands
-listed in display~\eqref{display:suppCmds}.
+Permissible commands within \ameta{rich-content}.}\label{para:KeysCmdsRC}
+The \ameta{rich-content} argument of display~\eqref{display:rtpara}
+(normally) consists of Latin 1 characters, plus any markup in the form of the
+commands listed in display~\eqref{display:suppCmds}.
\begin{itemize}
\item \cs{span} has two arguments, more on this command in the paragraph below
titled \Nameref{para:Span}.
@@ -944,7 +995,7 @@ The above markups, with the exception of \cs{span} are illustrated below.
The verbatim listing for this example is in the sticky note in the margin.
\paragraph[Some comments on the \texorpdfstring{\protect\cs{span}}{\textbackslash{span}}
-command]{Some comments on the \cs{span} command.}\chgCurrLblName{Some comments on the \cs{span} command}\label{para:Span}
+command]{Some comments on the \cs{span} command.}\label{para:Span}
the \cs{span} command, defined only locally within the \ameta{rich-text} argument \cs{rtspan} is a general purpose
command to format text. It has two argument:
\begin{quote}
@@ -981,8 +1032,7 @@ There are several styles of underlining \span{ulstyle=ul}{basic underlining},
The verbatim listing for this example is in the sticky note in the margin.
\paragraph[Key-values of \texorpdfstring{\protect\cs{setDefaultStyle}}{\textbackslash{setDefaultStyle}}]%
-{Key-values of \cs{setDefaultStyle}.}%
-\chgCurrLblName{Key-values of \cs{setDefaultStyle}}\label{para:KeysDS} The
+{Key-values of \cs{setDefaultStyle}.}\label{para:KeysDS} The
keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones --
may be used in the \ameta{KV-pairs} argument of \cs{setDefaultStyle} of
display~\eqref{display:setDefStyle}; however, only the keys \opt{font},