% % 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}}}{}]{% 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}