\documentclass{article}
\usepackage[%
    web={tight,usesf,usetemplates},
]{aeb_pro}
\usepackage[scandoc]{annot_pro}

\title{The \textsf{annot\_pro} Package\texorpdfstring{\\[2ex]}{: }Text, Stamp, and File Attachment Annotations}
\author{D. P. Story}
\university{Acro\negthinspace\TeX.Net}
\email{dpstory@acrotex.net}
\subject{Acrobat text, stamp, and file attachment annotations}
\keywords{AcroTeX, AeB Pro, Acrobat annotations}

\textBgColor{webyellow}

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

\margins{.5in}{.5in}{24pt}{.25in} % left,right,top, bottom
\screensize{4.5in}{6in} % height, width

\def\myNote{type=text,name=Note,color=webyellow}
\newcommand{\cs}[1]{\texttt{\char`\\#1}}

%
% This needs to be set to the path to the graphics folder
%
\defineAPath{\graphicsPath}{C:/Users/Public/Documents/My TeX Files/%
    tex/latex/aeb/aebpro/annot_pro/examples/graphics}

\marginparsep=6pt
\marginparwidth=.25in
\parskip6pt
\parindent0pt

\reversemarginpar

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

\begin{document}

\maketitle

\section{Introduction}

This is a  brief demo package for the \textsf{annot\_pro} package. This package uses
Adobe Distiller to distill PostScript files created by dvips (or dvipsone) to produce
a selection of useful annotations, the ones for text (also called sticky notes), stamps,
and file attachments. We take up each of these annotation types in that order. The command
to create all types of supported annotation is \cs{annotpro}. The syntax is\dots
\begin{verbatim}
    \annotpro[<key-values>]{<content>}
\end{verbatim}
There are several keys that are common to all annotations, among
these are \texttt{title} (whose value is usually the author of the
annotation), and \texttt{subject}. The \texttt{<content>} argument
is the text of the pop-up window (in the case of text and stamp
annotations), and the file attachment description (for file
attachment annotations).For example, \annotpro[title=Don Story,subject=AcroTeX.Net]{This is the content of the sticky note.}; the code is
\begin{verbatim}
    \annotpro[title=Don Story,subject=AcroTeX.Net]
        {This is the content of the sticky note.}
\end{verbatim}

See the documentation for this package, \texttt{annotpro\_man.pdf}, for details
beyond what is presented here.

\section{Text annotations}

There are a number of difference text annotation icons that can be used. The default
is the \texttt{Note} annotation \annotpro{This is a Note annotation, or sticky note.}. The
type of annotation is selected using the \texttt{type} key, text
annotations are \texttt{type=text} (the default). An icon is selected using the \texttt{name} key.
The above annotation is the default \texttt{name=Note}; consequently, the syntax is very simple:
\begin{verbatim}
    \annotpro{This is a Note annotation, or sticky note.}
\end{verbatim}
The default behavior is to leave the correct vertical and horizontal space in {\TeX} space to
place the icon. The icons of a text annotation do not re-scale, they remain the same size regardless
of the page magnification; consequently, they look best when the magnification is at 100\%.

There are keys (\texttt{nohspace}, \texttt{novspace}, and  \texttt{nospace}) for removing
space around the icon in {\TeX} space.

This is a sticky note that takes that uses the \texttt{\texttt{nohspace}} key.\makebox[0pt][r]{\raisebox{10bp}{\annotpro[name=Comment,nohspace]{J\"{u}rgen is a cool guy!}}\hspace{6bp}}
The sticky note retains vertical space. For sticky notes, there are three keys for removing space,
\texttt{nohspace}, \texttt{novspace}, and  \texttt{nospace}. Acrobat users can move these icons around
on the page, but users of Adobe Reader cannot; therefore, if an annot is to be used, it should not cover
any page content. You can see the additional space left between paragraphs, this space was created
by the vertical space of the note.  Here,\annotpro[name=Comment,nospace,color=blue]{J\"{u}rgen is a cool guy!} the blue note, is the same note with the \texttt{nospace} key.

Annots can be placed in the margin\annotpro[presets=\myNote,margin,readonly,margintext={Hi\\Mom!}]{This one appears in the margin of the document.}
using the \texttt{margin} key, with an optional ``caption.'' The core {\LaTeX} command \cs{marginpar} is used. This particular
annotation uses the \texttt{presets} key, this key allows you to predefine some options. The code for the margin note is
\begin{verbatim}
    \annotpro[presets=\myNote,margin,readonly,margintext={Hi\\Mom!}]
        {This one appears in the margin of the document.}
\end{verbatim}

Here is another sticky note, the \texttt{Check}
\annotpro[color=yellowgreen,name=Check]{This is an example of a
note.\string\n\string\n We've created a blank line and started a new
paragraph.}.

\section{Stamp Annotations}


The \textsl{PDF Reference} lists several stamps that are guaranteed to exist, by any conforming PDF viewer.
This stamp  is one\smash{\raisebox{38pt}{\makebox[0pt][l]{\annotpro[type=stamp,name=Approved,widthTo=150bp,color=blue]{I give my stamp of approval!}}}} of
the standard stamps. A stamp is created by by putting \texttt{type=stamp} and by setting the
\texttt{name} key to the name of the stamp.

The stamp annotation does not obey the \texttt{nospace} keys, the same effect can be obtains using
various combinations of \cs{smash} and \cs{makebox}. The code for the stamp above is
\begin{verbatim}
    \smash{\makebox[0pt][l]{\raisebox{36pt}{
        \annotpro[type=stamp,name=Approved,widthTo=150bp,
            color=blue]{I give my stamp of approval!}}}}
\end{verbatim}
Did I forget to mention \cs{raisebox}? I needed that command keep the stamp from covering page content.
The \textsf{annot\_pro} package has a \texttt{preview} option. If used, the bounding rectangles of
the annotations can be viewed in a dvi previewer. This helped me to place the stamp through my dvi previewer.

Stamps can be re-scaled using \texttt{widthTo} (for re-scaling a stamp to a specified width), \texttt{heightTo} (for re-scaling to height),
or \texttt{scale} (for re-scaling using a re-scaling factor, for example, \texttt{scale=.5}).
For example, here is a stamp resize to 20bp width \annotpro[type=stamp,name=WordsTheBestJustGotBetter,widthTo=20bp,color=webbrown]{This package just got better!}.
This stamp is one of the ``extra'' stamps that are (sometimes) shipped with Acrobat, see the file \texttt{stamps.pdf} for a complete listing
of these extra stamps that ship with Acrobat.

Stamps can be placed in the margins,\annotpro[type=stamp,name=WordsTheBestJustGotBetter,margin,widthTo=20bp,color=webbrown]{This package just got better!}
but they probably need to be re-scaled to make them smaller; there are several keys that can be used for this purpose.
A key I've used several times already is \texttt{widthTo} (for re-scaling a stamp to a specified width), \texttt{heightTo} (for re-scaling to height),
and \texttt{scale} (for re-scaling using a re-scaling factor, for example, \texttt{scale=.5}).
\begin{verbatim}
        \annotpro[type=stamp,name=WordsTheBestJustGotBetter,
            widthTo=20bp,color=webbrown]{This package
                just got better!}
\end{verbatim}

Stamps are shipped with Acrobat (and some with Adobe Reader) in the form of PDF files. The PDF consist of
a series of template pages with one graphical image of a stamp per page. The standard stamps
reside in the file \texttt{Standard.pdf}.

Additional Stamps: The following stamps may be on your computer, when \textbf{Acrobat Pro} is installed. See the
file \texttt{stamps.pdf} for a complete listing of the stamps and their names.


\begin{itemize}
\item  \texttt{StandardBusiness.pdf}: A \annotpro[type=stamp,name=SBApproved,color=webbrown]{This package just got better!} stamp
\item  \texttt{SignHere.pdf}: A \annotpro[type=stamp,name=SHSignHere,color=webbrown]{This package just got better!} stamp
\item  \texttt{Dynamic.pdf}: A \annotpro[type=stamp,name=\#DApproved,widthTo=2in,color=webbrown]{This package just got better!} stamp
\item  \texttt{Words.pdf}: A \annotpro[type=stamp,name=WordsTheBestJustGotBetter,widthTo=30bp,color=webbrown]{This package just got better!} stamp
\item  \texttt{Faces.pdf}: A \annotpro[type=stamp,name=FacesWow,widthTo=30bp,color=webbrown]{This package just got better!} stamp
\item  \texttt{Pointers.pdf}: A \annotpro[type=stamp,name=PointersWhen,widthTo=100bp,color=webbrown]{This package just got better!} stamp
\end{itemize}
These stamps are representatives of the many stamps that reside in the referenced files. The dimensions of these
stamps are known by \textsf{annot\_pro} for these stamps. These can be resized using the \texttt{widthTo}, \texttt{heightTo}, or \texttt{scale}
keys.

Note that the names in the \texttt{Dynamic.pdf} file begin with the `\texttt{\#}' symbol. To reference these stamps, use
\verb!\#!, like so, \verb!name=\#DApproved!.

The bounding rectangle for the non-standard stamps---ones whose
dimensions are not known to this package---can be set using the
\texttt{width} and \texttt{height} keys, there are default values if
these keys are not specified.

The stamps provided by Acrobat can be rotated using the rotate key. For example, the stamp named
\texttt{PointersWhen} shown above, can be rotated 30 degrees, the stamp and the code are shown below.
\smash{\makebox[0pt][l]{\put(125,-15){\annotpro[type=stamp,name=PointersWhen,widthTo=50bp,rotate=30,color=webbrown]{Here is the code for this stamp.}}}}
\begin{verbatim}
    \smash{\makebox[0pt][l]{\put(130,-20){%
        \annotpro[type=stamp,name=PointersWhen,
            widthTo=50bp,rotate=30,color=webbrown
            ]{Here is the code for this stamp.}}}}
\end{verbatim}
See the file \texttt{stamps.tex} (and \texttt{stamps.pdf}) for a
complete list of these stamps, and their names.

\textbf{\textcolor{red}{Important:}} When using the stamps of
Acrobat, always perform a \textbf{SaveAs} on the file when you have finished
building the file. This imports the appearances of the stamps into
the document and saves them.


\section{File Attachment Annotations}

This is a file attachment \annotpro[type=fileattachment,file={\graphicsPath/AdobeDon.pdf},name=Paperclip]{The author of annot\_pro (ho, ho).}
which depicts the image of an average man. A file attachment is created with \texttt{type=fileattachment}; in addition,
a value of the file key must be set, here \verb!file={\graphicsPath/AdobeDon.pdf}!, where \cs{graphicsPath} is a command
that expands to the path to the folder holding \texttt{AdobeDon.pdf}. The definition of the path was made using
a special command, \cs{defineAPath}, in \texttt{annot\_pro}.

\end{document}

