pdfmarginpar update 0.9

git-svn-id: svn://tug.org/texlive/trunk@16102 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 131 insertions, 16 deletions

diff --git a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.pdf b/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.pdf
index 9e2d505b37f..b7149a88b37 100644
--- a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.pdf
+++ b/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.pdf
diff --git a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.tex b/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.tex
index d386db78475..18c101d5f4f 100644
--- a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.tex
+++ b/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginpar.tex
@@ -95,12 +95,12 @@
 
 \title{
 	Manual for Package \PDFMRG\\
-	{\small Version 0.8}}
+	{\small Version 0.9}}
 
 \begin{document}
 \maketitle
 \begin{abstract}%
-\PDFMRG\ provides the |\pdfmarginpar| command which is similar in spirit to |\marginpar|. However, it creates \pdf-annotations which can be viewed with Adobe Reader instead of normal text margins: small icons\pdfmarginpar[Comment]{As they are provided by the viewer application} indicate the in-text position where the message originates, popups provide detailed messages. The advantage over |\marginpar| is that bugfixes and communication is clearly visible together with its text source and the document as such is not obscured.
+\PDFMRG\ provides the |\pdfmarginpar| command which is similar in spirit to |\marginpar|. However, it creates \pdf-annotations which can be viewed with Adobe Reader instead of normal text margins: small icons\pdfmarginpar[Comment]{The viewer application supplies the small icons} indicate the in-text position where the message originates, popups provide detailed messages. The advantage over |\marginpar| is that bugfixes and communication is clearly visible together with its text source and the document as such is not obscured.
 \end{abstract}
 \tableofcontents
 \section{Introduction}
@@ -110,8 +110,10 @@ The package is also useful as communication device for articles written by multi
 
 \paragraph{Hint:} View this document in Adobe Reader as it contains several annotations.
 
+\paragraph{Hint:} Josef Kleber has incorporated ideas of this package into his newer package |pdfcomment|. As long as the Acrobat Reader can't edit \TeX\ annotations, I won't continue development on |pdfmarginpar|.
+
 \section{Installation and Requirements}
