diff options
Diffstat (limited to 'texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex')
-rw-r--r-- | texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex | 1120 |
1 files changed, 1120 insertions, 0 deletions
diff --git a/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex new file mode 100644 index 00000000..167bc0ea --- /dev/null +++ b/texmf-dist/source/latex/annot-pro/doc/annotpro_man.tex @@ -0,0 +1,1120 @@ +% +% http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf +% +% makeindex < aebpro_man.idx > aebpro_man.ind +\documentclass[12pt]{article} +\usepackage[fleqn]{amsmath} +\usepackage[ + web={centertitlepage,designv,tight*, + forcolorpaper,latextoc,extended}, + aebxmp,eforms,graphicxsp={showembeds} +]{aeb_pro} +\usepackage{array} +\usepackage{aeb_mlink} +%\usepackage{myriadpro} %[usecmtt] +\usepackage[altbullet]{lucidbry} +\usepackage{annot_pro} +\usepackage{richtext} + +\DeclareInitView +{% + layoutmag={mag=100}, +% windowoptions={fit} +} + +%\useAAXdimtrue + +\usepackage{makeidx} +\makeindex +\usepackage{acroman} + +\usepackage[active]{srcltx} + +\def\expath{../examples} + +\urlstyle{rm} +\def\pkg{\textsf} +\let\app\textsf +\let\opt\texttt +\let\uif\textsf +\let\env\texttt +\def\meta#1{\textit{\texttt{#1}}} +\def\ameta#1{$\langle\textit{\texttt{#1}}\rangle$} +\newdimen\aebdimen \aebdimen6pt %\partopsep \advance\aebdimen\partopsep +\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% +\def\eVerb{\vskip\aebdimen\endgroup\noindent} +\def\SUB#1{\ensuremath{{}_{\text{#1}}}} + +\def\darg#1{\texttt{\{#1\}}} +\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} +\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} +\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} +\let\amtIndent\leftmargini + +%\def\tutpath{doc/tutorial} +%\def\tutpathi{tutorial} + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={The \texorpdfstring{\textsf{annot\_pro} Package\\[1em]}{annot\textunderscore pro Package: } + Text, Stamp, File Attachment, and Text Box Annotations}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject={Documentation for annot\textunderscore pro from AcroTeX}, + talksite={\url{www.acrotex.net}}, + version={1.1b, 2016/10/18}, + keywords={sticky notes, stamps, file attachment text box, free text, annotations}, + copyrightStatus=True, + copyrightNotice={Copyright (C) \the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} + +\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% + \kern-.6em \hbox{$\mathcal S$}}$} + +\universityLayout{fontsize=Large} +\titleLayout{fontsize=LARGE} +\authorLayout{fontsize=Large} +\tocLayout{fontsize=Large,color=aeb} +\sectionLayout{indent=-40pt,fontsize=large,color=aeb} +\subsectionLayout{indent=-20pt,color=aeb} +\subsubsectionLayout{indent=0pt,color=aeb} +\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}} + +\embedEPS[hiresbb,transparencyGroup]{AdobeDon}{../examples/graphics/AdobeDon} + +\makeStamp{0.0 0.0 20.0 20.0}{AdobeDon}{% + [ 20 \widthOf{AdobeDon} div 20 \widthOf{AdobeDon} div scale {AdobeDon} /SP pdfmark +} + +\makeatletter +\def\setDisplayNumber#1#2{\kern0pt + \setlength\abovedisplayshortskip{0pt}% + \setlength\belowdisplayshortskip{0pt}% + \setlength\abovedisplayskip{0pt}% + \setlength\belowdisplayskip{0pt}% + \begin{equation}\label{#2}\end{equation}\kern0pt +} +\renewenvironment{quote}[1][] + {\def\@rgi{#1}\ifx\@rgi\@empty + \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi + \list{}{\rghtm} %{\rightmargin\leftmargin}% + \item\relax} + {\endlist} +\renewcommand*\descriptionlabel[1]{\hspace\labelsep + \normalfont #1} +\setcounter{secnumdepth}{4} +\setcounter{tocdepth}{5} +\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}} +\renewcommand{\paragraph} + {\renewcommand{\@seccntformat}[1]{\theparagraph}% + \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}} +\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}} +\def\chgCurrLblName#1{\def\@currentlabelname{#1}} +\def\echgCurrLblName#1{\edef\@currentlabelname{#1}} +\makeatother + + +\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}} + +%\pagestyle{empty} +%\parindent0pt\parskip\medskipamount + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The annot_pro MANUAL"; +var manualfilename="Manual_BG_Print_annotpro.pdf"; +var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown +var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate; +var doc; +var buildIt=false; +if ( buildIt ) { + console.println("Creating new " + manualfilename + " file."); + doc = \appopenDoc({cPath: _pathToBlank, bHidden: true}); + var _path=this.path; + var pos=_path.lastIndexOf("/"); + _path=_path.substring(0,pos)+"/"+manualfilename; + \docSaveAs\newDO ({ cPath: _path }); + doc.closeDoc(); + doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true}); + f=doc.getField("ManualTitle"); + f.value=titleOfManual; + doc.flattenPages(); + \docSaveAs\newDO({ cPath: manualfilename }); + doc.closeDoc(); +} else { + console.println("Using the current "+manualfilename+" file."); +} +var _path=this.path; +var pos=_path.lastIndexOf("/"); +_path=_path.substring(0,pos)+"/"+manualfilename; +\addWatermarkFromFile({ + bOnTop:false, + bOnPrint:false, + cDIPath:_path +}); +\executeSave(); +\end{docassembly} +\begin{document} + +\maketitle + +\selectColors{linkColor=black} +\tableofcontents +\selectColors{linkColor=webgreen} + +\section{Introduction} + +This package is used to create text, stamp, and file attachment +annotations using \textbf{Adobe Distiller}, these annotations can be +viewed in Adobe Reader. For users of \textsf{pdf(la)tex}, use the +\textsf{pdfcomment} package by Josef Kleber.\footnote{Available at \href{http://ctan.org/pkg/pdfcomment}{ctan.org/pkg/pdfcomment}} + +The package primarily in support of my \href{http://www.math.uakron.edu/~dpstory} +{{Acro\negthinspace\TeX} PDF Blog}. I plan to use sticky notes, file attachments, and +custom stamps to make side-comments, and to provide source files. + +\section{Requirements} + +The requirements for your {\LaTeX} system, and well as any other +software, is highlighted in this section. + +\subsection{{\LaTeX} Package Requirements} + +The following packages, in addition to the standard {\LaTeX} +distribution, are required: +\begin{enumerate} + \item The \textsf{xkeyval} package is used to set up the key-value + pairs of the \cs{annot\-pro} command. Get a recent version. + \item The \textsf{xcolor} package is strongly recommended. + \item The \textsf{hyperref} package, a recent version. + \item If you want to create custom stamps (on the fly) using the techniques + developed for that purpose, the \textsf{graphicxsp} Package is required.\footnote + {Available at \href{http://ctan.org/pkg/graphicxsp}{ctan.org/pkg/graphicxsp}} +\end{enumerate} +The \textsf{annot\_pro} package is part of the \textcolor{blue}{AeB +Pro} family, which means \textbf{Adobe Distiller} is required. The +components of \textcolor{blue}{AeB} and \textcolor{blue}{AeB Pro} +are not required.\footnote{AeB: \href{http://ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}}${}^{,}$\footnote{AeB Pro: +\href{http://ctan.org/pkg/aeb-pro}{ctan.org/pkg/aeb-pro}} + +\subsection{PDF Creator Requirements} + +The \textsf{annot\_pro} package requires \textbf{Acrobat Distiller 5.0} (or +later) as the PDF creator. The document author typically uses dvips (or dvipsone) to +produce a PostScript file, which is then distilled to obtain a PDF. + +If you wish to use (dynamically) created stamps that have opacity less than 1, +you need to distill using \textbf{Standard\_transparancy.joboptions} with distiller, +in this case, \textbf{Acrobat Distiller 6.0} (or later) is required; otherwise, this +distiller job options file is not needed. + +The \textbf{Standard\_transparancy.joboptions} file is supplied with the \textsf{graphicxsp} +package; the documentation of the \textsf{graphicxsp} package includes installation instructions. + +\section{Installation} + +The installation is simple enough. Unzip \texttt{annot\_pro.zip} in a +folder that is on your {\LaTeX} search path. Refresh your filename +database, if appropriate. + +\begin{defineJS}{\winedtDist} +Run(|"c:\\Program Files\\Adobe\\Acrobat 9.0\\Acrobat\\acrodist.exe" -F "%P\\%N.ps"|,'%P',0,0,'%N.ps - Distiller',1,1); +\end{defineJS} + +\paragraph*{\textcolor{red}{Important:}} When creating a file attachment annotation, +you must specify a path to the file to be attached, and distiller must embed +this file. In recent versions of Acrobat, +security restrictions have been put in place to prevent +\textbf{Distiller} from reading files (the PostScript \textbf{file} +operator does not work). Fortunately, Distiller has a switch that +turns off this particular restriction. To successfully use this +package, therefore, you need to run Distiller by using the +\texttt{-F} command line switch. + + +Those using \app{Windows OS} can create a shortcut on the desktop, for example, +that starts \app{Distiller} with the \texttt{-F} switch. The \uif{Target} of the shortcut might read +\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] +"C:\Program Files (x86)\Adobe\ + Acrobat 9.0\Acrobat\acrodist.exe" -F +\end{Verbatim} +where we have wrapped the path to the next line to fit within the margins. +Once \app{Distiller} is started with \texttt{-F}, the switch remains in effect +until \app{Distiller} is closed. + +If this package is used to create file attachment annotations without the +\texttt{-F} switch, you typically get the following error message in +the Distiller log file +\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small] +%%[ Error: undefinedfilename; OffendingCommand: file ]%% +\end{Verbatim} +This tells you that either you have not started Distiller with the +\texttt{-F} command line switch, or Distiller can't find one of the +files that the \textbf{file} operator was trying to read. + + + +\newtopic \textbf{Mac OS Users.} The above comments on the \texttt{-F} command line switch +is for Windows users, Mac OS users must choose the \texttt{AllowPSFileOps} user preference, this is located +in the \texttt{plist}, possibly located at +\begin{Verbatim}[fontsize=\small] +/Users/[User]/Library/Preferences/com.adobe.distiller9.plist +\end{Verbatim} +You can also use Spotlight, the search utility on Mac, to search for the string \texttt{com.adobe.distiller}; +the result might be +\begin{quote} +\texttt{com.adobe.distiller9.plist}.\footnote{In the case of Adobe Distiller, version 9.0} +\end{quote} +Clicking on this find, +Spotlight opens \texttt{com.adobe.distiller9.plist} in the \texttt{plist} editor, see \hyperref[plist]{Figure~\ref*{plist}}. +If necessary, click on the arrow next to the Root to expand the +choices, then click the up and down arrows at the far +right in the \texttt{AllowPSFileOps} row to select Yes as the value. +\begin{figure}[hbt]\setlength{\fboxsep}{0pt} +\begin{center} +\fbox{\includegraphics[width=.75\linewidth]{plistEditor}} +\caption{com.adobe.distiller9.plist}\label{plist} +\end{center} +\end{figure} + +\section{The \texorpdfstring{\protect\cs{annotpro}}{\CMD{annotpro}} Command} + +The main command of this package is \Com{annotpro}; the command is controlled by +its optional parameters. The same command can create a text annotation (sticky note), +a stamp annotation, a file attachment or a Free Text (Text Box) annotation. The syntax of this command is +\bVerb\takeMeasure{\string\annotpro[\ameta{KV-pairs}]\darg{\ameta{text}}}% +\begin{minipage}{\linewidth} +\begin{minipage}{\bxSize} +\xdef\panelWidth{\the\linewidth}% +\begin{Verbatim}[frame=single,commandchars=!()] +\annotpro[!ameta(KV-pairs)]{!ameta(text)} +\end{Verbatim} +\end{minipage}\hfill +\begin{minipage}{\linewidth-\panelWidth} +\setDisplayNumber\label{display:arbproCmd} +\end{minipage}\end{minipage}\eVerb +\PD The optional argument is one or more key-value pairs that describe the +annotation; the required argument, \ameta{text}, is the ``contents'' of the +annotation; for the text and stamp annotation, \ameta{text} becomes the +contents of the popup annotation, for a file attachment annotation, which has +not associated pop-up, it is the description of the file attachment that +appears in the file attachment panel of Adobe Reader. In the latter case, the +value of \ameta{text} should be rather short. The key-value pairs (\ameta{KV-pairs}) are +described over the next few sections. + +\paragraph*{\color{red}Sample files.} The sample files \texttt{annots.tex} and \texttt{textbox.tex} illustrate the features +of the \pkg{annotpro} package. + +\subsection{Key-values common to all annotations}\label{s:CommonKeys} + +The following are key-value pairs common to all annotations. + +\begin{itemize} + \item \texttt{type=\ameta{\upshape{text|stamp|fileattachment|textbox}}} The \texttt{type} key determines the type of annotation to be produced; + permissible values are \texttt{text}, \texttt{stamp}, and \texttt{fileattachment}. This + key is optional, if not present, \texttt{type=text} is assumed. + \item \texttt{name=\ameta{name}} The name of the icon to use for the declared \texttt{type}. Permissible + values are dependent on the \texttt{type}, and are discussed in subsequent sections. + \item \texttt{title=\ameta{text}} Text to be displayed in the title bar of the annotation's pop-up window + when open and active. By convention, this entry identifies the user who made the annotation, + though any (short) text may be used. You can use \cs{setAnnotOptions} to globally set + the title of each annotation, perhaps using your name. +\begin{Verbatim}[fontsize=\small] + \setAnnotOptions{title={D. P. Story}} +\end{Verbatim} + \item \texttt{subject=\ameta{text}} Text representing a short description of the subject of the annotation. + You can use \cs{setAnnotOptions} to globally set the subject of each annotation, +\begin{Verbatim}[fontsize=\small] + \setAnnotOptions{title={D. P. Story}, + subject={AcroTeX Communiqu\'e}} +\end{Verbatim} + \item \texttt{color}: The color of the title bar of the pop-up window of the annotation. + \item \texttt{readonly=\ameta{\upshape{true|false}}} Set the annotation to readonly. The user can click on the annot to + see the popup, but the user, if using Acrobat, cannot move the annotation around on the page. + The popup window can still be move by the user. (This property makes no difference to the + user of Adobe Reader.) + \item \texttt{opacity=\ameta{dec}}: The opacity value ($ + \text0\le\text{\ameta{dec}}\le\text1$) to be used in painting the (icon of + the) annotation, but does apply to the pop-up window. The default + is 1.0. + \item[] Adobe Distiller handles the opacity for us in all cases except when we create a (dynamic) stamp. + If an opacity value less than 1 is desired, special techniques are needed, and the file needs to + be distilled using the \textbf{Standard\_tranparency} job options. + +\end{itemize} +The following key-values are {\LaTeX} based concerning placement of the annotation in the margin. +\begin{itemize} + \item \texttt{margin}: Use this key (it has no value), to declare that you want the annotation + to appear in the margin. The \cs{marginpar} command from core {\LaTeX} is used, the placement + of the annotation follows the rules set down by {\LaTeX}. You can reverse the placement of the + annotation by using the {\LaTeX} command \cs{reversemarginpar} (annots placed in the right margin, and now placed in the left); + you can return to the default by using \cs{normalmarginpar}. + + \item[] Given that you have use the \texttt{margin} key, there is an associated key that can be used, as well + as a command. + \begin{itemize} + \item \texttt{margintext}: The value of this key is text that will be typeset just below the annotation icon. + \item \cs{marginpartextformat}: A {\LaTeX} command for + formatting the text in the margin, the default definition is\smallskip +\begin{Verbatim} +\margintextformat{\bfseries\tiny\color{blue}} +\end{Verbatim} + \end{itemize} + \item[] For an annotation placed in the margin with margin text, you might want to use the \texttt{readonly} + key, this prevents the user---even one using Acrobat---from moving the annotation away from its caption. +\end{itemize} +The following key-value is for your convenience. +\begin{itemize} + \item \texttt{presets}: A key to allow the introduction of pre-defined options, for example, + you might like all your comment annotations to be red, so you can define +\begin{verbatim} + \def\myComments{type=text,name=Comment,color=red} +\end{verbatim} +then say +\begin{verbatim} + \annotpro[presets=\myComment]{Way to go!} +\end{verbatim} +Additional options may be included, +\begin{verbatim} + \annotpro[presets=\myComment,margin]{Way to go!} +\end{verbatim} +for example. + +\end{itemize} + +\subsection{Key-values for text annotations} + +The position of the annotation is determined by its bounding rectangle; for the +text annotation, an icon is placed so that its upper left corner is at the upper +left corner of the bounding rectangle. The icons themselves have certain dimensions +that have been recorded within the \texttt{annot\_pro} package, so you need not worry +about leaving space for them. + +An important fact about the icons used by text annotation is that they \emph{do not zoom in or out} as the page +magnification is changed; furthermore, the graphics commands \cs{scalebox} and \cs{resizebox} do not rescale +the icons as expected. + +The following are options specific to the text annotation. Recall, the text annotation +is of \texttt{type=text}. +\begin{itemize} + \item \texttt{name}: The name of the icon to use when displaying this annotation in closed form (no pop-up window visible). + Possible values---as specified in the \textsl{PDF Reference}---are + \texttt{Comment}, \texttt{Key}, \texttt{Note}, \texttt{Help}, + \texttt{NewParagraph}, \texttt{Paragraph}, and \texttt{Insert}. + Additional icons that are available in recent versions of Adobe + Reader are +\begin{quote}\raggedright + \texttt{Check}, \texttt{Circle}, \texttt{Cross}, \texttt{Star}, \texttt{RightArrow}, \texttt{RightPointer}, + \texttt{UpArrow}, \texttt{UpLeftArrow} +\end{quote} + If you are using comments in your document, and your audience have + older versions of Adobe Reader, it is best to use only the seven + listed in the \textsl{PDF Reference}. + + \item \texttt{open}: A Boolean value that determines whether the pop-up + window is open or not. When \texttt{true} the pop-up is open. The + package default is \texttt{false}. You can use \cs{setAnnotOptions} + to set this option globally. + + \item \texttt{nohspace}, \texttt{novspace}, \texttt{nospace}: The + presence of these commands zeroes out the dimension(s) of the + bounding rectangle. Specifying \texttt{nohspace} as an option + causes the icon to take up no horizontal space as the page is + latexed. Here\annotpro[nohspace]{This a sticky note with the + nospace option} is an example of a sticky note with the + \texttt{nohspace} option. Without any of these three keys, the text + annotation \annotpro[type=text,name=Key]{A sticky note that takes + up TeX space. If you put the document into 100\% magnification, + you'll see the note fits precisely into the allotted space.} fits + exactly into the allotted space at + \setLinkText[\A{\JS{this.zoom=100;}}\Color{0 .6 0}]{100\% + magnification}, try it. + + When the icon takes up no {\TeX} space, it may cover content on + the page, as it does above. Acrobat users can move the icon + around, but AR users cannot move the icon. The pop-up window is + movable and scalable, but the icon cannot be moved. Therefore, + you must be careful about placement. + + Additional positioning of the icons can be made using standard {\LaTeX} + commands such as \cs{raisebox} and \cs{smash}. For example,\smash{\raisebox{1in}{\annotpro[nospace,color=blue,opacity=.25]{I've raised this annot by 1in. + I've also used the nospace key, the icon does not take up any TeX space.}}} the blue icon above was created by +\begin{Verbatim}[fontsize=\footnotesize] + For example,\smash{\raisebox{1in}\raisebox{1in}{% + \annotpro[nospace,color=blue, + opacity=.25]{...clever message...}}} +\end{Verbatim} +Note that I've set the \texttt{opacity} to .25. + +\end{itemize} + + +\subsection{Key-values for stamp annotations} + +A stamp annotation is similar to a text annotation in the sense that +it has a pop-up window in which the contents of the message is +displayed; however, unlike the text annotation icons, the stamp +appearance by be re-scaled using \cs{scalebox} and \cs{resizebox} of +the graphics package; however, the keys \texttt{scale}, +\texttt{widthTo}, and \texttt{heightTo}, as described below, are the +recommended methods of re-scaling a stamp. + +The following are the key-values associated with this annotation type. + +\begin{itemize} + +\begingroup\raggedright + + \item \texttt{name}: The stamps listed in the \textsl{PDF + Reference} are \texttt{Approved}, \texttt{AsIs}, + \texttt{Confidential}, \texttt{Departmental}, \texttt{Draft}, + \texttt{Experimental}, \texttt{Expired}, \texttt{Final}, + \texttt{ForComment}, \texttt{ForPublicRelease}, + \texttt{NotApproved}, \texttt{NotForPublicRelease}, + \texttt{Sold}, and \texttt{TopSecret}. If \texttt{name} + is not specified, \texttt{Draft} is the default.\par\endgroup + + \item[] There are other stamps, not listed in the \textsl{PDF + Reference}, but available in more recent versions of Acrobat. + The file \texttt{stamps.pdf} lists all the stamps that I have + access to. The names of these other stamps are recognized by the + \texttt{name} key. + + \item[] The dimensions of the stamps listed above are all the + same, they are \texttt{150bp} width and \texttt{40bp} high. + + \item[] Additional stamps are shipped by Acrobat, a listing of these + appears in the file \texttt{stamps.pdf} (\texttt{stamps.tex}). + + \item\texttt{width}, \texttt{height}: If the value of + \texttt{name} key is something other than one of the stamps + listed above (one of the stamps listed in the file + \texttt{stamps.pdf}), the width and height are not known to + \textsf{annot\_pro}. In this case, use the \texttt{height} and \texttt{width} keys + to set the dimensions of the bounding box. Adobe Distiller will + resize the stamp to the stamp is the largest one that can fit in + the bounding box, the stamp will be centered vertically and + horizontally within the bounding box. + + \item[] Here are a couple of examples, the bounding box is should as a black \cs{fbox}. + +\begin{itemize} + +\previewtrue + + \item This one \annotpro[type=stamp,name=SBApproved,widthTo=106bp,color=webbrown]{This package just got better!} + fits more or less exactly. I determined the dimensions of this stamp through some controls of the user interface. + Contrast this this stamp + \annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!} + obtained by setting \texttt{width=50bp} and \texttt{height=50bp}. Notice the ``best fit,'' and that the bounding + box takes up space. We can use \cs{smash} to smash its vertical height, let's see how that looks, + \smash{\annotpro[type=stamp,width=50bp,height=50bp,name=SBApproved,color=webbrown]{This package just got better!}} + +\smallskip + +\begin{defineJS}{\annotstampi} +Exact fit: +\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!} +\end{defineJS} +\begin{defineJS}{\annotstampii} +Bad rectangle, but stamp fits the best it can: +\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!} +\end{defineJS} + +\previewfalse + + \item[] The code for producing these stamps are given in the margins. + \annotpro[margin,readonly,margintext={\centering Good Fit}]{\annotstampi}% + \annotpro[margin,readonly,margintext={\centering Bad Fit}]{\annotstampii}% + +\begin{defineJS}{\annotstampiii} +Resize using \\resizebox. \\raisebox was used to lift the same up a little: +\\raisebox{4pt}{\\resizebox{.5in}{!}{\\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}} +\end{defineJS} + + \item[] You can resize these stamps using \cs{scalebox} and \cs{resizebox}, like so. + \raisebox{4pt}{\resizebox{.5in}{!}{\annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!}}} + \enspace The code for producing this stamp are given here \annotpro{\annotstampiii}. + +\begin{defineJS}{\annotstampiv} +\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I give my stamp of approval!}}} +\end{defineJS} + +\item To create a stamp\smash{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,color=blue]{I give my stamp of approval!}}} that takes up no space, it is easiest to use \cs{smash} and \verb!\makebox[0pt][l]{text}!; + here is one of the standard stamps as listed in the \textsl{PDF Reference}. The code for this stamp is given + in this note \annotpro{\annotstampiv}. +\end{itemize} + +\item[] Try changing the magnification of the page, you'll see that stamps are re-scaled as you zoom in or out, while +the text annotations are not. I don't like text annotations for this reason. + +\begin{defineJS}{\annotstampv} +\\annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This is the best picture of me ever taken. Akron, about 2005.} +\end{defineJS} + +\item\texttt{rotate}: Stamps can be rotated, use this key to enter an angle of rotation, for example, + \texttt{rotate=30} rotates the stamp $\text{30}^\circ$ counter clock-wise. + +\item[\textcolor{red}{\ding{043}}] Do not use the \cs{rotatebox} command of \textsf{graphics} package, +this command \emph{does not rotate} the stamp. + +\item \texttt{scale}: Use this key to re-scale the stamp; the value of this key is a number between + 0 and 1. For example, \texttt{scale=.5} reduces both width and height in half. +\item \texttt{widthTo}: This key resizes the stamp so that the width is the value of this key; for example, + \texttt{widthTo=2in} re-scales the stamp to have a 2in width. +\item\texttt{heightTo}: This key resizes the stamp so that the height is the value of this key; for example, + \texttt{heightTo=2in} re-scales the stamp to have a 2in height. + +\item[] Only one of the keys \texttt{scale}, \texttt{widthTo}, and \texttt{heightTo} are recognized + for any stamp annotation. If all three are specified, only \texttt{scale} is used. If + \texttt{widthTo} and \texttt{heightTo} are both specified, then \texttt{widthTo} is used. + +\item[\textcolor{red}{\ding{043}}] The use of these keys is the recommend way of re-scaling +a stamp. These methods are compatible with the \texttt{rotate} key. + +\item \texttt{customStamp}: You can create a custom stamp from any + image you wish to use, here is + \annotpro[type=stamp,customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{This + is the best picture of me ever taken. Akron, about 2005.} one such + example. The code for the above stamp is given here + \annotpro{\annotstampv}. + +\item \texttt{ap}: When the \texttt{\texttt{customStamp}} key is + used, you have to supply an indirect reference to the appearance of + the stamp. This reference is made through the \texttt{ap} key. The + example above demonstrates the use of the \texttt{ap} key. +\end{itemize} +\textbf{\textcolor{red}{Important:}} When using the stamps of +\app{Acrobat} always perform a \uif{SaveAs} on the file when you have finished +building the file. This imports the appearances of the stamps into +the document and saves them. + +\redpoint The creation of a custom stamp requires detailed list of steps, at +some point I'll write a white paper on the subject.\footnote{Use the \pkg{mkstmp} package +(\href{http://ctan.org/pkg/mkstmp}{ctan.org/pkg/mkstmp}), +details of how to create custom stamps are included in the documentation.} + +\begin{defineJS}{\approvedStmp} +\\annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{...} +\end{defineJS} + +\newtopic +Here's an example of the keys \texttt{rotate} and \texttt{widthTo}: +\begin{center} + \annotpro[type=stamp,name=Approved,widthTo=2in,rotate=30]{The source for this + stamp is ...\string\r\approvedStmp} +\end{center} + +\subsection{Key-values file attachment annotations} + +The file attachment annotation has no pop-up window, the value of the required parameter is used as a description +of the attached file, and appears in the file attachment window. + +The key-value pairs special to this type of annotation are as follows. + +\begin{itemize} + \item\texttt{name}: The name of the icon to use, permitted values are + \texttt{Graph}, \texttt{Paperclip}, \texttt{PushPin}, and \texttt{Tag}. If the value of name is not + specified, the default is \texttt{PushPin}. The annot\_pro package knows the dimensions of each of these + icons, so you need not worry about them. They can be re-scale using standard commands from the graphics package, + though, there may be little need of doing so. + \item \texttt{file}: The value of the file key is the \emph{absolute path} to the file to be attached. I've + devised a helper command \Com{defineAPath} that can be used to define the path to your file. For example, we can + define a path to wherever the files are, like so +\begin{Verbatim}[fontsize=\footnotesize] + \defineAPath{\graphicsPath} + {C:/Users/Public/Documents/My TeX Files/% + tex/latex/aeb/aebpro/annot_pro/examples/graphics} +\end{Verbatim} +\item[] The command takes two arguments, the name of the command to be defined, and the path. + +\defineAPath{\graphicsPath}{C:/Users/Public/Documents/My TeX Files/tex/latex/aeb/aebpro/annot_pro/examples/graphics} + +\begin{defineJS}{\fa} +\\annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The author of annot\_pro (ho, ho).} +\end{defineJS} + +\item[] We can create a file attachment + \annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The + author of annot\_pro (ho, ho).} like so, ho, ho. Here is the code + for this file attachment \annotpro[name=Star]{\fa}. Clicking the + file attachment icon will open the file, in recent versions of + Acrobat, the file is listed in the file attachments panel. Open it + using the user interface, and you'll see the file listed, as well + as a description, as passed to the annot as the second argument of + \cs{annotpro}. +\end{itemize} + +The file attachment icons can be resized using any of the graphics commands, \cs{scalebox} or \cs{resizebox}. + +\subsection{The \texorpdfstring{\protect\uif{Text Box}}{Text Box} + (\texorpdfstring{\protect\uif{Free Text}}{Free Text}) annotation} + +A \uif{Text Box} annotation is a rectangular region in which the user can +enter rich text. The annotation may be created and `pre-populated' with rich text from a +{\LaTeX} source through the \pkg{annot\_pro} package. + +The \uif{Text Box} annotation, as implemented by this package, requires the +\pkg{richtex} package, dated 2016/09/30 or later. A one simple method for +introducing \pkg{richtext} is through the \opt{useTextBox} option of +\pkg{annot\_pro}. Placing the following line in the preamble: +\begin{Verbatim}[xleftmargin=\amtIndent] +\usepackage[useTextBox]{annot_pro} +\end{Verbatim} +declares you are going to use \uif{Text Box} annotations. The option does +nothing more than to execute \cs{usepackage\darg{richtext}[2016/09/30]}. The +option is more of a convenience. + +To create a \uif{Text Box} (originally named \uif{Free Text}) annotation use the \cs{annotpro} command. +\bVerb\begin{minipage}{\linewidth} +\begin{minipage}{3.5in} +\xdef\panelWidth{\the\linewidth}% +\begin{Verbatim}[xleftmargin=\leftmargini,commandchars=!(),fontsize=\small] +\annotpro[!textbf(type=textbox),!ameta(KV-pairs)] + {richtext=!ameta(name),defstyle=!ameta(name)} +\end{Verbatim} +\end{minipage}\hfill +\begin{minipage}{\linewidth-\panelWidth} +\setDisplayNumber\label{display:textbox} +\end{minipage}\end{minipage}\eVerb +Notice the second argument is not \ameta{text} as it is with the other annotations, but consists +of key-value pairs; recognized keys are \texttt{richtext} and \texttt{defstyle}. + +\newtopic\noindent The sample file \texttt{textbox.tex} illustrates the features of this section. + +\subsubsection{Creating an empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}} + +A common application would be to create an empty \uif{Text Box} for the +document consumer to type in comments. Below is an example of a \uif{Free +Text} annotation, called \uif{Text Box} by the user-interface of +\app{Acrobat}/\app{Adobe Reader}. +\begin{flushleft} %\previewtrue +\begin{minipage}{2in} +\annotpro[title=dpstory,type=textbox,subject=Empty Text Box]{} +\end{minipage}\hfill +\begin{minipage}{\linewidth-2in-10pt}\small +Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to obtain +the \uif{Properties} toolbar, now click on the text box to obtain the +\uif{Text Box Properties} toolbar. Double clicking on the text box +brings up the \uif{Text Box Text Properties} toolbar. +\end{minipage} +\end{flushleft} +The verbatim listing of the above \uif{Text Box} is, +\begin{Verbatim}[xleftmargin=\leftmargini] +\annotpro[type=textbox, + title=dpstory,subject=Empty Text Box]{} +\end{Verbatim} +The required second argument is empty, which leads to an empty \uif{Text Box}. + +\subsubsection{Creating a non-empty \texorpdfstring{\protect\uif{Text Box}}{Text Box}} + +A much more interesting exercise is to pre-populate the \uif{Text Box} with rich text for the +document consumer to read and/or to respond. + +\paragraph[Steps to create rich text content]{Steps to create rich text content.}\chgCurrLblName{Steps to create rich text content}\label{para:StepsRC} +We briefly outline the techniques to create rich text +for a \uif{Text Box} annotation. +\begin{itemize} + \item Use the \env{textboxpara} environment and the \cs{rtpara} command + to declare your rich text paragraph. +\bVerb\takeMeasure{\string\rtpara[\ameta{KV-pairs}]\darg{\ameta{name\SUB{para}}}\darg{\ameta{rich-content}}}% +\begin{minipage}{\linewidth} +\begin{minipage}{\bxSize} +\xdef\panelWidth{\the\linewidth}% +\begin{Verbatim}[frame=single,commandchars=!()] +\begin{textboxpara} +\rtpara[!ameta(KV-pairs)]{!ameta(name!SUB(para))}{!ameta(rich-content)} +... +\end{textboxpara} +\end{Verbatim} +\end{minipage}\hfill +\begin{minipage}{\linewidth-\panelWidth} +\setDisplayNumber\label{display:rtpara} +\end{minipage}\end{minipage}\eVerb +Details of the \cs{rtpara} command are found in the documentation manual of +the \pkg{richtext} package. The \env{textboxpara} environment is needed for +certain redefinitions of internals because of the different way rich text +is supported and implemented in the \uif{Text Box} annotation verses the +rich text field. + +\item Use the \cs{setRVVContent} command on your \cs{rtpara}-declared rich text and give it +a name \ameta{name\SUB{rvvc}}. +\bVerb\takeMeasure{\string\setRVVContent\darg{\ameta{name\SUB{rvvc}}}\darg{\ameta{name\SUB{para}}}}% +\begin{minipage}{\linewidth} +\begin{minipage}{\bxSize} +\xdef\panelWidth{\the\linewidth}% +\begin{Verbatim}[frame=single,commandchars=!()] +\setRVVContent{!ameta(name!SUB(rvvc))}{!ameta(name!SUB(para))} +... +\end{Verbatim} +\end{minipage}\hfill +\begin{minipage}{\linewidth-\panelWidth} +\setDisplayNumber\label{display:setRVVC} +\end{minipage}\end{minipage}\eVerb +This command expands the paragraph named \ameta{name\SUB{para}} and +develops the rich text version and the plain text version. It is +\ameta{name\SUB{rvvc}} that is used as a value for the \opt{richtext} key +above and illustrated below. To reduce the number of names, you can use +the same name for \ameta{name\SUB{rvvc}} as for \ameta{name\SUB{para}} +(\cs{setRVVContent\darg{para1}\darg{para1}}). + +The rich text \emph{form field} supports multiple paragraphs, and richer +formatting options than the \uif{Text Box} annotation. Of importance is +that the \uif{Text Box} annotation only permits a \emph{single paragraph}. + +\item (Optional) Declare a (named) default style using \cs{setDefaultStyle}: +\bVerb\takeMeasure{\string\setDefaultStyle\darg{\ameta{name\SUB{ds}}}\darg{\ameta{KV-pairs}}}% +\begin{minipage}{\linewidth} +\begin{minipage}{\bxSize} +\xdef\panelWidth{\the\linewidth}% +\begin{Verbatim}[frame=single,commandchars=!()] +\setDefaultStyle{!ameta(name!SUB(ds))}{!ameta(KV-pairs)} +... +\end{Verbatim} +\end{minipage}\hfill +\begin{minipage}{\linewidth-\panelWidth} +\setDisplayNumber\label{display:setDefStyle} +\end{minipage}\end{minipage}\eVerb +This default style is assignment a name that is used as the value of the +\opt{defstyle} key mentioned earlier, and illustrated below. If a value for +\opt{defstyle} is not provided, a standard default style is used. + +\end{itemize} +Once the \cs{rtpara}-declared paragraphs have been made and their names have passed through +\cs{setRVVContent}, you are ready to create a \uif{Text Box} annotation. + +\paragraph[Key-values for second argument]{Key-values for second argument.}\chgCurrLblName{Key-values for second argument}\label{para:KV2ndArg} +The required second argument, refer to display~\eqref{display:textbox}, has +two keys, both of which are optional. You are encouraged to read the +documentation for the \pkg{richtext} package for greater understanding of the +descriptions and examples found below. +\begin{description} + \item[\texttt{richtext=\ameta{name\SUB{rvvc}}}] The \opt{richtext} key + is the way the rich text is passed to the \uif{Text Box}. The + \ameta{name\SUB{rvvc}} is declared by the \cs{setRVVContent} + command. Use the command \cs{rtpara} within the \env{textboxpara} + environment to define the actual rich text paragraph. For example, +\begin{Verbatim}[fontsize=\small,commandchars=!()] +\begin{textboxpara} +\rtpara{para1}{\span{color=FF0000}{Hello world}, + this is \bf{rich text}!} +\end{textboxpara} +\setRVVContent{myContent}{para1} +\annotpro[type=textbox,title=dpstory, + subject=Text Box]{!textbf(richtext=myContent)} +\end{Verbatim} +The above code produces the following \uif{Text Box}: +\begin{quote} +\begin{textboxpara} +\rtpara{para1}{\span{color=FF0000}{Hello world}, + this is \bf{rich text}!} +\end{textboxpara} +\setRVVContent{myContent}{para1} +\annotpro[type=textbox,title=dpstory, + subject=Text Box]{richtext=myContent} +\end{quote} + + \item[\texttt{defstyle=\ameta{name\SUB{ds}}}] Through the + \opt{defstyle} you can define set the default style (refer to the + documentation of the \pkg{richtext} package. If this key does not + appear, then a predefined default style is provided. +\begin{Verbatim}[fontsize=\small,commandchars=!()] +\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif}, + color=0000FF} +\begin{textboxpara} +\rtpara{para1}{\span{color=FF0000}{Hello world}, + this is \it{rich text}!} +\setRVVContent{para1}{para1} +\end{textboxpara} +\annotpro[type=textbox,title=dpstory, + subject=Text Box]{richtext=para1,!textbf(defstyle=myDS)} +\end{Verbatim} +Notice that we've used the name `\texttt{para1}' for both \cs{setRVVContent} +and \cs{rtpara}. The above code produces the following \uif{Text Box}: +\begin{flushleft}%\previewtrue +\begin{minipage}{2in} +\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif},color=0000FF} +\begin{textboxpara} +\rtpara{para1}{\span{color=FF0000}{Hello world}, + this is \it{rich text}!} +\end{textboxpara} +\setRVVContent{para1}{para1} +\annotpro[type=textbox,title=dpstory, + subject=Text Box]{richtext=para1,defstyle=myDS} +\end{minipage}\hfill +\begin{minipage}{\linewidth-2in-10pt}\small +Press \uif{Ctrl+E} (\app{Windows}) or \uif{Cmd+E} (\app{Mac OS}) to +obtain the \uif{Properties} toolbar, now double click on the text box to +obtain the \uif{Text Box Text Properties} toolbar to verify the font used +is indeed Myriad Pro. +\end{minipage} +\end{flushleft} +\end{description} +If you are at all interested in generating the \uif{Text Box} annotation using rich text +strings, you are encouraged to read the documentation on \pkg{richtext}, +there you will learn about all the key-values available to format the text +and the paragraph. + +The \pkg{richtext} package was written for rich text form fields, but applies +to rich text annotations as well; however, it should be noted that there are +differences between forms and text box annotations in how they handle rich +text. One of the major differences is that rich text annotations (\uif{Text +Box}) \emph{do not support} multiple paragraphs as form fields do; as a +result, features listed in the \uif{Paragraph} and \uif{Link} tabs of the +\uif{Form Field Text Properties} dialog box are not available for the +\uif{Text Box}. + +\paragraph[Keys \& commands inherited from the \texorpdfstring{\protect\pkg{richtext}}{richtext} package]% +{Keys \& commands inherited from the \pkg{richtext} package.}% +\chgCurrLblName{Keys \& commands inherited from the \pkg{richtext} package}\label{para:InheritedKeys} +The following keys are supported by the \uif{Text Box} annotation: +\bVerb\begin{minipage}{\linewidth} +\begin{minipage}[c]{4in} +\xdef\panelWidth{\the\linewidth}% +\begin{quote}\raggedright +\opt{font}, \opt{size}, \opt{\st{raise}}, \opt{ulstyle}, +\opt{color}, \opt{\st{url}}, \opt{style}, \opt{\st{raw}}, \opt{halign} +\end{quote} +\end{minipage}\hfill +\begin{minipage}[c]{\linewidth-\panelWidth} +\setDisplayNumber\label{display:suppKeys} +\end{minipage}\end{minipage}\eVerb +The following commands are supported: +\bVerb\begin{minipage}{\linewidth} +\begin{minipage}[c]{4in} +\xdef\panelWidth{\the\linewidth}% +\begin{quote}\raggedright +\cs{span}, \cs{br}, \cs{it}, \cs{bf}, \cs{sup} and \cs{sub} +\end{quote} +\end{minipage}\hfill +\begin{minipage}[c]{\linewidth-\panelWidth} +\setDisplayNumber\label{display:suppCmds} +\end{minipage}\end{minipage}\eVerb +The ones having an overstrike are supported in a rich text \emph{form field}, but +not within an \uif{Text Box}. Refer to the documentation of the +\pkg{richtext} for details of these keys and commands. In this document, we +illustrate by example. + +\paragraph[Key-values of \texorpdfstring{\protect\cs{rtpara}}{\textbackslash{rtpara}}]{Key-values of \cs{rtpara}.}% +\chgCurrLblName{Key-values of \cs{rtpara}}\label{para:KeysPara} The +keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones -- may be used in the +\ameta{KV-pairs} argument of \cs{rtpara} of display~\eqref{display:rtpara}. + +\paragraph[Permissible commands within \texorpdfstring{\protect\ameta{rich-content}}{<rich-content>}]{% +Permissible commands within \ameta{rich-content}.}\chgCurrLblName{Permissible +commands within \ameta{\ameta{rich-content}}}\label{para:KeysCmdsRC} The +\ameta{rich-content} argument of display~\eqref{display:rtpara} (normally) +consists of Latin 1 characters, plus any markup in the form of the commands +listed in display~\eqref{display:suppCmds}. +\begin{itemize} + \item \cs{span} has two arguments, more on this command in the paragraph below + titled \Nameref{para:Span}. + \item \cs{br} is a line break, it has no argument. + \item \cs{it} is italic font; it has one argument, the text to be + placed in italics: \cs{it\darg{this is italic}}. + \item \cs{bf} is bold font; it has one argument, the text to be placed in bold: + \cs{bf\darg{this is bold}}. + + \cs{it} and \cs{bf} may be nested: \cs{it\darg{\cs{bf\darg{bold and italic}}}}. + + \item \cs{sup} and \cs{sub} are superscript and subscript, respectively; they each + have one argument, the text to be raised or lowered. For example, + \verb~We can \sup{raise} or we can \sub{lower} text~. +\end{itemize} +The above markups, with the exception of \cs{span} are illustrated below. +\begin{defineJS}{\annotextboxi} +\\begin{textboxpara} +\\rtpara{mypara}{\\it{This is italic}, whereas \\bf{this is bold}, but wait, we can do +\\it{\\bf{bold and italic}}.\\br\\br Moving on, we can \\sup{raise} or we can \\sub{lower} text.} +\\end{textboxpara} +\\setRVVContent{mypara}{mypara} +\\annotpro[type=textbox,width=3.5in]{richtext=mypara} +\end{defineJS} +\begin{quote} +\begin{textboxpara} +\rtpara{mypara}{\it{This is italic}, whereas \bf{this is bold}, but wait, we can do +\it{\bf{bold and italic}}.\br\br Moving on, we can \sup{raise} or we can \sub{lower} text.} +\end{textboxpara} +\setRVVContent{mypara}{mypara} +\annotpro[type=textbox,width=3.5in]{richtext=mypara}% +\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}% +\end{quote} +The verbatim listing for this example is in the sticky note in the margin. + +\paragraph[Some comments on the \texorpdfstring{\protect\cs{span}}{\textbackslash{span}} +command]{Some comments on the \cs{span} command.}\chgCurrLblName{Some comments on the \cs{span} command}\label{para:Span} +the \cs{span} command, defined only locally within the \ameta{rich-text} argument \cs{rtspan} is a general purpose +command to format text. It has two argument: +\begin{quote} +\cs{span\darg{\ameta{KV-pairs}}\darg{\ameta{text}}}. +\end{quote} +The \ameta{KV-pairs} argument can be the keys of +display~\eqref{display:suppKeys} (again excluding the overstrike keys). The \ameta{text} argument is the +text to be made rich; experience shows that \cs{it}, \cs{bf}, \cs{sub} and \cs{sup} may be used within +\ameta{text}. Italic and bold may be accomplished using the \opt{style} key, probably preferred over +using \cs{it} and \cs{bf} within \ameta{text}. +\begin{defineJS}{\annotextboxi} +\\begin{textboxpara} +\\rtpara{para1}{Welcome to my \\span{style={strikeit,bold}}{poor}\\span{style=bold}{rich text world}. +We add a little color shall we try \\span{color=FF0000}{red} or \\span{color=00FF00}{green}?\\br\\br +There are several styles of underlining \\span{ulstyle=ul}{basic underlining}, +\\span{ulstyle=2ul}{double underlining}, \\span{ulstyle=wul}{word underlining}, and +\\span{ulstyle=2wul}{double word underlining}. Cool.} +\\end{textboxpara} +\\setRVVContent{para1}{para1} +\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1} +\end{defineJS} +\begin{quote} +\begin{textboxpara} +\rtpara{para1}{Welcome to my \span{style={strikeit,bold}}{poor}\span{style=bold}{rich text world}. +We add a little color shall we try \span{color=FF0000}{red} or \span{color=00FF00}{green}?\br\br +There are several styles of underlining \span{ulstyle=ul}{basic underlining}, +\span{ulstyle=2ul}{double underlining}, \span{ulstyle=wul}{word underlining}, and +\span{ulstyle=2wul}{double word underlining}. Cool.} +\end{textboxpara} +\setRVVContent{para1}{para1} +\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1}% +\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}% +\end{quote} +The verbatim listing for this example is in the sticky note in the margin. + +\paragraph[Key-values of \texorpdfstring{\protect\cs{setDefaultStyle}}{\textbackslash{setDefaultStyle}}]% +{Key-values of \cs{setDefaultStyle}.}% +\chgCurrLblName{Key-values of \cs{setDefaultStyle}}\label{para:KeysDS} The +keys of display~\eqref{display:suppKeys} -- excluding the overstrike ones -- +may be used in the \ameta{KV-pairs} argument of \cs{setDefaultStyle} of +display~\eqref{display:setDefStyle}; however, only the keys \opt{font}, +\opt{size}, \opt{color}, and \opt{halign} are typically used. For example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\setDefaultStyle{myDS}{font={'Myriad Pro',sans-serif}, + size=12.0,color=0000FF,halign=left} +\end{Verbatim} +The name `\opt{myDS}' may then be used as the value of \opt{defstyle} key in the second argument +of \cs{annotpro}, see display~\eqref{display:textbox}. + +\subsubsection{Key-values for text box annotations} + +\hyperref[s:CommonKeys]{Section~\ref*{s:CommonKeys}} lists keys that are +common to all annotations; we list the ones that make sense for the \uif{Text +Box} annotation, and strikeout these that do not: +\begin{quote}\raggedright +\texttt{type}, \texttt{\st{name}}, \texttt{title}, \texttt{subject}, +\texttt{\st{color}}, \texttt{readonly}, \texttt{opacity}, \texttt{margin}, +\texttt{presets} +\end{quote} +In addition to these keys, there are several keys particular to the text box +annotation. We list these and describe them in detail. +\begin{itemize} + \item \texttt{width=\ameta{length}}: The width of the annotation, the + default is \texttt{144bp} (\texttt{2in}). + \item \texttt{height=\ameta{length}}: The height of the annotation, the + default is \texttt{72bp} (\texttt{1in}). + \item \texttt{bgcolor=\ameta{color}} The color to be used as the background color + of the text box annotation. If \opt{bgcolor} has no value, transparent color is used. + The default is white. + \item \texttt{bcolor=\ameta{color}} The color to be used as the boundary color of the + annotation. The default is black. + \item \texttt{borderstyle=\ameta{choice}}: This keys determines the + style of border to be used. It is a choice key, choices are + \texttt{none}, \texttt{solid}, \texttt{dash1}, \texttt{dash2}, + \texttt{dash3}, \texttt{dash4}, \texttt{dash5}, \texttt{dash6}, + \texttt{cloud1}, and \texttt{cloud2}. The default is \texttt{solid}. + \item \texttt{borderwidth=\ameta{choice}}: The border width of the + annotation, acceptable choices are \texttt{.5}, \texttt{1}, \texttt{2}, + \texttt{3}, \texttt{4}, \texttt{6}, 8, and \texttt{10}. The default is \texttt{1}. +\end{itemize} +\begin{textboxpara} +\rtpara{para1}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=14bp*2, bgcolor=cornsilk, +bcolor=blue]{richtext=para1}}}\setRVVContent{para1}{para1} +\rtpara{para2}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=16bp*3, bgcolor, bcolor=red, +borderstyle=dash2, borderwidth=2]{richtext=para2}}}\setRVVContent{para2}{para2} +\rtpara{para3}{\cs{annotpro[type=textbox, width=\cs{linewidth}, height=18bp*3, bcolor=red, +borderstyle=cloud1]{richtext=para3}}}\setRVVContent{para3}{para3} +\end{textboxpara}%\previewtrue +\setDefaultStyle{myDS}{font=Courier,size=12.0,color=000000} +\annotpro[type=textbox, width=\linewidth, height=14bp*2, bgcolor=cornsilk, bcolor=blue]{richtext=para1,defstyle=myDS}\\[6bp] +\annotpro[type=textbox, width=\linewidth, height=16bp*3, bgcolor, bcolor=red, borderstyle=dash2, borderwidth=2]{richtext=para2,defstyle=myDS}\\[6bp] +\annotpro[type=textbox, width=\linewidth, height=18bp*3, bcolor=red, borderstyle=cloud1]{richtext=para3,defstyle=myDS}\\[6bp] +The second text box annotation above has transparent background color. Using your pointing device, move it around to verify +the background is `see through', compare with the other two by moving them around, not `see through'. + +\subsubsection{Accented glyphs and the unicode characters} + +There are several advantages that text box annotation have over rich text +form fields: movability and unicode. An annotation can be moved around the +page by the user quite easily, a form field typically cannot unless the user +is using \app{Acrobat}. Also, when it comes to using unicode, text box +annotations are far superior to rich text form fields. Unicode characters may +be inserted using the convenience commands \cs{uHex} and \cs{uDec}, where the +first take a hex code as its argument and the second takes a non-negative +integer as its argument. Latin1 accented characters can be entered using octal notation +for example, \verb~J\374rgen~ +\begin{defineJS}{\annotextboxi} +\\begin{textboxpara} +\\rtpara{para1}{J\\374rgen is a nice fellow, though I've never met him.\\br\\br +We've communicated, J\\uHex{00FC}rgen and I, via email. J\\uDec{252}rgen where are you?} +\\end{textboxpara} +\\setRVVContent{para1}{para1} +\\annotpro[type=textbox,width=4.5in,height=14bp*7]{richtext=para1} +\end{defineJS} +\begin{textboxpara} +\rtpara{para1}{J\374rgen is a nice fellow, though I've never met him.\br\br +We've communicated, J\uHex{00FC}rgen and I, via email. J\uDec{252}rgen where are you?} +\end{textboxpara} +\begin{quote}%\previewtrue +\setRVVContent{para1}{para1} +\annotpro[type=textbox,width=4in,height=16bp*4]{richtext=para1}% +\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}% +\end{quote} +But wait, we're not done. In theory, we can access any unicode character through the use +of \cs{uHex} or \cs{uDec}. I'll randomly pick off some unicode characters. +\begin{defineJS}{\annotextboxi} +\\begin{textboxpara} +\\rtpara{para1}{% +\\uHex{01A2}, \\uHex{023E}, \\uHex{03A3}, \\uHex{0416}, +\\uHex{0583}, \\uHex{06A6}, \\uHex{263A}, \\uHex{FB21}, +\\uHex{82A0}, \\uHex{4EE4}, \\uHex{F92C}, \\uHex{5475}} +\\end{textboxpara} +\\setRVVContent{para1}{para1} +\\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1} +\end{defineJS} +\begin{textboxpara} +\rtpara{para1}{% +\uHex{01A2}, \uHex{023E}, \uHex{03A3}, \uHex{0416}, +\uHex{0583}, \uHex{06A6}, \uHex{263A}, \uHex{FB21}, +\uHex{82A0}, \uHex{4EE4}, \uHex{F92C}, \uHex{5475}} +\end{textboxpara} +\begin{quote}%\previewtrue +\setRVVContent{para1}{para1} +\annotpro[type=textbox,width=4in,height=14bp*2]{richtext=para1}% +\annotpro[margin,readonly,margintext={\centering The Code}]{\annotextboxi}% +\end{quote} +Cool! + + +\subsection{Setting Global Options with + \texorpdfstring{\protect\cs{setAnnotOptions}}{\CMD{setAnnotOptions}}} + +Global options are by using the \cs{setAnnotOptions} command. +In the preamble of this document I placed +\begin{Verbatim}[fontsize=\footnotesize] +\setAnnotOptions{subject={AcroTeX Communiqu\'e},title={D.P. Story}} +\end{Verbatim} +That way, I didn't have to constantly type in my personal name for each example. These options can be overwritten +by specifying options locally, if I say, \cs{annotpro[author=Don Story]\darg{Hi there!}}, the author is now my +alter ego, Don Story. + +%\redpoint\textbf{\textcolor{red}{Important:}} Certain key, \texttt{name}, should not be used to set global options, +%\cs{setAnnotOptions} tests for these, and puts them back to their default values that are expected +%by \cs{annotpro}. These keys should only be used for passing options to \cs{annotpro} in its option list. + + +\bigskip +\noindent +That's all for now, I simply must get back to my retirement. \dps\space\annotpro[type=stamp, + customStamp=MyDPSImage,ap=AdobeDon,color=webbrown]{% + Did I say that I had to get back to my retirement?} + +\end{document} |