-The package is very small. In fact, it is nothing but a light-weight command which invokes the |pdflatex| primitive |\pdfannot| with a high-level user interface which encapsulates all supported \pdf\ annotation parameters with key-value options.
+The package is very small. It requires \pgfname\ 2.0 installed. In fact, it is nothing but a light-weight command which invokes the |pdflatex| primitive |\pdfannot| with a high-level user interface which encapsulates all supported \pdf\ annotation parameters with key-value options.
 
 Simply copy |pdfmarginpar.sty| somewhere into your \TeX\ search path (or the article's directory).
 
@@ -148,15 +150,15 @@ All options have a key prefix, |/pdfmarginpar/|. This prefix is optional (it has
 \begin{codeexample}[]
 \pdfmarginparset{Open=true,color={[0.5 0.5 0.5]}}
 
-This is an example already opened annotations with gray color
-\pdfmarginpar{This is an example already opened annotations with gray color.}.
+This is an example of already opened annotations with gray color
+\pdfmarginpar{This is an example of already opened annotations with gray color.}.
 \end{codeexample}
 	
 	It is \emph{not} necessary to prefix every option with |/pdfmarginpar/|, see above.
 \end{command}
 
 
-\begin{key}{/pdfmarginpar/Name=\mchoice{Comment,Key,Note,Help,NewParagraph,Paragraph,Insert} (initially Comment)}
+\begin{key}{/pdfmarginpar/Name=\mchoice{Comment,Key,Note,Help,NewParagraph,Paragraph,Insert,none} (initially Comment)}
 	Allows to choose a different type of annotation.
 \begin{codeexample}[] 
 Comment Annotation\pdfmarginpar[Comment]{Comment}\end{codeexample}
@@ -176,15 +178,19 @@ Annotation\pdfmarginpar[Paragraph]{Paragraph}\end{codeexample}
 Insert Annotation\pdfmarginpar[Insert]{Insert}\end{codeexample}
 
 If |Name=| is omitted, the annotation is chosen directly -- and some more style options take place. For example, the |Comment| annotation will be raised somewhat and the |Insert| Annotation will be moved somewhat. Using |Name=Comment| will just select the |Comment| annotation without any further modifications.
+
+Use the |none| value to disable this variable in the |.pdf|. This may be necessary for types different than Sticky Notes.
 \end{key}
 
-\begin{key}{/pdfmarginpar/Open=\mchoice{true,false} (initially false)}
+\begin{key}{/pdfmarginpar/Open=\mchoice{true,false} (initially true)}
 	Defines whether annotation popups shall be opened at start-up.
+
+	\paragraph{Attention:} Only opened popups will be printed!
 \end{key}
 
 \begin{keylist}{
-	/pdfmarginpar/C=\oarg{\meta{R} \meta{G} \meta{B}} (initially [1 0 0]),
-	/pdfmarginpar/color=\oarg{\meta{R} \meta{G} \meta{B}} (initially [1 0 0])}
+	/pdfmarginpar/C=\oarg{\meta{R} \meta{G} \meta{B}} (initially [1 1 0]),
+	/pdfmarginpar/color=\oarg{\meta{R} \meta{G} \meta{B}} (initially [1 1 0])}
 	Defines the annotation's color with \meta{R},\meta{G},\meta{B}$ \in [0,1]$.
 \end{keylist}
 
@@ -208,8 +214,73 @@ If |Name=| is omitted, the annotation is chosen directly -- and some more style
 \end{key}
 
 \begin{key}{/pdfmarginpar/Subtype=\marg{Type} (initially Text)}
-	This option is here for future developments. I intended only |Text| (although it should be possible to use any other supported |Subtype| as found in the pdf reference).
+	Currently, only |Text| is accepted.
+
+	Use	
+	
+	|\pdfmarginpar[Subtype/Other=|\meta{pdf name}|]|\marg{$\dotsc$}
+
+	to supply unsupported sub types.\pdfmarginpar[Name=none,Subtype=FreeText]{ZEUG!}
+\end{key}
+
+\begin{key}{/pdfmarginpar/caption=\marg{text caption} (initially Author's Note)}
+	Sets a caption.
+\end{key}
+
+\begin{key}{/pdfmarginpar/width=\marg{dimen} (initially empty)}
+	Defines a width for an annotation. This is not necessary for sticky notes.
+\begin{codeexample}[width=2cm]
+\pdfmarginpar[Subtype=FreeText,width=4cm,height=0.5cm]
+	{A free text.}
+\end{codeexample}
+	Please note that the |\pdfmarginpar| won't occupy any space in the final document -- |width| refers only to the appearance of the annotation.
+
+	Use can use |hoffset| and |voffset| to move the annotation around (relative to the occurance of |\pdfmarginpar| in the document). However, it may be better to use the |textpos| package for absolute positioning on the page.
+\begin{codeexample}[width=2cm]
+\pdfmarginpar[Subtype=FreeText,width=4cm,height=2cm,hoffset=9cm,voffset=-5cm]
+	{A free text, shifted relatively to the occurance of pdfmarginpar.}
+Here comes the marginpar!
+\end{codeexample}
+\end{key}
+
+\begin{key}{/pdfmarginpar/height=\marg{dimen} (initially empty)}
+	Defines a height for an annotation. See |width|.
 \end{key}
+\begin{key}{/pdfmarginpar/depth=\marg{dimen} (initially empty)}
+	Defines a depth for an annotation. See |width|.
+\end{key}
+
+
+\subsection{Printing Popups and Comments}
+Adobe Reader \emph{can} print both free texts and popups. The feature can be accesses using ``File $\gg$ Print: Comments and Forms = Document and Markups''. 
+
+To print popups, you need to configure Adobe Reader using ``Edit $\gg$ Preferences $\gg$ Commenting'' where the corresponding option needs to be set. Unfortunately, this option does not exist in many reader versions.
+
+If it does not exist, the only possibility to activate it is to patch the configuration of Adobe Reader.
+
+\begin{description}
+	\item[For Windows,]
+ the registry need to be changed. Please note that this is at your own risk.
+
+For Reader 6 or 7, open the registry editor and browse to the following key:
+
+|HKEY_CURRENT_USER\Software\ADOBE\Acrobat Reader\6.0| (or |7.0| or |8.0|)|\Annots\cPrefs|
+
+Double click the |bprintCommentPopups| key and change the value to |1|.
+
+For Adobe Reader 8, the same key needs to be changed to 
+
+|HKEY_CURRENT_USER\Software\Adobe\Acrobat Reader\8.0\Annots\cPrefs|
+
+|"bprintCommentPopups"=dword:00000001|.
+	\item[For Linux,]
+edit
+
+|~/.adobe/Acrobat/8.0/Preferences/reader_prefs| 
+
+with a text editor and change |/printCommentPopups [/b false]| to |/printCommentPopups [/b true]|.
+\end{description}
+Please note that only opened popups will be printed.
 
 \subsection{Implementation note}
 All these variables boil down to the |pdflatex| primitive
diff --git a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginparexample.pdf b/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginparexample.pdf
deleted file mode 100644
index a34328f162f..00000000000
--- a/Master/texmf-dist/doc/latex/pdfmarginpar/pdfmarginparexample.pdf
+++ /dev/null
diff --git a/Master/texmf-dist/tex/latex/pdfmarginpar/pdfmarginpar.sty b/Master/texmf-dist/tex/latex/pdfmarginpar/pdfmarginpar.sty
index 6dfaf05324a..eab76a03b5f 100644
--- a/Master/texmf-dist/tex/latex/pdfmarginpar/pdfmarginpar.sty
+++ b/Master/texmf-dist/tex/latex/pdfmarginpar/pdfmarginpar.sty
@@ -36,7 +36,7 @@
 % along with this program.  If not, see <http://www.gnu.org/licenses/>.
 %
 %--------------------------------------------
-\ProvidesPackage{pdfmarginpar}[2008/09/21 Version 0.8]
+\ProvidesPackage{pdfmarginpar}[2009/10/13 Version 0.9]
 
 \RequirePackage{pgfkeys}
 
@@ -45,15 +45,24 @@
 \pgfqkeys{/pdfmarginpar}{
 	Subtype/.is choice,
 	Subtype/Text/.code={\def\pdfmarginpar@SubType{/Text}},
+	Subtype/FreeText/.code={\def\pdfmarginpar@SubType{/FreeText}\pgfkeysalso{Name=none}},
+	Subtype/Other/.code={\def\pdfmarginpar@SubType{/#1}},
 	Subtype=Text,
 	Open/.is choice,
 	Open/true/.code={\def\pdfmarginpar@OPEN{true}},
 	Open/false/.code={\def\pdfmarginpar@OPEN{false}},
-	Open=false,
+	Open=true,
+	FreeText/.style={Subtype/FreeText},
+	%
+	caption/.code={\def\pdfmarginpar@textlabel{#1}},
 	%
 	voffset/.initial=0pt,
 	hoffset/.initial=0pt,
 	%
+	width/.initial=,
+	height/.initial=,
+	depth/.initial=,
+	%
 	Name/.is choice,
 	Name/Comment/.code={\def\pdfmarginpar@NAME{/Comment}},
 	Name/Key/.code={\def\pdfmarginpar@NAME{/Key}},
@@ -62,6 +71,7 @@
 	Name/NewParagraph/.code={\def\pdfmarginpar@NAME{/NewParagraph}},
 	Name/Paragraph/.code={\def\pdfmarginpar@NAME{/Paragraph}},
 	Name/Insert/.code={\def\pdfmarginpar@NAME{/Insert}},
+	Name/none/.code={\def\pdfmarginpar@NAME{}},
 	%
 	Comment/.style={Name=Comment,voffset=1.3\baselineskip},
 	Key/.style={Name=Key,voffset=\baselineskip},
@@ -70,15 +80,17 @@
 	Paragraph/.style={Name=Paragraph,voffset=\baselineskip},
 	Insert/.style={Name=Insert,voffset=0pt,hoffset=-1.5ex},
 	NewParagraph/.style={Name=NewParagraph,voffset=0pt,hoffset=-1.5ex,CA=0.7},
+	none/.style={},
 	%
 	Comment,
-	C/.initial={[1 0 0]},
+	C/.initial={[1 1 0]},
 	color/.style={C={#1}},
 	CA/.initial=0.5,
 	opacity/.style={CA={#1}},
 	Subj/.store in=\pdfmarginpar@Subj,
 	Subject/.style={Subj={#1}},
 	Subj={Comment},
+	caption=Author's Note,
 }
 
 % Usage:
@@ -89,27 +101,59 @@
 	\pgfqkeys{/pdfmarginpar}{#1}%
 	\toks0={#2}%
 	\toks1=\expandafter{\pdfmarginpar@Subj}%
+	\toks2=\expandafter{\pdfmarginpar@textlabel}%
 	\pgfkeysgetvalue{/pdfmarginpar/voffset}\pdfmarginpar@voffset
 	\pgfkeysgetvalue{/pdfmarginpar/hoffset}\pdfmarginpar@hoffset
+	\pgfkeysgetvalue{/pdfmarginpar/width}\pdfmarginpar@wd
+	\pgfkeysgetvalue{/pdfmarginpar/height}\pdfmarginpar@ht
+	\pgfkeysgetvalue{/pdfmarginpar/depth}\pdfmarginpar@dp
+	\def\pdfmarginpar@rulespec{}%
+	\ifx\pdfmarginpar@wd\pgfutil@empty
+	\else
+		\expandafter\def\expandafter\pdfmarginpar@rulespec\expandafter{%
+			\pdfmarginpar@rulespec
+			width \pdfmarginpar@wd\space
+		}%
+	\fi
+	\ifx\pdfmarginpar@ht\pgfutil@empty
+	\else
+		\expandafter\def\expandafter\pdfmarginpar@rulespec\expandafter{%
+			\pdfmarginpar@rulespec
+			height \pdfmarginpar@ht\space
+		}%
+	\fi
+	\ifx\pdfmarginpar@dp\pgfutil@empty
+	\else
+		\expandafter\def\expandafter\pdfmarginpar@rulespec\expandafter{%
+			\pdfmarginpar@rulespec
+			depth \pdfmarginpar@dp\space
+		}%
+	\fi
+	%
 	%\ifvmode\noindent\fi
 	\vbox to 0pt{\hsize=0pt
-		\vss
 		\noindent
 		\raise\pdfmarginpar@voffset
 		\hbox to 0pt{\vsize=0pt%
 			\hskip\pdfmarginpar@hoffset
-			\pdfannot {
+			\expandafter\pdfannot \pdfmarginpar@rulespec {
 				/Subtype	\pdfmarginpar@SubType
 				/Open		\pdfmarginpar@OPEN
-				/Name		\pdfmarginpar@NAME
+				\ifx\pdfmarginpar@NAME\pgfutil@empty
+				\else
+					/Name		\pdfmarginpar@NAME
+				\fi
+				/T			(\the\toks2)
 				/C			\pgfkeysvalueof{/pdfmarginpar/C}
 				/CA			\pgfkeysvalueof{/pdfmarginpar/CA}
 				/Subj		(\the\toks1)
 				/Contents	(\the\toks0)
+				/F 4 % print it!
 			}%
 			\hss
 		}%
 		%\hss
+		\vss
 	}%
 }}%